GitHub

key_format

API reference for key_format.

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

Values

AttributeTypeDescription
spkiFormat[Literal['public'], Direction, bytes]
pkcs8Format[Literal['private'], Direction, bytes]
jwkFormat[Role, Direction, JsonWebKey]
pkcs1Format[Literal['private'], Literal['decode'], bytes]

RSA private keys (RFC 8017), read only.

sec1Format[Literal['private'], Literal['decode'], bytes]

EC private keys (RFC 5915), read only; they must include the public point.

Types

TypeDefinitionDescription
Roletype Role = Literal['public', 'private', 'secret']
Directiontype Direction = Literal['decode', 'encode']
AsymmetricAlgorithmtype AsymmetricAlgorithm = signature_module.Algorithm | key_agreement.Algorithm | key_wrap.RsaOaep
PublicKeytype PublicKey = signature_module.PublicKey[Any] | key_agreement.PublicKey[Any] | key_wrap.PublicKey[Any]
PrivateKeytype PrivateKey = signature_module.PrivateKey[Any] | key_agreement.PrivateKey[Any] | key_wrap.PrivateKey[Any]
Keytype Key = PublicKey | PrivateKey | SecretKey

Classes

Functions

pem

pem[R, D](format) -> Format[R, D, str]

format as a PEM block.

ParameterTypeDescription
formatFormat[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.

ParameterTypeDescription
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.

ParameterTypeDescription
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.

ParameterTypeDescription
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.

ParameterTypeDescription
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