Reading and writing keys in standard formats (Effect's
effect/crypto/KeyFormat)::
public_key = yield from decode_public(pem(spki), signature.ecdsa_p256, pem_text)
jwk_dict = yield from encode(jwk, private_key)Public keys: spki and jwk. Private keys: pkcs8 and jwk,
and read-only pkcs1 (RSA) and sec1 (EC). Secret keys: jwk
only. pem(format) wraps a DER format in a PEM block with the format's
label. A format's roles and directions are in its type, so writing a
secret key as SPKI is a type error. A JWK's kty, crv and alg
must match the algorithm; use, key_ops and ext are dropped
before importing. Reading uses the WebCrypto reference.
Re-exports#
- From
pyfect.crypto.crypto_error:CryptoError - From
pyfect.crypto.key_wrap:SecretAlgorithm,SecretKey - From
pyfect.crypto.web_crypto:JsonWebKey
Values#
| Attribute | Type | Description |
|---|---|---|
spki | Format[Literal['public'], Direction, bytes] | |
pkcs8 | Format[Literal['private'], Direction, bytes] | |
jwk | Format[Role, Direction, JsonWebKey] | |
pkcs1 | Format[Literal['private'], Literal['decode'], bytes] | RSA private keys (RFC 8017), read only. |
sec1 | Format[Literal['private'], Literal['decode'], bytes] | EC private keys (RFC 5915), read only; they must include the public point. |
Types#
| Type | Definition | Description |
|---|---|---|
Role | type Role = Literal['public', 'private', 'secret'] | |
Direction | type Direction = Literal['decode', 'encode'] | |
AsymmetricAlgorithm | type AsymmetricAlgorithm = signature_module.Algorithm | key_agreement.Algorithm | key_wrap.RsaOaep | |
PublicKey | type PublicKey = signature_module.PublicKey[Any] | key_agreement.PublicKey[Any] | key_wrap.PublicKey[Any] | |
PrivateKey | type PrivateKey = signature_module.PrivateKey[Any] | key_agreement.PrivateKey[Any] | key_wrap.PrivateKey[Any] | |
Key | type Key = PublicKey | PrivateKey | SecretKey |
Classes#
Functions#
pem#
pem[R, D](format) -> Format[R, D, str]format as a PEM block.
| Parameter | Type | Description |
|---|---|---|
format | Format[R, D, bytes] |
Returns Format[R, D, str]
def pem[R, D](format: Format[R, D, bytes]) -> Format[R, D, str]:
"""``format`` as a PEM block."""
return Format(format.tag, pem=True)decode_public#
decode_public[A: signature_module.Algorithm, Data](format: Format[Literal['public'], Literal['decode'], Data], algorithm: A, data: Data) -> Effect[signature_module.PublicKey[A], CryptoError]
decode_public[A: key_agreement.Algorithm, Data](format: Format[Literal['public'], Literal['decode'], Data], algorithm: A, data: Data) -> Effect[key_agreement.PublicKey[A], CryptoError]
decode_public[A: key_wrap.RsaOaep, Data](format: Format[Literal['public'], Literal['decode'], Data], algorithm: A, data: Data) -> Effect[key_wrap.PublicKey[A], CryptoError]
decode_public[Data](format: Format[Literal['public'], Literal['decode'], Data], algorithm: AsymmetricAlgorithm, data: Data) -> Effect[PublicKey, CryptoError]A public key from SPKI or a JWK, checked by importing it.
| Parameter | Type | Description |
|---|---|---|
format | ||
algorithm | ||
data |
@overload
def decode_public[A: signature_module.Algorithm, Data](
format: Format[Literal["public"], Literal["decode"], Data], algorithm: A, data: Data
) -> Effect[signature_module.PublicKey[A], CryptoError]: ...
@overload
def decode_public[A: key_agreement.Algorithm, Data](
format: Format[Literal["public"], Literal["decode"], Data], algorithm: A, data: Data
) -> Effect[key_agreement.PublicKey[A], CryptoError]: ...
@overload
def decode_public[A: key_wrap.RsaOaep, Data](
format: Format[Literal["public"], Literal["decode"], Data], algorithm: A, data: Data
) -> Effect[key_wrap.PublicKey[A], CryptoError]: ...
@overload
def decode_public[Data](
format: Format[Literal["public"], Literal["decode"], Data],
algorithm: AsymmetricAlgorithm,
data: Data,
) -> Effect[PublicKey, CryptoError]: ...
def decode_public(
format: Format[Any, Any, Any], algorithm: AsymmetricAlgorithm, data: object
) -> Effect[Any, CryptoError]:
"""A public key from SPKI or a JWK, checked by importing it."""
return _decode_asymmetric("decodePublic", "public", format, algorithm, data)decode_private#
decode_private[A: signature_module.Algorithm, Data](format: Format[Literal['private'], Literal['decode'], Data], algorithm: A, data: Data) -> Effect[signature_module.PrivateKey[A], CryptoError]
decode_private[A: key_agreement.Algorithm, Data](format: Format[Literal['private'], Literal['decode'], Data], algorithm: A, data: Data) -> Effect[key_agreement.PrivateKey[A], CryptoError]
decode_private[A: key_wrap.RsaOaep, Data](format: Format[Literal['private'], Literal['decode'], Data], algorithm: A, data: Data) -> Effect[key_wrap.PrivateKey[A], CryptoError]
decode_private[Data](format: Format[Literal['private'], Literal['decode'], Data], algorithm: AsymmetricAlgorithm, data: Data) -> Effect[PrivateKey, CryptoError]A private key from PKCS#8, PKCS#1, SEC1 or a JWK, checked by importing it.
| Parameter | Type | Description |
|---|---|---|
format | ||
algorithm | ||
data |
@overload
def decode_private[A: signature_module.Algorithm, Data](
format: Format[Literal["private"], Literal["decode"], Data], algorithm: A, data: Data
) -> Effect[signature_module.PrivateKey[A], CryptoError]: ...
@overload
def decode_private[A: key_agreement.Algorithm, Data](
format: Format[Literal["private"], Literal["decode"], Data], algorithm: A, data: Data
) -> Effect[key_agreement.PrivateKey[A], CryptoError]: ...
@overload
def decode_private[A: key_wrap.RsaOaep, Data](
format: Format[Literal["private"], Literal["decode"], Data], algorithm: A, data: Data
) -> Effect[key_wrap.PrivateKey[A], CryptoError]: ...
@overload
def decode_private[Data](
format: Format[Literal["private"], Literal["decode"], Data],
algorithm: AsymmetricAlgorithm,
data: Data,
) -> Effect[PrivateKey, CryptoError]: ...
def decode_private(
format: Format[Any, Any, Any], algorithm: AsymmetricAlgorithm, data: object
) -> Effect[Any, CryptoError]:
"""A private key from PKCS#8, PKCS#1, SEC1 or a JWK, checked by
importing it."""
return _decode_asymmetric("decodePrivate", "private", format, algorithm, data)decode_secret#
decode_secret[A: aead.Algorithm, Data](format: Format[Literal['secret'], Literal['decode'], Data], algorithm: A, data: Data) -> Effect[aead.Key[A], CryptoError]
decode_secret[A: cipher.Algorithm, Data](format: Format[Literal['secret'], Literal['decode'], Data], algorithm: A, data: Data) -> Effect[cipher.Key[A], CryptoError]
decode_secret[A: mac.Algorithm, Data](format: Format[Literal['secret'], Literal['decode'], Data], algorithm: A, data: Data) -> Effect[mac.Key[A], CryptoError]
decode_secret[A: key_wrap.AesKw, Data](format: Format[Literal['secret'], Literal['decode'], Data], algorithm: A, data: Data) -> Effect[key_wrap.Key[A], CryptoError]A secret key from a JWK's k.
| Parameter | Type | Description |
|---|---|---|
format | ||
algorithm | ||
data |
@overload
def decode_secret[A: aead.Algorithm, Data](
format: Format[Literal["secret"], Literal["decode"], Data], algorithm: A, data: Data
) -> Effect[aead.Key[A], CryptoError]: ...
@overload
def decode_secret[A: cipher.Algorithm, Data](
format: Format[Literal["secret"], Literal["decode"], Data], algorithm: A, data: Data
) -> Effect[cipher.Key[A], CryptoError]: ...
@overload
def decode_secret[A: mac.Algorithm, Data](
format: Format[Literal["secret"], Literal["decode"], Data], algorithm: A, data: Data
) -> Effect[mac.Key[A], CryptoError]: ...
@overload
def decode_secret[A: key_wrap.AesKw, Data](
format: Format[Literal["secret"], Literal["decode"], Data], algorithm: A, data: Data
) -> Effect[key_wrap.Key[A], CryptoError]: ...
def decode_secret(
format: Format[Any, Any, Any], algorithm: SecretAlgorithm, data: object
) -> Effect[Any, CryptoError]:
"""A secret key from a JWK's ``k``."""
def go() -> Effect[Any, CryptoError]:
if format.tag != "jwk":
return _invalid_key("decodeSecret", "Secret keys are only read from JWK")
checked = _check_jwk(data, algorithm, "secret")
if isinstance(checked, str):
return _invalid_key("decodeSecret", checked)
decoded = base64_url_decode(checked.get("k", ""))
if isinstance(decoded, Err):
return _invalid_key("decodeSecret", "The JWK k member is not valid base64url")
return key_wrap.secret_key(algorithm, decoded.value).catch_all(
_web.rehome("KeyFormat", "decodeSecret")
)
return suspend(go)encode#
encode[Data](format: Format[Literal['public'], Literal['encode'], Data], key: PublicKey) -> Effect[Data, CryptoError]
encode[Data](format: Format[Literal['private'], Literal['encode'], Data], key: PrivateKey) -> Effect[Data, CryptoError]
encode[Data](format: Format[Literal['secret'], Literal['encode'], Data], key: SecretKey) -> Effect[Data, CryptoError]key in format; NotExtractable for a non-extractable
CryptoKey.
| Parameter | Type | Description |
|---|---|---|
format | ||
key |
@overload
def encode[Data](
format: Format[Literal["public"], Literal["encode"], Data], key: PublicKey
) -> Effect[Data, CryptoError]: ...
@overload
def encode[Data](
format: Format[Literal["private"], Literal["encode"], Data], key: PrivateKey
) -> Effect[Data, CryptoError]: ...
@overload
def encode[Data](
format: Format[Literal["secret"], Literal["encode"], Data], key: SecretKey
) -> Effect[Data, CryptoError]: ...
def encode(format: Format[Any, Any, Any], key: Key) -> Effect[Any, CryptoError]:
"""``key`` in ``format``; ``NotExtractable`` for a non-extractable
``CryptoKey``."""
family = _family_of(key.algorithm)
encoded: Effect[bytes | JsonWebKey, CryptoError]
if family is not None:
encoded = _encode_asymmetric(format, cast("PublicKey | PrivateKey", key), family)
elif format.tag != "jwk":
encoded = _invalid_key("encode", "Secret keys are only written as JWK")
else:
encoded = (
key_wrap.secret_to_bytes(cast("SecretKey", key))
.catch_all(_web.rehome("KeyFormat", "encode"))
.map(lambda data: JsonWebKey(kty="oct", k=base64_url_encode(data)))
)
if format.pem:
return encoded.map(lambda der: _to_pem(_LABELS[format.tag], cast("bytes", der)))
return encoded