GitHub

key_wrap

API reference for key_wrap.

Key wrapping as a service (Effect's effect/crypto/KeyWrap)::

key_wrap = yield from KeyWrap()
kek = yield from key_wrap.generate_key(aes256_kw)
wrapped = yield from key_wrap.wrap(kek, data_key)
restored = yield from key_wrap.unwrap(kek, aead.aes256_gcm, wrapped)

AES-KW (RFC 3394) wraps with a secret key; RSA-OAEP wraps with a public key and unwraps with the private one. Any secret key of mac, aead, cipher or this module can be wrapped; unwrap gives a key of the algorithm asked for. A wrapped key that fails to unwrap fails with DecryptionFailed.

Re-exports

Values

AttributeTypeDescription
aes128_kwAesKw
aes256_kwAesKw
rsa_oaep_sha256RsaOaep
rsa_oaep_sha1RsaOaep

RSA-OAEP with SHA-1, for protocols that require it (JWE RSA-OAEP).

familyFamily
layer_web_cryptoLayer[KeyWrap, Never, SecureRandom]

AES-KW and RSA-OAEP on the WebCrypto reference.

Types

TypeDefinitionDescription
Algorithmtype Algorithm = AesKw | RsaOaep
WrapKeytype WrapKey = Key[Any] | PublicKey[Any]
UnwrapKeytype UnwrapKey = Key[Any] | PrivateKey[Any]
SecretAlgorithmtype SecretAlgorithm = mac.Algorithm | aead.Algorithm | cipher.Algorithm | AesKw
SecretKeytype SecretKey = mac.Key[Any] | aead.Key[Any] | cipher.Key[Any] | Key[Any]

Classes

Functions

rsa_oaep

rsa_oaep(*, hash, modulus_length) -> RsaOaep
ParameterTypeDescription
hashDigestAlgorithm
modulus_lengthint

Returns RsaOaep

def rsa_oaep(*, hash: DigestAlgorithm, modulus_length: int) -> RsaOaep:
    return RsaOaep(name=f"rsaOaep{name_suffix(hash)}", hash=hash, modulus_length=modulus_length)

is_key

is_key(u) -> bool
ParameterTypeDescription
uobject

Returns bool

def is_key(u: object) -> bool:
    return isinstance(u, Key)

is_private_key

is_private_key(u) -> bool
ParameterTypeDescription
uobject

Returns bool

def is_private_key(u: object) -> bool:
    return isinstance(u, PrivateKey)

is_public_key

is_public_key(u) -> bool
ParameterTypeDescription
uobject

Returns bool

def is_public_key(u: object) -> bool:
    return isinstance(u, PublicKey)

secret_key

secret_key(algorithm, data) -> Effect[SecretKey, CryptoError]

A secret key of algorithm's family from its bytes.

ParameterTypeDescription
algorithmSecretAlgorithm
dataBinary

Returns Effect[SecretKey, CryptoError]

def secret_key(algorithm: SecretAlgorithm, data: Binary) -> Effect[SecretKey, CryptoError]:
    """A secret key of ``algorithm``'s family from its bytes."""
    match algorithm:
        case aead.Algorithm():
            return aead.key(algorithm, data)
        case cipher.Algorithm():
            return cipher.key(algorithm, data)
        case AesKw():
            return key(algorithm, data)
        case mac.Algorithm():
            return mac.key(algorithm, data)

secret_to_bytes

secret_to_bytes(secret) -> Effect[bytes, CryptoError]

A secret key's bytes, through its own family.

ParameterTypeDescription
secretSecretKey

Returns Effect[bytes, CryptoError]

def secret_to_bytes(secret: SecretKey) -> Effect[bytes, CryptoError]:
    """A secret key's bytes, through its own family."""
    match secret:
        case aead.Key():
            return aead.to_bytes(secret)
        case cipher.Key():
            return cipher.to_bytes(secret)
        case Key():
            return to_bytes(secret)
        case mac.Key():
            return mac.to_bytes(secret)

key

key[A: AesKw](algorithm, data) -> Effect[Key[A], CryptoError]

An AES-KW key holding a copy of data, of the algorithm's length.

ParameterTypeDescription
algorithmA
dataBinary

Returns Effect[Key[A], CryptoError]

def key[A: AesKw](algorithm: A, data: Binary) -> Effect[Key[A], CryptoError]:
    """An AES-KW key holding a copy of ``data``, of the algorithm's length."""
    return _key.from_bytes(
        lambda copied: Key(algorithm, copied),
        "KeyWrap",
        "key",
        data,
        _key.check_key_length(algorithm.name, algorithm.key_length),
    )

from_crypto_key

from_crypto_key[A: AesKw](algorithm, crypto_key) -> Effect[Key[A], CryptoError]
ParameterTypeDescription
algorithmA
crypto_keyCryptoKey

Returns Effect[Key[A], CryptoError]

def from_crypto_key[A: AesKw](algorithm: A, crypto_key: CryptoKey) -> Effect[Key[A], CryptoError]:
    return _key.from_crypto_key(
        Key,
        "KeyWrap",
        "fromCryptoKey",
        algorithm,
        crypto_key,
        _key.ExpectedCryptoKey(
            type="secret",
            name="AES-KW",
            usages=("wrapKey", "unwrapKey"),
            usage_policy="all",
            check=_key.check_aes_length("AES-KW", algorithm.key_length),
        ),
    )

private_key_from_crypto_key

private_key_from_crypto_key[A: RsaOaep](algorithm, crypto_key) -> Effect[PrivateKey[A], CryptoError]
ParameterTypeDescription
algorithmA
crypto_keyCryptoKey

Returns Effect[PrivateKey[A], CryptoError]

def private_key_from_crypto_key[A: RsaOaep](
    algorithm: A, crypto_key: CryptoKey
) -> Effect[PrivateKey[A], CryptoError]:
    return _rsa_from_crypto_key(
        "privateKeyFromCryptoKey", PrivateKey, algorithm, "private", crypto_key
    )

public_key_from_crypto_key

public_key_from_crypto_key[A: RsaOaep](algorithm, crypto_key) -> Effect[PublicKey[A], CryptoError]
ParameterTypeDescription
algorithmA
crypto_keyCryptoKey

Returns Effect[PublicKey[A], CryptoError]

def public_key_from_crypto_key[A: RsaOaep](
    algorithm: A, crypto_key: CryptoKey
) -> Effect[PublicKey[A], CryptoError]:
    return _rsa_from_crypto_key(
        "publicKeyFromCryptoKey", PublicKey, algorithm, "public", crypto_key
    )

to_bytes

to_bytes(key) -> Effect[bytes, CryptoError]
ParameterTypeDescription
keyKey[Any] | PrivateKey[Any] | PublicKey[Any]

Returns Effect[bytes, CryptoError]

def to_bytes(key: Key[Any] | PrivateKey[Any] | PublicKey[Any]) -> Effect[bytes, CryptoError]:
    if isinstance(key, Key):
        return _key.to_bytes("KeyWrap", key, _key.export_raw)
    return _asymmetric.to_bytes(family, key)