GitHub

API reference for kdf.

Key derivation as a service (Effect's effect/crypto/Kdf)::

kdf = yield from Kdf()
okm = yield from kdf.derive(hkdf_sha256, secret, salt=salt, info=b"ctx", length=32)
hashed = yield from kdf.derive(argon2id(), password, salt=salt, length=32)

HKDF and PBKDF2 run on the WebCrypto reference; Argon2id needs native.layer_kdf (layer_web_crypto fails it with Unsupported). Arguments are checked before Web Crypto sees them.

Re-exports

Values

AttributeTypeDescription
hkdf_sha1Hkdf
hkdf_sha256Hkdf
hkdf_sha384Hkdf
hkdf_sha512Hkdf
pbkdf2_sha256Pbkdf2

PBKDF2-HMAC-SHA256 at OWASP's 600,000 iterations.

layer_web_cryptoLayer[Kdf]

HKDF and PBKDF2 on the WebCrypto reference.

Types

TypeDefinitionDescription
Algorithmtype Algorithm = Hkdf | Pbkdf2 | Argon2id

Classes

Functions

hkdf

hkdf(hash) -> Hkdf
ParameterTypeDescription
hashDigestAlgorithm

Returns Hkdf

def hkdf(hash: DigestAlgorithm) -> Hkdf:
    return Hkdf(name=f"hkdf{name_suffix(hash)}", hash=hash)

pbkdf2

pbkdf2(*, hash, iterations) -> Pbkdf2
ParameterTypeDescription
hashDigestAlgorithm
iterationsint

Returns Pbkdf2

def pbkdf2(*, hash: DigestAlgorithm, iterations: int) -> Pbkdf2:
    return Pbkdf2(name=f"pbkdf2{name_suffix(hash)}", hash=hash, iterations=iterations)

argon2id

argon2id(*, memory=65536, passes=3, parallelism=4) -> Argon2id

Argon2id; the defaults are RFC 9106's second recommended setting (64 MiB, 3 passes, 4 lanes).

ParameterTypeDescription
memoryint = 65536
passesint = 3
parallelismint = 4

Returns Argon2id

def argon2id(*, memory: int = 65_536, passes: int = 3, parallelism: int = 4) -> Argon2id:
    """Argon2id; the defaults are RFC 9106's second recommended setting
    (64 MiB, 3 passes, 4 lanes)."""
    return Argon2id(memory=memory, passes=passes, parallelism=parallelism)

check_arguments

check_arguments(algorithm, length, info) -> Effect[Never, CryptoError] | None

Checked before Web Crypto, which takes a 32-bit bit length that some backends wrap instead of rejecting.

ParameterTypeDescription
algorithmAlgorithm
lengthint
infoBinary | None

Returns Effect[Never, CryptoError] | None

def check_arguments(  # noqa: PLR0911
    algorithm: Algorithm, length: int, info: Binary | None
) -> Effect[Never, CryptoError] | None:
    """Checked before Web Crypto, which takes a 32-bit bit length that some
    backends wrap instead of rejecting."""
    if not isinstance(algorithm, Hkdf) and info is not None:
        return _invalid_argument("info only applies to HKDF")
    if isinstance(algorithm, Argon2id):
        return None
    if algorithm.hash.name == "MD5":
        return _invalid_argument(f"{algorithm.tag} needs a SHA hash, not MD5")
    if isinstance(algorithm, Hkdf):
        max_length = 255 * algorithm.hash.output_length
        if _is_integer_in(length, 1, max_length):
            return None
        return _invalid_argument(
            f"length must be between 1 and {max_length} bytes for {algorithm.name}"
        )
    if not _is_integer_in(algorithm.iterations, 1, 0x7FFF_FFFF):
        return _invalid_argument("iterations must be between 1 and 2^31 - 1")
    if _is_integer_in(length, 1, 0x1FFF_FFFF):
        return None
    return _invalid_argument("length must be between 1 and 2^29 - 1 bytes")