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#
| Attribute | Type | Description |
|---|---|---|
aes128_gcm | AesGcm | |
aes256_gcm | AesGcm | |
chacha20_poly1305 | Algorithm | |
xchacha20_poly1305 | Algorithm | |
layer_web_crypto | Layer[Aead, Never, SecureRandom] | AES-GCM on the |
Types#
| Type | Definition | Description |
|---|---|---|
Name | type Name = Literal['aes128Gcm', 'aes256Gcm', 'chacha20Poly1305', 'xchacha20Poly1305'] |
Classes#
Functions#
is_key#
is_key(u) -> bool| Parameter | Type | Description |
|---|---|---|
u | object |
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.
| Parameter | Type | Description |
|---|---|---|
implementations | dict[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.
| Parameter | Type | Description |
|---|---|---|
algorithm | A | |
data | Binary |
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.
| Parameter | Type | Description |
|---|---|---|
algorithm | A | |
crypto_key | CryptoKey |
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.
| Parameter | Type | Description |
|---|---|---|
key | Key[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)