GitHub

API reference for aead.

Authenticated encryption as a service (Effect's effect/crypto/Aead)::

aead = yield from Aead()
key = yield from aead.generate_key(aes256_gcm)
sealed = yield from aead.encrypt(key, plaintext, nonce=nonce, aad=header)
opened = yield from aead.decrypt(key, sealed, nonce=nonce, aad=header)

The ciphertext ends with its 16-byte tag. Every argument is checked when the effect runs, before any work; a decryption that fails for any reason (tag, AAD, ciphertext, a too-short input) fails with the same DecryptionFailed. AES-GCM runs on the WebCrypto reference; ChaCha20-Poly1305 (cryptography) and XChaCha20-Poly1305 (PyNaCl, both in the crypto extra) run in the process. Never reuse a nonce with a key.

Re-exports

Values

AttributeTypeDescription
aes128_gcmAesGcm
aes256_gcmAesGcm
chacha20_poly1305Algorithm
xchacha20_poly1305Algorithm
layer_web_cryptoLayer[Aead, Never, SecureRandom]

AES-GCM on the WebCrypto reference, ChaCha in the process.

Types

TypeDefinitionDescription
Nametype Name = Literal['aes128Gcm', 'aes256Gcm', 'chacha20Poly1305', 'xchacha20Poly1305']

Classes

Functions

is_key

is_key(u) -> bool
ParameterTypeDescription
uobject

Returns bool

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

layer_web_crypto_with

layer_web_crypto_with(*, implementations=None) -> Layer[Aead, Never, SecureRandom]

layer_web_crypto, running implementations (by algorithm name) for byte-backed keys; CryptoKey-backed keys stay on subtle.

ParameterTypeDescription
implementationsdict[Name, Implementation] | None = None

Returns Layer[Aead, Never, SecureRandom]

def layer_web_crypto_with(
    *, implementations: dict[Name, Implementation] | None = None
) -> Layer[Aead, Never, SecureRandom]:
    """``layer_web_crypto``, running ``implementations`` (by algorithm name)
    for byte-backed keys; ``CryptoKey``-backed keys stay on ``subtle``."""

    @gen
    def build():
        random = yield from SecureRandom()
        crypto = yield from WebCrypto()
        service: AeadService = _WebCryptoAead(random, crypto, implementations)
        return service

    return layer_effect(Aead, build)

key

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

A key holding a copy of data, which must be the algorithm's key length.

ParameterTypeDescription
algorithmA
dataBinary

Returns Effect[Key[A], CryptoError]

def key[A: Algorithm](algorithm: A, data: Binary) -> Effect[Key[A], CryptoError]:
    """A key holding a copy of ``data``, which must be the algorithm's key
    length."""
    return _key.from_bytes(
        lambda copied: Key(algorithm, copied),
        "Aead",
        "key",
        data,
        _key.check_key_length(algorithm.name, algorithm.key_length),
    )

from_crypto_key

from_crypto_key[A: AesGcm](algorithm, crypto_key) -> Effect[Key[A], CryptoError]

A key backed by an AES-GCM CryptoKey of the algorithm's size, with both the encrypt and decrypt usages.

ParameterTypeDescription
algorithmA
crypto_keyCryptoKey

Returns Effect[Key[A], CryptoError]

def from_crypto_key[A: AesGcm](algorithm: A, crypto_key: CryptoKey) -> Effect[Key[A], CryptoError]:
    """A key backed by an AES-GCM ``CryptoKey`` of the algorithm's size,
    with both the ``encrypt`` and ``decrypt`` usages."""
    if algorithm.implementation is not None:
        return _web.invalid_key(
            "Aead", "fromCryptoKey", f"{algorithm.name} keys cannot be CryptoKeys"
        )
    return _key.from_crypto_key(
        Key,
        "Aead",
        "fromCryptoKey",
        algorithm,
        crypto_key,
        _key.ExpectedCryptoKey(
            type="secret",
            name="AES-GCM",
            usages=("encrypt", "decrypt"),
            usage_policy="all",
            check=_key.check_aes_length("AES-GCM", algorithm.key_length),
        ),
    )

to_bytes

to_bytes(key) -> Effect[bytes, CryptoError]

A copy of the key's bytes; NotExtractable for a non-extractable CryptoKey.

ParameterTypeDescription
keyKey[Any]

Returns Effect[bytes, CryptoError]

def to_bytes(key: Key[Any]) -> Effect[bytes, CryptoError]:
    """A copy of the key's bytes; ``NotExtractable`` for a non-extractable
    ``CryptoKey``."""
    return _key.to_bytes("Aead", key, _key.export_raw)