GitHub

API reference for jwe.

Compact JSON Web Encryption with a shared key (Effect's effect/jose/Jwe): alg dir and enc A256GCM only::

token = yield from jwe.encrypt(b"hello", dir_key, {"cty": "text/plain"})
decrypted = yield from jwe.decrypt(token, dir_key)

decrypt takes the key, or a function choosing it from the protected header (by kid), called only once the token is well formed. The crit and zip header parameters are refused.

Re-exports

Values

AttributeTypeDescription
ProtectedHeaderSchemaStructWithRestSchema[ProtectedHeader, Never, Never]

Types

TypeDefinitionDescription
Headertype Header = Mapping[str, JsonValue]

Protected header members besides the fixed ones (alg, enc), which always win. kid defaults to the key's (also when None); a typ or cty of None is left out.

Classes

Functions

encrypt

encrypt(plaintext, key, header=None) -> Effect[Redacted[str], JoseError, Aead | SecureRandom]

A compact JWE of plaintext with a random IV; alg and enc are always dir and A256GCM.

ParameterTypeDescription
plaintextbytes
keyDirKey
headerHeader | None = None

Returns Effect[Redacted[str], JoseError, Aead | SecureRandom]

def encrypt(
    plaintext: bytes, key: DirKey, header: Header | None = None
) -> Effect[Redacted[str], JoseError, Aead | SecureRandom]:
    """A compact JWE of ``plaintext`` with a random IV; ``alg`` and ``enc``
    are always ``dir`` and ``A256GCM``."""

    @gen
    def body():
        protected_header = yield from encode_header(
            {"alg": "dir", "enc": "A256GCM"}, key.kid, header, _UNSUPPORTED
        )
        random = yield from SecureRandom()
        service = yield from Aead()
        nonce = yield from random.random_bytes(_NONCE_LENGTH)
        sealed = yield from service.encrypt(
            key.key, plaintext, nonce=nonce, aad=utf8(protected_header)
        ).map_error(crypto_failure("Could not encrypt with the key"))
        ciphertext = base64_url_encode(sealed[:-_TAG_LENGTH])
        tag = base64_url_encode(sealed[-_TAG_LENGTH:])
        return redacted(f"{protected_header}..{base64_url_encode(nonce)}.{ciphertext}.{tag}")

    return body

decrypt

decrypt(token: Token, key: DirKey) -> Effect[Decrypted, JoseError, Aead]
decrypt[E = Never, R = Never](token: Token, key: Callable[[ProtectedHeader], Effect[DirKey, E, R]]) -> Effect[Decrypted, JoseError | E, Aead | R]
decrypt[E = Never, R = Never](token: Token, key: DirKey | Callable[[ProtectedHeader], Effect[DirKey, E, R]]) -> Effect[Decrypted, JoseError | E, Aead | R]

The plaintext and header; DecryptionFailed for a wrong key or a tampered token.

ParameterTypeDescription
token
key
@overload
def decrypt(token: Token, key: DirKey) -> Effect[Decrypted, JoseError, Aead]: ...
@overload
def decrypt[E = Never, R = Never](
    token: Token, key: Callable[[ProtectedHeader], Effect[DirKey, E, R]]
) -> Effect[Decrypted, JoseError | E, Aead | R]: ...
@overload
def decrypt[E = Never, R = Never](
    token: Token, key: DirKey | Callable[[ProtectedHeader], Effect[DirKey, E, R]]
) -> Effect[Decrypted, JoseError | E, Aead | R]: ...
def decrypt(
    token: Token, key: DirKey | Callable[[ProtectedHeader], Effect[DirKey, Any, Any]]
) -> Effect[Decrypted, Any, Any]:
    """The plaintext and header; ``DecryptionFailed`` for a wrong key or a
    tampered token."""

    @gen
    def body():
        header, encrypted_key, iv, ciphertext, tag = yield from split(token, 5)
        if encrypted_key != "":
            return (yield from invalid_token("A dir token must have an empty encrypted key"))
        protected_header = yield from decode_header(header, _decode_protected_header, _UNSUPPORTED)
        nonce = decode_segment(iv)
        data = decode_segment(ciphertext)
        auth_tag = decode_segment(tag)
        if (
            nonce is None
            or data is None
            or auth_tag is None
            or len(nonce) != _NONCE_LENGTH
            or len(auth_tag) != _TAG_LENGTH
        ):
            return (yield from invalid_token("The IV, ciphertext, or tag is malformed"))
        resolved: DirKey = key if isinstance(key, DirKey) else (yield from key(protected_header))
        service = yield from Aead()
        plaintext = yield from service.decrypt(
            resolved.key, data + auth_tag, nonce=nonce, aad=utf8(header)
        ).map_error(_decryption_failure)
        return Decrypted(protected_header, plaintext, resolved)

    return body