libdecaf (libdecaf v3.0.0)
View SourceCryptography for Erlang and Elixir: signatures, key agreement, hashes, XOFs, and random bytes.
Start with hash/2 for a digest, xof/3 for a chosen number of XOF bytes,
or strong_rand_bytes/1 for random bytes:
Digest = libdecaf:hash(sha3_256, <<"abc">>),
<<"3A985DA74FE225B2045C172D6BD390BD855F086E3E9D525B46BFE24511431532">> = binary:encode_hex(Digest),
Token = libdecaf:strong_rand_bytes(32).Signatures use eddsa_keypair/1, eddsa_sign/2, and eddsa_verify/3.
Ed25519ph and Ed448ph also support streaming through eddsa_sign_init/1
and eddsa_verify_init/2. Key agreement uses ecdh_keypair/1 and
ecdh_shared_secret/3 with X25519 or X448.
For streaming hashes, use hash_init/1, hash_update/2, and hash_final/1.
For streaming XOFs, use xof_init/1, xof_absorb/2, and xof_squeeze/2.
All states are immutable: keep the state returned by each update. Lengths are
in bytes, and message input accepts iodata.
cSHAKE, KMAC, KMACXOF, TupleHash, TupleHashXOF, ParallelHash, and ParallelHashXOF follow SP 800-185r1, including its initialization, absorption, and squeezing interfaces.
parallel_hash/2 supports KT128, KT256, HopMAC128, HopMAC256, ParallelHash128,
and ParallelHash256. parallel_xof/3 supports KT128, KT256, HopMAC128, HopMAC256,
ParallelHashXOF128, and ParallelHashXOF256. Call start/0 to enable the worker
pool. The ordinary and parallel APIs produce identical output.
See the Hash and XOF guide for algorithm parameters
and the migration guide for deprecated APIs.
Group arithmetic is available through libdecaf_ristretto255 and
libdecaf_decaf448; TUAK through libdecaf_tuak.
Summary
Types
ParallelHash block size in bytes. It is part of the construction and changes the digest.
Application-specific domain separation string; the default is empty.
TurboSHAKE domain byte, defaulting to 16#1F.
An ECDH algorithm; its secret scalar is distinct from an EdDSA seed.
An X25519 or X448 keypair.
An X25519 or X448 public key.
An X25519 or X448 secret key.
An X25519 or X448 shared secret.
An extracted public/seed pair, or a legacy curve-module public/encoded-signing-key pair.
An opaque ed448 keypair wrapping a native resource; it contains no signature context.
A 57-byte ed448 public key.
A ed448 public key or a keypair from which to extract it.
The original 57-byte ed448 secret seed.
Accepted ed448 signing inputs. Supplied seed/public-key pairs must match.
ed448 sign parameters restricted to the prehash variant.
ed448 sign parameters.
A 114-byte ed448 signature.
An encoded 114-byte signing key: seed followed by its matching public key.
ed448 verify parameters restricted to the prehash variant.
ed448 verify parameters.
An immutable ed448ph sign state, distinct from the other curve and operation.
An immutable ed448ph verify state, distinct from the other curve and operation.
An extracted public/seed pair, or a legacy curve-module public/encoded-signing-key pair.
An opaque ed25519 keypair wrapping a native resource; it contains no signature context.
A 32-byte ed25519 public key.
A ed25519 public key or a keypair from which to extract it.
The original 32-byte ed25519 secret seed.
Accepted ed25519 signing inputs. Supplied seed/public-key pairs must match.
ed25519 sign parameters restricted to the prehash variant.
ed25519 sign parameters.
A 64-byte ed25519 signature.
An encoded 64-byte signing key: seed followed by its matching public key.
ed25519 verify parameters restricted to the prehash variant.
ed25519 verify parameters.
An immutable ed25519ph sign state, distinct from the other curve and operation.
An immutable ed25519ph verify state, distinct from the other curve and operation.
The base curve used to generate an EdDSA keypair.
An operation-specific context of at most 255 bytes; omitted contexts are empty.
An EdDSA public/secret pair; newly extracted pairs contain the original seed.
An opaque native EdDSA keypair for either base curve.
An Ed25519 or Ed448 public-key encoding.
An original Ed25519 or Ed448 secret seed.
Streaming signing parameters, restricted to Ed25519ph or Ed448ph.
One-shot EdDSA algorithm, signing key, and optional context.
An immutable streaming EdDSA sign state.
An Ed25519 or Ed448 signature encoding.
A legacy encoded EdDSA seed/public-key signing key.
Streaming verification parameters, restricted to Ed25519ph or Ed448ph.
One-shot EdDSA algorithm, verification key, and optional context.
An immutable streaming EdDSA verify state.
cSHAKE function-name string; the default is empty.
Supported hash algorithm selectors.
Algorithm atom or tuple containing initialization parameters in argument order.
An immutable native hash state, with its output length chosen at initialization.
Message bytes accepted as iodata, or one complete TupleHash element during absorption.
Secret KMAC or HopMAC key material accepted as iodata.
Original message bytes. Prehash variants compute the prehash internally.
Requested number of output bytes, including zero.
Initialization parameters for KT128, KT256, HopMAC128, HopMAC256, ParallelHash128, and ParallelHash256.
An immutable parallel HASH state. Retain each returned state to advance the stream.
Initialization parameters for KT128, KT256, HopMAC128, HopMAC256, ParallelHashXOF128, and ParallelHashXOF256.
An immutable parallel XOF state. Retain each returned state to advance the stream.
A proper list of separately framed TupleHash elements.
An opaque x448 public/secret keypair stored as Erlang binaries.
A curve-module public/secret scalar pair.
A 56-byte x448 public key.
A x448 public key or a keypair supplying it.
A 56-byte x448 secret key.
A x448 secret key or a keypair supplying it.
A 56-byte x448 shared secret.
An opaque x25519 public/secret keypair stored as Erlang binaries.
A curve-module public/secret scalar pair.
A 32-byte x25519 public key.
A x25519 public key or a keypair supplying it.
A 32-byte x25519 secret key.
A x25519 secret key or a keypair supplying it.
A 32-byte x25519 shared secret.
Supported xof algorithm selectors.
Algorithm atom or tuple containing initialization parameters in argument order.
An immutable native absorbing or squeezing state.
Application API
Start libdecaf and its application dependencies.
Deprecated API
Derive an X448 scalar from a Ed448 secret seed.
Convert an encoded Ed448 public key to its X448 public-key encoding.
Derive an immutable Ed448 keypair resource from a secret seed.
Derive a Ed448 public key from a secret seed.
Extract the secret seed from a keypair resource. Keep the returned bytes private.
Extract the public key from a keypair resource.
Sign with a Ed448 keypair resource.
Prehashed is 0 for a message or 1 for an already computed 64-byte prehash.
Context is a binary of at most 255 bytes; use <<>> for an empty context.
Prehash the message internally and sign using Ed448ph.
Context is a binary of at most 255 bytes; use <<>> for an empty context.
Sign using a Ed448 secret seed and matching public key.
Mismatched keys raise an error.
Prehashed is 0 for a message or 1 for an already computed 64-byte prehash.
Context is a binary of at most 255 bytes; use <<>> for an empty context.
Prehash the message internally and sign using Ed448ph.
The secret seed and public key must match.
Context is a binary of at most 255 bytes; use <<>> for an empty context.
Verify a Ed448 signature, returning false when verification fails.
Prehashed is 0 for a message or 1 for an already computed 64-byte prehash.
Context is a binary of at most 255 bytes; use <<>> for an empty context.
Prehash the message internally and verify a Ed448ph signature.
Context is a binary of at most 255 bytes; use <<>> for an empty context.
Derive an X25519 scalar from a Ed25519 secret seed.
Convert an encoded Ed25519 public key to its X25519 public-key encoding.
Derive an immutable Ed25519 keypair resource from a secret seed.
Derive a Ed25519 public key from a secret seed.
Extract the secret seed from a keypair resource. Keep the returned bytes private.
Extract the public key from a keypair resource.
Sign with a Ed25519 keypair resource.
Prehashed is 0 for a message or 1 for an already computed 64-byte prehash.
Use no_context for pure Ed25519, or a binary of at most 255 bytes for Ed25519ctx/Ed25519ph.
Prehash the message internally and sign using Ed25519ph.
Use no_context for pure Ed25519, or a binary of at most 255 bytes for Ed25519ctx/Ed25519ph.
Sign using a Ed25519 secret seed and matching public key.
Mismatched keys raise an error.
Prehashed is 0 for a message or 1 for an already computed 64-byte prehash.
Use no_context for pure Ed25519, or a binary of at most 255 bytes for Ed25519ctx/Ed25519ph.
Prehash the message internally and sign using Ed25519ph.
The secret seed and public key must match.
Use no_context for pure Ed25519, or a binary of at most 255 bytes for Ed25519ctx/Ed25519ph.
Verify a Ed25519 signature, returning false when verification fails.
Prehashed is 0 for a message or 1 for an already computed 64-byte prehash.
Use no_context for pure Ed25519, or a binary of at most 255 bytes for Ed25519ctx/Ed25519ph.
Prehash the message internally and verify a Ed25519ph signature.
Use no_context for pure Ed25519, or a binary of at most 255 bytes for Ed25519ctx/Ed25519ph.
Hash iodata using keccak_224; the default digest length is 28 bytes. An explicit output length may truncate the digest to 0 through 28 bytes.
Hash iodata using keccak_224; the default digest length is 28 bytes. An explicit output length may truncate the digest to 0 through 28 bytes.
Return the full 28-byte keccak_224 digest without changing the native state.
Return an keccak_224 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 28.
Initialize an immutable keccak_224 hash state with its full 28-byte digest length. Return the native state directly, without an algorithm tuple.
Absorb iodata into an keccak_224 state and return a new native state. The input state remains reusable.
Hash iodata using keccak_256; the default digest length is 32 bytes. An explicit output length may truncate the digest to 0 through 32 bytes.
Hash iodata using keccak_256; the default digest length is 32 bytes. An explicit output length may truncate the digest to 0 through 32 bytes.
Return the full 32-byte keccak_256 digest without changing the native state.
Return an keccak_256 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 32.
Initialize an immutable keccak_256 hash state with its full 32-byte digest length. Return the native state directly, without an algorithm tuple.
Absorb iodata into an keccak_256 state and return a new native state. The input state remains reusable.
Hash iodata using keccak_384; the default digest length is 48 bytes. An explicit output length may truncate the digest to 0 through 48 bytes.
Hash iodata using keccak_384; the default digest length is 48 bytes. An explicit output length may truncate the digest to 0 through 48 bytes.
Return the full 48-byte keccak_384 digest without changing the native state.
Return an keccak_384 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 48.
Initialize an immutable keccak_384 hash state with its full 48-byte digest length. Return the native state directly, without an algorithm tuple.
Absorb iodata into an keccak_384 state and return a new native state. The input state remains reusable.
Hash iodata using keccak_512; the default digest length is 64 bytes. An explicit output length may truncate the digest to 0 through 64 bytes.
Hash iodata using keccak_512; the default digest length is 64 bytes. An explicit output length may truncate the digest to 0 through 64 bytes.
Return the full 64-byte keccak_512 digest without changing the native state.
Return an keccak_512 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 64.
Initialize an immutable keccak_512 hash state with its full 64-byte digest length. Return the native state directly, without an algorithm tuple.
Absorb iodata into an keccak_512 state and return a new native state. The input state remains reusable.
Locate libdecaf's priv directory, including the historical fallback when the application is not loaded.
Hash iodata using sha2_512; the default digest length is 64 bytes. An explicit output length may truncate the digest to 0 through 64 bytes.
Hash iodata using sha2_512; the default digest length is 64 bytes. An explicit output length may truncate the digest to 0 through 64 bytes.
Return the full 64-byte sha2_512 digest without changing the native state.
Return an sha2_512 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 64.
Initialize an immutable sha2_512 hash state with its full 64-byte digest length. Return the native state directly, without an algorithm tuple.
Absorb iodata into an sha2_512 state and return a new native state. The input state remains reusable.
Hash iodata using sha3_224; the default digest length is 28 bytes. An explicit output length may truncate the digest to 0 through 28 bytes.
Hash iodata using sha3_224; the default digest length is 28 bytes. An explicit output length may truncate the digest to 0 through 28 bytes.
Return the full 28-byte sha3_224 digest without changing the native state.
Return an sha3_224 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 28.
Initialize an immutable sha3_224 hash state with its full 28-byte digest length. Return the native state directly, without an algorithm tuple.
Absorb iodata into an sha3_224 state and return a new native state. The input state remains reusable.
Hash iodata using sha3_256; the default digest length is 32 bytes. An explicit output length may truncate the digest to 0 through 32 bytes.
Hash iodata using sha3_256; the default digest length is 32 bytes. An explicit output length may truncate the digest to 0 through 32 bytes.
Return the full 32-byte sha3_256 digest without changing the native state.
Return an sha3_256 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 32.
Initialize an immutable sha3_256 hash state with its full 32-byte digest length. Return the native state directly, without an algorithm tuple.
Absorb iodata into an sha3_256 state and return a new native state. The input state remains reusable.
Hash iodata using sha3_384; the default digest length is 48 bytes. An explicit output length may truncate the digest to 0 through 48 bytes.
Hash iodata using sha3_384; the default digest length is 48 bytes. An explicit output length may truncate the digest to 0 through 48 bytes.
Return the full 48-byte sha3_384 digest without changing the native state.
Return an sha3_384 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 48.
Initialize an immutable sha3_384 hash state with its full 48-byte digest length. Return the native state directly, without an algorithm tuple.
Absorb iodata into an sha3_384 state and return a new native state. The input state remains reusable.
Hash iodata using sha3_512; the default digest length is 64 bytes. An explicit output length may truncate the digest to 0 through 64 bytes.
Hash iodata using sha3_512; the default digest length is 64 bytes. An explicit output length may truncate the digest to 0 through 64 bytes.
Return the full 64-byte sha3_512 digest without changing the native state.
Return an sha3_512 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 64.
Initialize an immutable sha3_512 hash state with its full 64-byte digest length. Return the native state directly, without an algorithm tuple.
Absorb iodata into an sha3_512 state and return a new native state. The input state remains reusable.
Return OutputLength bytes of shake128 output from iodata.
Return OutputLength bytes from an absorbing shake128 state. Return only the output binary; finalizing the same immutable state repeats the output.
Initialize an immutable absorbing shake128 native state.
Absorb iodata into shake128 and return a new native state. The input state remains reusable.
Return OutputLength bytes of shake256 output from iodata.
Return OutputLength bytes from an absorbing shake256 state. Return only the output binary; finalizing the same immutable state repeats the output.
Initialize an immutable absorbing shake256 native state.
Absorb iodata into shake256 and return a new native state. The input state remains reusable.
Initialize a sponge PRNG from seed bytes.
Deterministic selects the upstream PRNG's deterministic mode.
Initialize a sponge PRNG using /dev/urandom.
Raise an exception if the entropy source cannot be read.
Initialize a sponge PRNG by reading InputLen bytes from a file.
Filename contains nonempty native filename bytes; file errors raise an exception.
Generate bytes and return the new PRNG state together with those bytes. Continue with the returned state to advance the stream.
Mix additional seed bytes into a PRNG state and return a new state.
Compute a Diffie-Hellman shared secret.
The public key comes first and the secret scalar second.
Return error when the upstream operation rejects the input, including low-order points.
Derive an X448 public key from a secret scalar.
Derive an X448 public key from a secret scalar.
Compute a Diffie-Hellman shared secret.
The public key comes first and the secret scalar second.
Return error when the upstream operation rejects the input, including low-order points.
Derive an X25519 public key from a secret scalar.
Derive an X25519 public key from a secret scalar.
ECDH API
Generate a random ECDH keypair.
Derive an ECDH keypair from an existing secret scalar.
Return {PublicKey, SecretKey} in that order.
Extract the public-key bytes.
Extract the original secret scalar bytes.
Compute the raw ECDH shared secret with the local secret first and peer public key second.
EdDSA API
Generate a random EdDSA keypair.
Derive an EdDSA keypair from an existing secret seed.
Return {PublicKey, SecretKey} in that order. For EdDSA, the secret is the original seed, not the
encoded seed/public-key signing key.
Extract the public-key bytes. For EdDSA, the secret is the original seed, not the encoded seed/public-key signing key.
Extract the original secret seed bytes. For EdDSA, the secret is the original seed, not the encoded seed/public-key signing key.
Sign a message using {Algorithm, Key} or {Algorithm, Key, Context}.
Sign the accumulated original message using the retained keypair and context. The input state is unchanged; repeated finalization returns the same result. The signature matches one-shot signing with the same parameters.
Start streaming signing with Ed25519ph or Ed448ph.
Add another original-message chunk and return a new signing state.
Verify a signature over an original message using the same algorithm and context as signing.
Verify the accumulated original message against the retained signature, key, and context. The input
state is unchanged; repeated finalization returns the same result. Return false if verification
fails.
Start streaming verification with Ed25519ph or Ed448ph.
Add another original-message chunk and return a new verification state.
Hash API
Hash input using an algorithm atom or initialization parameter tuple.
Return the digest or authentication tag at the length chosen during initialization.
Initialize a hash using an algorithm atom or a parameter tuple.
Add input to a hash and return a new state.
Compute a parallel hash from initialization parameters and input.
Return the configured hash output without changing the input state.
Initialize a parallel Hash state.
Add input to a parallel Hash state and return its new state.
Sponge PRNG API
Generate Length cryptographically random bytes without managing a PRNG state.
XOF API
Compute parallel XOF output from initialization parameters and input.
Add input to a parallel XOF state and return its new state.
Initialize a parallel XOF state.
Read output and return {NextState, Output}.
Return OutputLength bytes using XOF initialization parameters and input.
Add input to an absorbing XOF and return a new state.
Initialize an XOF using an algorithm atom or a parameter tuple.
Return {NextState, Output} with the next Length bytes of an XOF stream.
Types
-type block_size() :: libdecaf_nif:block_size().
ParallelHash block size in bytes. It is part of the construction and changes the digest.
-type customization_string() :: libdecaf_nif:customization_string().
Application-specific domain separation string; the default is empty.
-type domain_separation() :: libdecaf_nif:domain_separation().
TurboSHAKE domain byte, defaulting to 16#1F.
-type ecdh_algorithm() :: x25519 | x448.
An ECDH algorithm; its secret scalar is distinct from an EdDSA seed.
-type ecdh_keypair() :: x25519_keypair() | x448_keypair().
An X25519 or X448 keypair.
-type ecdh_public_key() :: x25519_public_key() | x448_public_key().
An X25519 or X448 public key.
-type ecdh_secret_key() :: x25519_secret_key() | x448_secret_key().
An X25519 or X448 secret key.
-type ed448_keypair() :: {ed448_public_key(), ed448_secret_key() | ed448_signing_key()}.
An extracted public/seed pair, or a legacy curve-module public/encoded-signing-key pair.
-opaque ed448_keypair_state()
An opaque ed448 keypair wrapping a native resource; it contains no signature context.
-type ed448_public_key() :: libdecaf_nif:ed448_public_key().
A 57-byte ed448 public key.
-type ed448_public_key_compat() :: ed448_public_key() | ed448_keypair() | ed448_keypair_state().
A ed448 public key or a keypair from which to extract it.
-type ed448_secret_key() :: libdecaf_nif:ed448_secret_key().
The original 57-byte ed448 secret seed.
-type ed448_secret_key_compat() :: ed448_secret_key() | ed448_signing_key() | ed448_keypair() | ed448_keypair_state().
Accepted ed448 signing inputs. Supplied seed/public-key pairs must match.
-type ed448_sign_init_parameters() :: {ed448ph, ed448_secret_key_compat()} | {ed448ph, ed448_secret_key_compat(), eddsa_context()}.
ed448 sign parameters restricted to the prehash variant.
-type ed448_sign_parameters() :: {ed448, ed448_secret_key_compat()} | {ed448, ed448_secret_key_compat(), eddsa_context()} | {ed448ph, ed448_secret_key_compat()} | {ed448ph, ed448_secret_key_compat(), eddsa_context()}.
ed448 sign parameters.
-type ed448_signature() :: libdecaf_nif:ed448_signature().
A 114-byte ed448 signature.
-type ed448_signing_key() :: libdecaf_nif:ed448_signing_key().
An encoded 114-byte signing key: seed followed by its matching public key.
-type ed448_verify_init_parameters() :: {ed448ph, ed448_public_key_compat()} | {ed448ph, ed448_public_key_compat(), eddsa_context()}.
ed448 verify parameters restricted to the prehash variant.
-type ed448_verify_parameters() :: {ed448, ed448_public_key_compat()} | {ed448, ed448_public_key_compat(), eddsa_context()} | {ed448ph, ed448_public_key_compat()} | {ed448ph, ed448_public_key_compat(), eddsa_context()}.
ed448 verify parameters.
-opaque ed448ph_sign_state()
An immutable ed448ph sign state, distinct from the other curve and operation.
-opaque ed448ph_verify_state()
An immutable ed448ph verify state, distinct from the other curve and operation.
-type ed25519_keypair() :: {ed25519_public_key(), ed25519_secret_key() | ed25519_signing_key()}.
An extracted public/seed pair, or a legacy curve-module public/encoded-signing-key pair.
-opaque ed25519_keypair_state()
An opaque ed25519 keypair wrapping a native resource; it contains no signature context.
-type ed25519_public_key() :: libdecaf_nif:ed25519_public_key().
A 32-byte ed25519 public key.
-type ed25519_public_key_compat() :: ed25519_public_key() | ed25519_keypair() | ed25519_keypair_state().
A ed25519 public key or a keypair from which to extract it.
-type ed25519_secret_key() :: libdecaf_nif:ed25519_secret_key().
The original 32-byte ed25519 secret seed.
-type ed25519_secret_key_compat() :: ed25519_secret_key() | ed25519_signing_key() | ed25519_keypair() | ed25519_keypair_state().
Accepted ed25519 signing inputs. Supplied seed/public-key pairs must match.
-type ed25519_sign_init_parameters() :: {ed25519ph, ed25519_secret_key_compat()} | {ed25519ph, ed25519_secret_key_compat(), eddsa_context()}.
ed25519 sign parameters restricted to the prehash variant.
-type ed25519_sign_parameters() :: {ed25519, ed25519_secret_key_compat()} | {ed25519ctx, ed25519_secret_key_compat()} | {ed25519ctx, ed25519_secret_key_compat(), eddsa_context()} | {ed25519ph, ed25519_secret_key_compat()} | {ed25519ph, ed25519_secret_key_compat(), eddsa_context()}.
ed25519 sign parameters.
-type ed25519_signature() :: libdecaf_nif:ed25519_signature().
A 64-byte ed25519 signature.
-type ed25519_signing_key() :: libdecaf_nif:ed25519_signing_key().
An encoded 64-byte signing key: seed followed by its matching public key.
-type ed25519_verify_init_parameters() :: {ed25519ph, ed25519_public_key_compat()} | {ed25519ph, ed25519_public_key_compat(), eddsa_context()}.
ed25519 verify parameters restricted to the prehash variant.
-type ed25519_verify_parameters() :: {ed25519, ed25519_public_key_compat()} | {ed25519ctx, ed25519_public_key_compat()} | {ed25519ctx, ed25519_public_key_compat(), eddsa_context()} | {ed25519ph, ed25519_public_key_compat()} | {ed25519ph, ed25519_public_key_compat(), eddsa_context()}.
ed25519 verify parameters.
-opaque ed25519ph_sign_state()
An immutable ed25519ph sign state, distinct from the other curve and operation.
-opaque ed25519ph_verify_state()
An immutable ed25519ph verify state, distinct from the other curve and operation.
-type eddsa_algorithm() :: ed25519 | ed448.
The base curve used to generate an EdDSA keypair.
-type eddsa_context() :: binary().
An operation-specific context of at most 255 bytes; omitted contexts are empty.
-type eddsa_keypair() :: ed25519_keypair() | ed448_keypair().
An EdDSA public/secret pair; newly extracted pairs contain the original seed.
-type eddsa_keypair_state() :: ed25519_keypair_state() | ed448_keypair_state().
An opaque native EdDSA keypair for either base curve.
-type eddsa_public_key() :: ed25519_public_key() | ed448_public_key().
An Ed25519 or Ed448 public-key encoding.
-type eddsa_secret_key() :: ed25519_secret_key() | ed448_secret_key().
An original Ed25519 or Ed448 secret seed.
-type eddsa_sign_init_parameters() :: ed25519_sign_init_parameters() | ed448_sign_init_parameters().
Streaming signing parameters, restricted to Ed25519ph or Ed448ph.
-type eddsa_sign_parameters() :: ed25519_sign_parameters() | ed448_sign_parameters().
One-shot EdDSA algorithm, signing key, and optional context.
-type eddsa_sign_state() :: ed25519ph_sign_state() | ed448ph_sign_state().
An immutable streaming EdDSA sign state.
-type eddsa_signature() :: ed25519_signature() | ed448_signature().
An Ed25519 or Ed448 signature encoding.
-type eddsa_signing_key() :: ed25519_signing_key() | ed448_signing_key().
A legacy encoded EdDSA seed/public-key signing key.
-type eddsa_verify_init_parameters() :: ed25519_verify_init_parameters() | ed448_verify_init_parameters().
Streaming verification parameters, restricted to Ed25519ph or Ed448ph.
-type eddsa_verify_parameters() :: ed25519_verify_parameters() | ed448_verify_parameters().
One-shot EdDSA algorithm, verification key, and optional context.
-type eddsa_verify_state() :: ed25519ph_verify_state() | ed448ph_verify_state().
An immutable streaming EdDSA verify state.
-type function_name() :: libdecaf_nif:function_name().
cSHAKE function-name string; the default is empty.
-type hash_algorithm() :: libdecaf_nif:hash_algorithm().
Supported hash algorithm selectors.
-type hash_parameters() :: libdecaf_nif:hash_parameters().
Algorithm atom or tuple containing initialization parameters in argument order.
-type hash_state() :: libdecaf_nif:hash_state().
An immutable native hash state, with its output length chosen at initialization.
-type input() :: libdecaf_nif:input().
Message bytes accepted as iodata, or one complete TupleHash element during absorption.
-type key() :: libdecaf_nif:key().
Secret KMAC or HopMAC key material accepted as iodata.
-type message() :: iodata().
Original message bytes. Prehash variants compute the prehash internally.
-type output_length() :: libdecaf_nif:output_length().
Requested number of output bytes, including zero.
-type parallel_hash_parameters() :: libdecaf_nif:parallel_hash_parameters().
Initialization parameters for KT128, KT256, HopMAC128, HopMAC256, ParallelHash128, and ParallelHash256.
-type parallel_hash_state() :: libdecaf_nif:parallel_hash_state().
An immutable parallel HASH state. Retain each returned state to advance the stream.
-type parallel_xof_parameters() :: libdecaf_nif:parallel_xof_parameters().
Initialization parameters for KT128, KT256, HopMAC128, HopMAC256, ParallelHashXOF128, and ParallelHashXOF256.
-type parallel_xof_state() :: libdecaf_nif:parallel_xof_state().
An immutable parallel XOF state. Retain each returned state to advance the stream.
-type tuple_input() :: libdecaf_nif:tuple_input().
A proper list of separately framed TupleHash elements.
-opaque x448_keypair()
An opaque x448 public/secret keypair stored as Erlang binaries.
-type x448_keypair_bytes() :: {x448_public_key(), x448_secret_key()}.
A curve-module public/secret scalar pair.
-type x448_public_key() :: libdecaf_nif:x448_public_key().
A 56-byte x448 public key.
-type x448_public_key_compat() :: x448_public_key() | x448_keypair() | x448_keypair_bytes().
A x448 public key or a keypair supplying it.
-type x448_secret_key() :: libdecaf_nif:x448_scalar().
A 56-byte x448 secret key.
-type x448_secret_key_compat() :: x448_secret_key() | x448_keypair() | x448_keypair_bytes().
A x448 secret key or a keypair supplying it.
-opaque x25519_keypair()
An opaque x25519 public/secret keypair stored as Erlang binaries.
-type x25519_keypair_bytes() :: {x25519_public_key(), x25519_secret_key()}.
A curve-module public/secret scalar pair.
-type x25519_public_key() :: libdecaf_nif:x25519_public_key().
A 32-byte x25519 public key.
-type x25519_public_key_compat() :: x25519_public_key() | x25519_keypair() | x25519_keypair_bytes().
A x25519 public key or a keypair supplying it.
-type x25519_secret_key() :: libdecaf_nif:x25519_scalar().
A 32-byte x25519 secret key.
-type x25519_secret_key_compat() :: x25519_secret_key() | x25519_keypair() | x25519_keypair_bytes().
A x25519 secret key or a keypair supplying it.
-type xof_algorithm() :: libdecaf_nif:xof_algorithm().
Supported xof algorithm selectors.
-type xof_parameters() :: libdecaf_nif:xof_parameters().
Algorithm atom or tuple containing initialization parameters in argument order.
-type xof_state() :: libdecaf_nif:xof_state().
An immutable native absorbing or squeezing state.
Application API
Deprecated API
-spec ed448_convert_private_key_to_x448(SecretKey) -> Result when SecretKey :: libdecaf_nif:ed448_secret_key(), Result :: libdecaf_nif:x448_scalar().
Derive an X448 scalar from a Ed448 secret seed.
-spec ed448_convert_public_key_to_x448(PublicKey) -> Result when PublicKey :: libdecaf_nif:ed448_public_key(), Result :: libdecaf_nif:x448_public_key().
Convert an encoded Ed448 public key to its X448 public-key encoding.
-spec ed448_derive_keypair(SecretKey) -> Result when SecretKey :: libdecaf_nif:ed448_secret_key(), Result :: libdecaf_nif:ed448_keypair().
Derive an immutable Ed448 keypair resource from a secret seed.
-spec ed448_derive_public_key(SecretKey) -> Result when SecretKey :: libdecaf_nif:ed448_secret_key(), Result :: libdecaf_nif:ed448_public_key().
Derive a Ed448 public key from a secret seed.
-spec ed448_keypair_extract_private_key(Keypair) -> Result when Keypair :: libdecaf_nif:ed448_keypair(), Result :: libdecaf_nif:ed448_secret_key().
Extract the secret seed from a keypair resource. Keep the returned bytes private.
-spec ed448_keypair_extract_public_key(Keypair) -> Result when Keypair :: libdecaf_nif:ed448_keypair(), Result :: libdecaf_nif:ed448_public_key().
Extract the public key from a keypair resource.
-spec ed448_keypair_sign(Keypair, Message, Prehashed, Context) -> Result when Keypair :: libdecaf_nif:ed448_keypair(), Message :: binary(), Prehashed :: libdecaf_nif:prehashed(), Context :: binary(), Result :: libdecaf_nif:ed448_signature().
Sign with a Ed448 keypair resource.
Prehashed is 0 for a message or 1 for an already computed 64-byte prehash.
Context is a binary of at most 255 bytes; use <<>> for an empty context.
-spec ed448_keypair_sign_prehash(Keypair, Message, Context) -> Result when Keypair :: libdecaf_nif:ed448_keypair(), Message :: binary(), Context :: binary(), Result :: libdecaf_nif:ed448_signature().
Prehash the message internally and sign using Ed448ph.
Context is a binary of at most 255 bytes; use <<>> for an empty context.
-spec ed448_sign(SecretKey, PublicKey, Message, Prehashed, Context) -> Result when SecretKey :: libdecaf_nif:ed448_secret_key(), PublicKey :: libdecaf_nif:ed448_public_key(), Message :: binary(), Prehashed :: libdecaf_nif:prehashed(), Context :: binary(), Result :: libdecaf_nif:ed448_signature().
Sign using a Ed448 secret seed and matching public key.
Mismatched keys raise an error.
Prehashed is 0 for a message or 1 for an already computed 64-byte prehash.
Context is a binary of at most 255 bytes; use <<>> for an empty context.
-spec ed448_sign_prehash(SecretKey, PublicKey, Message, Context) -> Result when SecretKey :: libdecaf_nif:ed448_secret_key(), PublicKey :: libdecaf_nif:ed448_public_key(), Message :: binary(), Context :: binary(), Result :: libdecaf_nif:ed448_signature().
Prehash the message internally and sign using Ed448ph.
The secret seed and public key must match.
Context is a binary of at most 255 bytes; use <<>> for an empty context.
-spec ed448_verify(Signature, PublicKey, Message, Prehashed, Context) -> Result when Signature :: libdecaf_nif:ed448_signature(), PublicKey :: libdecaf_nif:ed448_public_key(), Message :: binary(), Prehashed :: libdecaf_nif:prehashed(), Context :: binary(), Result :: boolean().
Verify a Ed448 signature, returning false when verification fails.
Prehashed is 0 for a message or 1 for an already computed 64-byte prehash.
Context is a binary of at most 255 bytes; use <<>> for an empty context.
-spec ed448_verify_prehash(Signature, PublicKey, Message, Context) -> Result when Signature :: libdecaf_nif:ed448_signature(), PublicKey :: libdecaf_nif:ed448_public_key(), Message :: binary(), Context :: binary(), Result :: boolean().
Prehash the message internally and verify a Ed448ph signature.
Context is a binary of at most 255 bytes; use <<>> for an empty context.
-spec ed25519_convert_private_key_to_x25519(SecretKey) -> Result when SecretKey :: libdecaf_nif:ed25519_secret_key(), Result :: libdecaf_nif:x25519_scalar().
Derive an X25519 scalar from a Ed25519 secret seed.
-spec ed25519_convert_public_key_to_x25519(PublicKey) -> Result when PublicKey :: libdecaf_nif:ed25519_public_key(), Result :: libdecaf_nif:x25519_public_key().
Convert an encoded Ed25519 public key to its X25519 public-key encoding.
-spec ed25519_derive_keypair(SecretKey) -> Result when SecretKey :: libdecaf_nif:ed25519_secret_key(), Result :: libdecaf_nif:ed25519_keypair().
Derive an immutable Ed25519 keypair resource from a secret seed.
-spec ed25519_derive_public_key(SecretKey) -> Result when SecretKey :: libdecaf_nif:ed25519_secret_key(), Result :: libdecaf_nif:ed25519_public_key().
Derive a Ed25519 public key from a secret seed.
-spec ed25519_keypair_extract_private_key(Keypair) -> Result when Keypair :: libdecaf_nif:ed25519_keypair(), Result :: libdecaf_nif:ed25519_secret_key().
Extract the secret seed from a keypair resource. Keep the returned bytes private.
-spec ed25519_keypair_extract_public_key(Keypair) -> Result when Keypair :: libdecaf_nif:ed25519_keypair(), Result :: libdecaf_nif:ed25519_public_key().
Extract the public key from a keypair resource.
-spec ed25519_keypair_sign(Keypair, Message, Prehashed, Context) -> Result when Keypair :: libdecaf_nif:ed25519_keypair(), Message :: binary(), Prehashed :: libdecaf_nif:prehashed(), Context :: libdecaf_nif:ed25519_context(), Result :: libdecaf_nif:ed25519_signature().
Sign with a Ed25519 keypair resource.
Prehashed is 0 for a message or 1 for an already computed 64-byte prehash.
Use no_context for pure Ed25519, or a binary of at most 255 bytes for Ed25519ctx/Ed25519ph.
-spec ed25519_keypair_sign_prehash(Keypair, Message, Context) -> Result when Keypair :: libdecaf_nif:ed25519_keypair(), Message :: binary(), Context :: libdecaf_nif:ed25519_context(), Result :: libdecaf_nif:ed25519_signature().
Prehash the message internally and sign using Ed25519ph.
Use no_context for pure Ed25519, or a binary of at most 255 bytes for Ed25519ctx/Ed25519ph.
-spec ed25519_sign(SecretKey, PublicKey, Message, Prehashed, Context) -> Result when SecretKey :: libdecaf_nif:ed25519_secret_key(), PublicKey :: libdecaf_nif:ed25519_public_key(), Message :: binary(), Prehashed :: libdecaf_nif:prehashed(), Context :: libdecaf_nif:ed25519_context(), Result :: libdecaf_nif:ed25519_signature().
Sign using a Ed25519 secret seed and matching public key.
Mismatched keys raise an error.
Prehashed is 0 for a message or 1 for an already computed 64-byte prehash.
Use no_context for pure Ed25519, or a binary of at most 255 bytes for Ed25519ctx/Ed25519ph.
-spec ed25519_sign_prehash(SecretKey, PublicKey, Message, Context) -> Result when SecretKey :: libdecaf_nif:ed25519_secret_key(), PublicKey :: libdecaf_nif:ed25519_public_key(), Message :: binary(), Context :: libdecaf_nif:ed25519_context(), Result :: libdecaf_nif:ed25519_signature().
Prehash the message internally and sign using Ed25519ph.
The secret seed and public key must match.
Use no_context for pure Ed25519, or a binary of at most 255 bytes for Ed25519ctx/Ed25519ph.
-spec ed25519_verify(Signature, PublicKey, Message, Prehashed, Context) -> Result when Signature :: libdecaf_nif:ed25519_signature(), PublicKey :: libdecaf_nif:ed25519_public_key(), Message :: binary(), Prehashed :: libdecaf_nif:prehashed(), Context :: libdecaf_nif:ed25519_context(), Result :: boolean().
Verify a Ed25519 signature, returning false when verification fails.
Prehashed is 0 for a message or 1 for an already computed 64-byte prehash.
Use no_context for pure Ed25519, or a binary of at most 255 bytes for Ed25519ctx/Ed25519ph.
-spec ed25519_verify_prehash(Signature, PublicKey, Message, Context) -> Result when Signature :: libdecaf_nif:ed25519_signature(), PublicKey :: libdecaf_nif:ed25519_public_key(), Message :: binary(), Context :: libdecaf_nif:ed25519_context(), Result :: boolean().
Prehash the message internally and verify a Ed25519ph signature.
Use no_context for pure Ed25519, or a binary of at most 255 bytes for Ed25519ctx/Ed25519ph.
-spec keccak_224(Input) -> Result when Input :: libdecaf_nif:input(), Result :: binary().
Hash iodata using keccak_224; the default digest length is 28 bytes. An explicit output length may truncate the digest to 0 through 28 bytes.
-spec keccak_224(Input, OutputLength) -> Result when Input :: libdecaf_nif:input(), OutputLength :: libdecaf_nif:output_length(), Result :: binary().
Hash iodata using keccak_224; the default digest length is 28 bytes. An explicit output length may truncate the digest to 0 through 28 bytes.
-spec keccak_224_final(State) -> Result when State :: libdecaf_nif:hash_state(), Result :: binary().
Return the full 28-byte keccak_224 digest without changing the native state.
-spec keccak_224_final(State, OutputLength) -> Result when State :: libdecaf_nif:hash_state(), OutputLength :: non_neg_integer(), Result :: binary().
Return an keccak_224 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 28.
-spec keccak_224_init() -> Result when Result :: libdecaf_nif:hash_state().
Initialize an immutable keccak_224 hash state with its full 28-byte digest length. Return the native state directly, without an algorithm tuple.
-spec keccak_224_update(State, Input) -> Result when State :: libdecaf_nif:hash_state(), Input :: iodata(), Result :: libdecaf_nif:hash_state().
Absorb iodata into an keccak_224 state and return a new native state. The input state remains reusable.
-spec keccak_256(Input) -> Result when Input :: libdecaf_nif:input(), Result :: binary().
Hash iodata using keccak_256; the default digest length is 32 bytes. An explicit output length may truncate the digest to 0 through 32 bytes.
-spec keccak_256(Input, OutputLength) -> Result when Input :: libdecaf_nif:input(), OutputLength :: libdecaf_nif:output_length(), Result :: binary().
Hash iodata using keccak_256; the default digest length is 32 bytes. An explicit output length may truncate the digest to 0 through 32 bytes.
-spec keccak_256_final(State) -> Result when State :: libdecaf_nif:hash_state(), Result :: binary().
Return the full 32-byte keccak_256 digest without changing the native state.
-spec keccak_256_final(State, OutputLength) -> Result when State :: libdecaf_nif:hash_state(), OutputLength :: non_neg_integer(), Result :: binary().
Return an keccak_256 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 32.
-spec keccak_256_init() -> Result when Result :: libdecaf_nif:hash_state().
Initialize an immutable keccak_256 hash state with its full 32-byte digest length. Return the native state directly, without an algorithm tuple.
-spec keccak_256_update(State, Input) -> Result when State :: libdecaf_nif:hash_state(), Input :: iodata(), Result :: libdecaf_nif:hash_state().
Absorb iodata into an keccak_256 state and return a new native state. The input state remains reusable.
-spec keccak_384(Input) -> Result when Input :: libdecaf_nif:input(), Result :: binary().
Hash iodata using keccak_384; the default digest length is 48 bytes. An explicit output length may truncate the digest to 0 through 48 bytes.
-spec keccak_384(Input, OutputLength) -> Result when Input :: libdecaf_nif:input(), OutputLength :: libdecaf_nif:output_length(), Result :: binary().
Hash iodata using keccak_384; the default digest length is 48 bytes. An explicit output length may truncate the digest to 0 through 48 bytes.
-spec keccak_384_final(State) -> Result when State :: libdecaf_nif:hash_state(), Result :: binary().
Return the full 48-byte keccak_384 digest without changing the native state.
-spec keccak_384_final(State, OutputLength) -> Result when State :: libdecaf_nif:hash_state(), OutputLength :: non_neg_integer(), Result :: binary().
Return an keccak_384 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 48.
-spec keccak_384_init() -> Result when Result :: libdecaf_nif:hash_state().
Initialize an immutable keccak_384 hash state with its full 48-byte digest length. Return the native state directly, without an algorithm tuple.
-spec keccak_384_update(State, Input) -> Result when State :: libdecaf_nif:hash_state(), Input :: iodata(), Result :: libdecaf_nif:hash_state().
Absorb iodata into an keccak_384 state and return a new native state. The input state remains reusable.
-spec keccak_512(Input) -> Result when Input :: libdecaf_nif:input(), Result :: binary().
Hash iodata using keccak_512; the default digest length is 64 bytes. An explicit output length may truncate the digest to 0 through 64 bytes.
-spec keccak_512(Input, OutputLength) -> Result when Input :: libdecaf_nif:input(), OutputLength :: libdecaf_nif:output_length(), Result :: binary().
Hash iodata using keccak_512; the default digest length is 64 bytes. An explicit output length may truncate the digest to 0 through 64 bytes.
-spec keccak_512_final(State) -> Result when State :: libdecaf_nif:hash_state(), Result :: binary().
Return the full 64-byte keccak_512 digest without changing the native state.
-spec keccak_512_final(State, OutputLength) -> Result when State :: libdecaf_nif:hash_state(), OutputLength :: non_neg_integer(), Result :: binary().
Return an keccak_512 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 64.
-spec keccak_512_init() -> Result when Result :: libdecaf_nif:hash_state().
Initialize an immutable keccak_512 hash state with its full 64-byte digest length. Return the native state directly, without an algorithm tuple.
-spec keccak_512_update(State, Input) -> Result when State :: libdecaf_nif:hash_state(), Input :: iodata(), Result :: libdecaf_nif:hash_state().
Absorb iodata into an keccak_512 state and return a new native state. The input state remains reusable.
-spec priv_dir() -> Result when Result :: file:filename_all().
Locate libdecaf's priv directory, including the historical fallback when the application is not loaded.
-spec sha2_512(Input) -> Result when Input :: libdecaf_nif:input(), Result :: binary().
Hash iodata using sha2_512; the default digest length is 64 bytes. An explicit output length may truncate the digest to 0 through 64 bytes.
-spec sha2_512(Input, OutputLength) -> Result when Input :: libdecaf_nif:input(), OutputLength :: libdecaf_nif:output_length(), Result :: binary().
Hash iodata using sha2_512; the default digest length is 64 bytes. An explicit output length may truncate the digest to 0 through 64 bytes.
-spec sha2_512_final(State) -> Result when State :: libdecaf_nif:hash_state(), Result :: binary().
Return the full 64-byte sha2_512 digest without changing the native state.
-spec sha2_512_final(State, OutputLength) -> Result when State :: libdecaf_nif:hash_state(), OutputLength :: non_neg_integer(), Result :: binary().
Return an sha2_512 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 64.
-spec sha2_512_init() -> Result when Result :: libdecaf_nif:hash_state().
Initialize an immutable sha2_512 hash state with its full 64-byte digest length. Return the native state directly, without an algorithm tuple.
-spec sha2_512_update(State, Input) -> Result when State :: libdecaf_nif:hash_state(), Input :: iodata(), Result :: libdecaf_nif:hash_state().
Absorb iodata into an sha2_512 state and return a new native state. The input state remains reusable.
-spec sha3_224(Input) -> Result when Input :: libdecaf_nif:input(), Result :: binary().
Hash iodata using sha3_224; the default digest length is 28 bytes. An explicit output length may truncate the digest to 0 through 28 bytes.
-spec sha3_224(Input, OutputLength) -> Result when Input :: libdecaf_nif:input(), OutputLength :: libdecaf_nif:output_length(), Result :: binary().
Hash iodata using sha3_224; the default digest length is 28 bytes. An explicit output length may truncate the digest to 0 through 28 bytes.
-spec sha3_224_final(State) -> Result when State :: libdecaf_nif:hash_state(), Result :: binary().
Return the full 28-byte sha3_224 digest without changing the native state.
-spec sha3_224_final(State, OutputLength) -> Result when State :: libdecaf_nif:hash_state(), OutputLength :: non_neg_integer(), Result :: binary().
Return an sha3_224 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 28.
-spec sha3_224_init() -> Result when Result :: libdecaf_nif:hash_state().
Initialize an immutable sha3_224 hash state with its full 28-byte digest length. Return the native state directly, without an algorithm tuple.
-spec sha3_224_update(State, Input) -> Result when State :: libdecaf_nif:hash_state(), Input :: iodata(), Result :: libdecaf_nif:hash_state().
Absorb iodata into an sha3_224 state and return a new native state. The input state remains reusable.
-spec sha3_256(Input) -> Result when Input :: libdecaf_nif:input(), Result :: binary().
Hash iodata using sha3_256; the default digest length is 32 bytes. An explicit output length may truncate the digest to 0 through 32 bytes.
-spec sha3_256(Input, OutputLength) -> Result when Input :: libdecaf_nif:input(), OutputLength :: libdecaf_nif:output_length(), Result :: binary().
Hash iodata using sha3_256; the default digest length is 32 bytes. An explicit output length may truncate the digest to 0 through 32 bytes.
-spec sha3_256_final(State) -> Result when State :: libdecaf_nif:hash_state(), Result :: binary().
Return the full 32-byte sha3_256 digest without changing the native state.
-spec sha3_256_final(State, OutputLength) -> Result when State :: libdecaf_nif:hash_state(), OutputLength :: non_neg_integer(), Result :: binary().
Return an sha3_256 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 32.
-spec sha3_256_init() -> Result when Result :: libdecaf_nif:hash_state().
Initialize an immutable sha3_256 hash state with its full 32-byte digest length. Return the native state directly, without an algorithm tuple.
-spec sha3_256_update(State, Input) -> Result when State :: libdecaf_nif:hash_state(), Input :: iodata(), Result :: libdecaf_nif:hash_state().
Absorb iodata into an sha3_256 state and return a new native state. The input state remains reusable.
-spec sha3_384(Input) -> Result when Input :: libdecaf_nif:input(), Result :: binary().
Hash iodata using sha3_384; the default digest length is 48 bytes. An explicit output length may truncate the digest to 0 through 48 bytes.
-spec sha3_384(Input, OutputLength) -> Result when Input :: libdecaf_nif:input(), OutputLength :: libdecaf_nif:output_length(), Result :: binary().
Hash iodata using sha3_384; the default digest length is 48 bytes. An explicit output length may truncate the digest to 0 through 48 bytes.
-spec sha3_384_final(State) -> Result when State :: libdecaf_nif:hash_state(), Result :: binary().
Return the full 48-byte sha3_384 digest without changing the native state.
-spec sha3_384_final(State, OutputLength) -> Result when State :: libdecaf_nif:hash_state(), OutputLength :: non_neg_integer(), Result :: binary().
Return an sha3_384 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 48.
-spec sha3_384_init() -> Result when Result :: libdecaf_nif:hash_state().
Initialize an immutable sha3_384 hash state with its full 48-byte digest length. Return the native state directly, without an algorithm tuple.
-spec sha3_384_update(State, Input) -> Result when State :: libdecaf_nif:hash_state(), Input :: iodata(), Result :: libdecaf_nif:hash_state().
Absorb iodata into an sha3_384 state and return a new native state. The input state remains reusable.
-spec sha3_512(Input) -> Result when Input :: libdecaf_nif:input(), Result :: binary().
Hash iodata using sha3_512; the default digest length is 64 bytes. An explicit output length may truncate the digest to 0 through 64 bytes.
-spec sha3_512(Input, OutputLength) -> Result when Input :: libdecaf_nif:input(), OutputLength :: libdecaf_nif:output_length(), Result :: binary().
Hash iodata using sha3_512; the default digest length is 64 bytes. An explicit output length may truncate the digest to 0 through 64 bytes.
-spec sha3_512_final(State) -> Result when State :: libdecaf_nif:hash_state(), Result :: binary().
Return the full 64-byte sha3_512 digest without changing the native state.
-spec sha3_512_final(State, OutputLength) -> Result when State :: libdecaf_nif:hash_state(), OutputLength :: non_neg_integer(), Result :: binary().
Return an sha3_512 digest prefix without changing the native state. OutputLength is in bytes and must be between 0 and 64.
-spec sha3_512_init() -> Result when Result :: libdecaf_nif:hash_state().
Initialize an immutable sha3_512 hash state with its full 64-byte digest length. Return the native state directly, without an algorithm tuple.
-spec sha3_512_update(State, Input) -> Result when State :: libdecaf_nif:hash_state(), Input :: iodata(), Result :: libdecaf_nif:hash_state().
Absorb iodata into an sha3_512 state and return a new native state. The input state remains reusable.
-spec shake128(Input, OutputLength) -> Result when Input :: iodata(), OutputLength :: non_neg_integer(), Result :: binary().
Return OutputLength bytes of shake128 output from iodata.
-spec shake128_final(State, OutputLength) -> Result when State :: libdecaf_nif:xof_state(), OutputLength :: non_neg_integer(), Result :: binary().
Return OutputLength bytes from an absorbing shake128 state. Return only the output binary; finalizing the same immutable state repeats the output.
-spec shake128_init() -> Result when Result :: libdecaf_nif:xof_state().
Initialize an immutable absorbing shake128 native state.
-spec shake128_update(State, Input) -> Result when State :: libdecaf_nif:xof_state(), Input :: iodata(), Result :: libdecaf_nif:xof_state().
Absorb iodata into shake128 and return a new native state. The input state remains reusable.
-spec shake256(Input, OutputLength) -> Result when Input :: iodata(), OutputLength :: non_neg_integer(), Result :: binary().
Return OutputLength bytes of shake256 output from iodata.
-spec shake256_final(State, OutputLength) -> Result when State :: libdecaf_nif:xof_state(), OutputLength :: non_neg_integer(), Result :: binary().
Return OutputLength bytes from an absorbing shake256 state. Return only the output binary; finalizing the same immutable state repeats the output.
-spec shake256_init() -> Result when Result :: libdecaf_nif:xof_state().
Initialize an immutable absorbing shake256 native state.
-spec shake256_update(State, Input) -> Result when State :: libdecaf_nif:xof_state(), Input :: iodata(), Result :: libdecaf_nif:xof_state().
Absorb iodata into shake256 and return a new native state. The input state remains reusable.
-spec spongerng_init_from_buffer(Seed, Deterministic) -> Result when Seed :: iodata(), Deterministic :: boolean(), Result :: libdecaf_nif:spongerng_state().
Initialize a sponge PRNG from seed bytes.
Deterministic selects the upstream PRNG's deterministic mode.
-spec spongerng_init_from_dev_urandom() -> Result when Result :: libdecaf_nif:spongerng_state().
Initialize a sponge PRNG using /dev/urandom.
Raise an exception if the entropy source cannot be read.
-spec spongerng_init_from_file(Filename, InputLen, Deterministic) -> Result when Filename :: iodata(), InputLen :: non_neg_integer(), Deterministic :: boolean(), Result :: libdecaf_nif:spongerng_state().
Initialize a sponge PRNG by reading InputLen bytes from a file.
Filename contains nonempty native filename bytes; file errors raise an exception.
-spec spongerng_next(State, OutputLen) -> Result when State :: libdecaf_nif:spongerng_state(), OutputLen :: non_neg_integer(), Result :: {libdecaf_nif:spongerng_state(), binary()}.
Generate bytes and return the new PRNG state together with those bytes. Continue with the returned state to advance the stream.
-spec spongerng_stir(State, Input) -> Result when State :: libdecaf_nif:spongerng_state(), Input :: iodata(), Result :: libdecaf_nif:spongerng_state().
Mix additional seed bytes into a PRNG state and return a new state.
-spec x448(PublicKey, Scalar) -> Result when PublicKey :: libdecaf_nif:x448_public_key(), Scalar :: libdecaf_nif:x448_scalar(), Result :: libdecaf_nif:x448_shared_secret() | error.
Compute a Diffie-Hellman shared secret.
The public key comes first and the secret scalar second.
Return error when the upstream operation rejects the input, including low-order points.
-spec x448_derive_public_key(Scalar) -> Result when Scalar :: libdecaf_nif:x448_scalar(), Result :: libdecaf_nif:x448_public_key().
Derive an X448 public key from a secret scalar.
-spec x448_generate_key(Scalar) -> Result when Scalar :: libdecaf_nif:x448_scalar(), Result :: libdecaf_nif:x448_public_key().
Derive an X448 public key from a secret scalar.
-spec x25519(PublicKey, Scalar) -> Result when PublicKey :: libdecaf_nif:x25519_public_key(), Scalar :: libdecaf_nif:x25519_scalar(), Result :: libdecaf_nif:x25519_shared_secret() | error.
Compute a Diffie-Hellman shared secret.
The public key comes first and the secret scalar second.
Return error when the upstream operation rejects the input, including low-order points.
-spec x25519_derive_public_key(Scalar) -> Result when Scalar :: libdecaf_nif:x25519_scalar(), Result :: libdecaf_nif:x25519_public_key().
Derive an X25519 public key from a secret scalar.
-spec x25519_generate_key(Scalar) -> Result when Scalar :: libdecaf_nif:x25519_scalar(), Result :: libdecaf_nif:x25519_public_key().
Derive an X25519 public key from a secret scalar.
ECDH API
-spec ecdh_keypair(Type) -> Keypair when Type :: x25519, Keypair :: x25519_keypair(); (Type) -> Keypair when Type :: x448, Keypair :: x448_keypair().
Generate a random ECDH keypair.
Keep the opaque keypair for repeated operations; extract bytes when needed.
Keypair = libdecaf:ecdh_keypair(x25519),
PublicKey = libdecaf:ecdh_keypair_extract_public_key(Keypair).-spec ecdh_keypair(Type, SecretKey) -> Keypair when Type :: x25519, SecretKey :: x25519_secret_key(), Keypair :: x25519_keypair(); (Type, SecretKey) -> Keypair when Type :: x448, SecretKey :: x448_secret_key(), Keypair :: x448_keypair().
Derive an ECDH keypair from an existing secret scalar.
X25519 uses 32 bytes; X448 uses 56. The scalar is clamped inside the native operation; extraction returns the supplied bytes.
SecretKey = crypto:strong_rand_bytes(32),
Keypair = libdecaf:ecdh_keypair(x25519, SecretKey),
SecretKey = libdecaf:ecdh_keypair_extract_secret_key(Keypair).-spec ecdh_keypair_extract(Keypair) -> Keys when Keypair :: x25519_keypair(), Keys :: {x25519_public_key(), x25519_secret_key()}; (Keypair) -> Keys when Keypair :: x448_keypair(), Keys :: {x448_public_key(), x448_secret_key()}.
Return {PublicKey, SecretKey} in that order.
-spec ecdh_keypair_extract_public_key(Keypair) -> PublicKey when Keypair :: x25519_keypair(), PublicKey :: x25519_public_key(); (Keypair) -> PublicKey when Keypair :: x448_keypair(), PublicKey :: x448_public_key().
Extract the public-key bytes.
-spec ecdh_keypair_extract_secret_key(Keypair) -> SecretKey when Keypair :: x25519_keypair(), SecretKey :: x25519_secret_key(); (Keypair) -> SecretKey when Keypair :: x448_keypair(), SecretKey :: x448_secret_key().
Extract the original secret scalar bytes.
EdDSA API
-spec eddsa_keypair(Type) -> Keypair when Type :: ed25519, Keypair :: ed25519_keypair_state(); (Type) -> Keypair when Type :: ed448, Keypair :: ed448_keypair_state().
Generate a random EdDSA keypair.
Keep the opaque keypair for repeated operations; extract bytes when needed.
Keypair = libdecaf:eddsa_keypair(ed25519),
PublicKey = libdecaf:eddsa_keypair_extract_public_key(Keypair).-spec eddsa_keypair(Type, SecretKey) -> Keypair when Type :: ed25519, SecretKey :: ed25519_secret_key(), Keypair :: ed25519_keypair_state(); (Type, SecretKey) -> Keypair when Type :: ed448, SecretKey :: ed448_secret_key(), Keypair :: ed448_keypair_state().
Derive an EdDSA keypair from an existing secret seed.
Ed25519 uses a 32-byte seed; Ed448 uses a 57-byte seed. Contexts belong to signing/verification parameters, not keypairs.
SecretKey = crypto:strong_rand_bytes(32),
Keypair = libdecaf:eddsa_keypair(ed25519, SecretKey),
SecretKey = libdecaf:eddsa_keypair_extract_secret_key(Keypair).-spec eddsa_keypair_extract(Keypair) -> Keys when Keypair :: ed25519_keypair_state(), Keys :: {ed25519_public_key(), ed25519_secret_key()}; (Keypair) -> Keys when Keypair :: ed448_keypair_state(), Keys :: {ed448_public_key(), ed448_secret_key()}.
Return {PublicKey, SecretKey} in that order. For EdDSA, the secret is the original seed, not the
encoded seed/public-key signing key.
-spec eddsa_keypair_extract_public_key(Keypair) -> PublicKey when Keypair :: ed25519_keypair_state(), PublicKey :: ed25519_public_key(); (Keypair) -> PublicKey when Keypair :: ed448_keypair_state(), PublicKey :: ed448_public_key().
Extract the public-key bytes. For EdDSA, the secret is the original seed, not the encoded seed/public-key signing key.
-spec eddsa_keypair_extract_secret_key(Keypair) -> SecretKey when Keypair :: ed25519_keypair_state(), SecretKey :: ed25519_secret_key(); (Keypair) -> SecretKey when Keypair :: ed448_keypair_state(), SecretKey :: ed448_secret_key().
Extract the original secret seed bytes. For EdDSA, the secret is the original seed, not the encoded seed/public-key signing key.
-spec eddsa_sign(Parameters, Message) -> Signature when Parameters :: ed25519_sign_parameters(), Message :: message(), Signature :: ed25519_signature(); (Parameters, Message) -> Signature when Parameters :: ed448_sign_parameters(), Message :: message(), Signature :: ed448_signature().
Sign a message using {Algorithm, Key} or {Algorithm, Key, Context}.
Signing keys may be original seeds, encoded Seed || PublicKey binaries, public/secret pairs, or
opaque keypairs. Encoded keys and pairs are checked for matching public keys. Messages accept
iodata; pass the original message even for prehash variants. Contexts are binaries of at most 255
bytes and default to <<>>. Pure Ed25519 accepts no context; Ed25519ctx with an empty context is
distinct from pure Ed25519.
Keypair = libdecaf:eddsa_keypair(ed25519),
Signature = libdecaf:eddsa_sign({ed25519, Keypair}, <<"message">>),
PublicKey = libdecaf:eddsa_keypair_extract_public_key(Keypair),
true = libdecaf:eddsa_verify({ed25519, PublicKey}, Signature, <<"message">>).-spec eddsa_sign_final(State) -> Signature when State :: ed25519ph_sign_state(), Signature :: ed25519_signature(); (State) -> Signature when State :: ed448ph_sign_state(), Signature :: ed448_signature().
Sign the accumulated original message using the retained keypair and context. The input state is unchanged; repeated finalization returns the same result. The signature matches one-shot signing with the same parameters.
-spec eddsa_sign_init(Parameters) -> State when Parameters :: ed25519_sign_init_parameters(), State :: ed25519ph_sign_state(); (Parameters) -> State when Parameters :: ed448_sign_init_parameters(), State :: ed448ph_sign_state().
Start streaming signing with Ed25519ph or Ed448ph.
Signing keys may be original seeds, encoded Seed || PublicKey binaries, public/secret pairs, or
opaque keypairs. Encoded keys and pairs are checked for matching public keys. Messages accept
iodata; pass the original message even for prehash variants. Contexts are binaries of at most 255
bytes and default to <<>>. Pure Ed25519 accepts no context; Ed25519ctx with an empty context is
distinct from pure Ed25519. The native state retains the key, context and prehash. Updates and
finalization leave their input reusable. Pure Ed25519, Ed25519ctx, and Ed448 are one-shot only.
Keypair = libdecaf:eddsa_keypair(ed25519),
S0 = libdecaf:eddsa_sign_init({ed25519ph, Keypair, <<"protocol/v1">>}),
S1 = libdecaf:eddsa_sign_update(S0, [<<"hello ">>, <<"world">>]),
Signature = libdecaf:eddsa_sign_final(S1).-spec eddsa_sign_update(State, Message) -> NextState when State :: ed25519ph_sign_state(), Message :: message(), NextState :: ed25519ph_sign_state(); (State, Message) -> NextState when State :: ed448ph_sign_state(), Message :: message(), NextState :: ed448ph_sign_state().
Add another original-message chunk and return a new signing state.
Chunks accept iodata. Large updates yield to the scheduler; completed updates do not retain the input chunks. The original state remains reusable for branching. Signing and verification states are distinct.
-spec eddsa_verify(Parameters, Signature, Message) -> Valid when Parameters :: ed25519_verify_parameters(), Signature :: ed25519_signature(), Message :: message(), Valid :: boolean(); (Parameters, Signature, Message) -> Valid when Parameters :: ed448_verify_parameters(), Signature :: ed448_signature(), Message :: message(), Valid :: boolean().
Verify a signature over an original message using the same algorithm and context as signing.
Parameters contain a public key, public/secret pair, or opaque keypair. Return false for a
correctly sized signature that fails verification; malformed keys, signatures, or parameters raise
badarg. Message input accepts iodata.
Keypair = libdecaf:eddsa_keypair(ed448),
Signature = libdecaf:eddsa_sign({ed448, Keypair, <<"protocol/v1">>}, <<"message">>),
true = libdecaf:eddsa_verify({ed448, Keypair, <<"protocol/v1">>}, Signature, <<"message">>).-spec eddsa_verify_final(State) -> Valid when State :: ed25519ph_verify_state(), Valid :: boolean(); (State) -> Valid when State :: ed448ph_verify_state(), Valid :: boolean().
Verify the accumulated original message against the retained signature, key, and context. The input
state is unchanged; repeated finalization returns the same result. Return false if verification
fails.
-spec eddsa_verify_init(Parameters, Signature) -> State when Parameters :: ed25519_verify_init_parameters(), Signature :: ed25519_signature(), State :: ed25519ph_verify_state(); (Parameters, Signature) -> State when Parameters :: ed448_verify_init_parameters(), Signature :: ed448_signature(), State :: ed448ph_verify_state().
Start streaming verification with Ed25519ph or Ed448ph.
Use {Algorithm, PublicKeyOrKeypair} with an optional third context field, matching the signing
parameters. The native state retains the key, context, signature and prehash. Updates and
finalization leave their input reusable. Pure Ed25519, Ed25519ctx, and Ed448 are one-shot only.
Keypair = libdecaf:eddsa_keypair(ed25519),
S0 = libdecaf:eddsa_sign_init({ed25519ph, Keypair, <<"protocol/v1">>}),
S1 = libdecaf:eddsa_sign_update(S0, [<<"hello ">>, <<"world">>]),
Signature = libdecaf:eddsa_sign_final(S1),
V0 = libdecaf:eddsa_verify_init({ed25519ph, Keypair, <<"protocol/v1">>}, Signature),
V1 = libdecaf:eddsa_verify_update(V0, <<"hello world">>),
true = libdecaf:eddsa_verify_final(V1).-spec eddsa_verify_update(State, Message) -> NextState when State :: ed25519ph_verify_state(), Message :: message(), NextState :: ed25519ph_verify_state(); (State, Message) -> NextState when State :: ed448ph_verify_state(), Message :: message(), NextState :: ed448ph_verify_state().
Add another original-message chunk and return a new verification state.
Chunks accept iodata. Large updates yield to the scheduler; completed updates do not retain the input chunks. The original state remains reusable for branching. Signing and verification states are distinct.
Hash API
-spec hash(Parameters, Input) -> Output when Parameters :: hash_parameters(), Input :: input() | tuple_input(), Output :: binary().
Hash input using an algorithm atom or initialization parameter tuple.
Tuple fields match hash_init/1. For TupleHash, input is a list of separate elements.
Output = libdecaf:hash({parallelhash128, 32, 8192, <<"orders/v1">>}, <<"invoice-42">>),
State = libdecaf:hash_update(libdecaf:hash_init({parallelhash128, 32, 8192, <<"orders/v1">>}), <<"invoice-42">>),
Output = libdecaf:hash_final(State).-spec hash_final(HashState) -> Output when HashState :: hash_state(), Output :: binary().
Return the digest or authentication tag at the length chosen during initialization.
This leaves the state reusable. KMAC, TupleHash, and ParallelHash include the chosen length in their computation: initialize at the desired length instead of truncating a longer result. SHA-2, SHA-3, and legacy Keccak return digest prefixes when shortened.
Key = binary:copy(<<42>>, 32),
State0 = libdecaf:hash_init({kmac128, 16, Key}),
State1 = libdecaf:hash_update(State0, <<"invoice-42">>),
Tag = libdecaf:hash_final(State1),
16 = byte_size(Tag),
Tag = libdecaf:hash({kmac128, 16, Key}, <<"invoice-42">>).-spec hash_init(Parameters) -> Result when Parameters :: hash_parameters(), Result :: hash_state().
Initialize a hash using an algorithm atom or a parameter tuple.
Tuple fields put the algorithm first, then output length and construction-specific options.
For example, {kmac128, 32, Key, <<"orders/v1">>} selects a 32-byte KMAC tag.
The output length belongs to the state; finish with hash_final/1.
Parameter forms (L is output bytes, S is customization, and B is block bytes):
| Algorithms | Parameters |
|---|---|
| SHA-2, SHA-3, fixed Keccak | Algorithm or {Algorithm, L} |
| SHAKE, Keccak XOF | {Algorithm, L} |
| cSHAKE | {Algorithm, L} or {Algorithm, L, FunctionName, S} |
| KMAC, HopMAC | {Algorithm, L, Key} or {Algorithm, L, Key, S} |
| KT | Algorithm, {Algorithm, L}, or {Algorithm, L, S} |
| TurboSHAKE | Algorithm, {Algorithm, L}, or {Algorithm, L, Domain} |
| TupleHash128, TupleHash256 | {Algorithm, L} or {Algorithm, L, S} |
| ParallelHash128, ParallelHash256 | {Algorithm, L, B} or {Algorithm, L, B, S} |
SHA-2, SHA-3, and fixed Keccak permit prefixes up to the full digest size.
KT and TurboSHAKE default to 32 bytes at strength 128 and 64 at strength 256.
TurboSHAKE's domain is an integer in 1..127, defaulting to 16#1F.
ParallelHash's positive block size affects the digest; update boundaries do not.
Blocks are processed serially in constant memory. Keys and customization accept
iodata; omitted customization and function names are empty.
State0 = libdecaf:hash_init({sha3_256, 16}),
State1 = libdecaf:hash_update(State0, <<"abc">>),
<<"3A985DA74FE225B2045C172D6BD390BD">> = binary:encode_hex(libdecaf:hash_final(State1)).-spec hash_update(HashState, Input) -> NewHashState when HashState :: hash_state(), Input :: input(), NewHashState :: hash_state().
Add input to a hash and return a new state.
Input accepts iodata. For TupleHash, each call adds one complete tuple element:
two calls with <<"a">> and <<"bc">> differ from two calls with <<"ab">> and <<"c">>.
An empty element counts; an empty one-shot list contains no elements.
The original state remains reusable, so it can be used to hash different suffixes.
-spec parallel_hash(Parameters, Input) -> Output when Parameters :: parallel_hash_parameters(), Input :: input(), Output :: binary().
Compute a parallel hash from initialization parameters and input.
Uses the same framing and produces the same bytes as hash/2.
Parallelism applies to independent leaves, without changing the algorithm.
Input = binary:copy(<<"abc">>, 10000),
Output = libdecaf:parallel_hash(kt128, Input),
Output = libdecaf:hash(kt128, Input).-spec parallel_hash_final(State) -> Output when State :: parallel_hash_state(), Output :: binary().
Return the configured hash output without changing the input state.
State = libdecaf:parallel_hash_update(libdecaf:parallel_hash_init(kt128), <<"abc">>),
Digest = libdecaf:parallel_hash_final(State),
Digest = libdecaf:hash(kt128, <<"abc">>).-spec parallel_hash_init(Parameters) -> State when Parameters :: parallel_hash_parameters(), State :: parallel_hash_state().
Initialize a parallel Hash state.
Accepts the same parameter forms as hash_init/1 for KT128, KT256,
HopMAC128, HopMAC256, and ParallelHash128, ParallelHash256.
Other algorithms raise badarg. KT and HopMAC use 8192-byte leaves;
ParallelHash uses its configured block size. States remain immutable.
S0 = libdecaf:parallel_hash_init({parallelhash128, 32, 8192}),
S1 = libdecaf:parallel_hash_update(S0, <<"invoice-42">>),
Output = libdecaf:parallel_hash_final(S1).-spec parallel_hash_update(State, Input) -> NewState when State :: parallel_hash_state(), Input :: input(), NewState :: parallel_hash_state().
Add input to a parallel Hash state and return its new state.
Input accepts iodata. Large inputs are processed concurrently using the application's worker pool, while results are combined in input order. The previous state remains reusable. Without a worker pool, the call still completes using the caller's dirty scheduler.
Sponge PRNG API
-spec strong_rand_bytes(Length) -> Output when Length :: non_neg_integer(), Output :: binary().
Generate Length cryptographically random bytes without managing a PRNG state.
The generator is seeded automatically from operating-system entropy and
reseeded periodically. If native entropy is unavailable, it uses
crypto:strong_rand_bytes/1 to obtain seed bytes. An entropy-source failure
raises an exception. A zero-byte request returns <<>>.
For an explicitly seeded or deterministic stream, use libdecaf_spongerng.
Token = libdecaf:strong_rand_bytes(32),
32 = byte_size(Token),
<<>> = libdecaf:strong_rand_bytes(0).XOF API
-spec parallel_xof(Parameters, Input, OutputLength) -> Output when Parameters :: parallel_xof_parameters(), Input :: input(), OutputLength :: output_length(), Output :: binary().
Compute parallel XOF output from initialization parameters and input.
Uses the same framing and produces the same bytes as xof/3.
Parallelism applies to independent leaves, without changing the algorithm.
Input = binary:copy(<<"abc">>, 10000),
Output = libdecaf:parallel_xof(kt128, Input, 64),
Output = libdecaf:xof(kt128, Input, 64).-spec parallel_xof_absorb(State, Input) -> NewState when State :: parallel_xof_state(), Input :: input(), NewState :: parallel_xof_state().
Add input to a parallel XOF state and return its new state.
Input accepts iodata. Large inputs are processed concurrently using the application's worker pool, while results are combined in input order. The previous state remains reusable. Without a worker pool, the call still completes using the caller's dirty scheduler.
-spec parallel_xof_init(Parameters) -> State when Parameters :: parallel_xof_parameters(), State :: parallel_xof_state().
Initialize a parallel XOF state.
Accepts the same parameter forms as xof_init/1 for KT128, KT256,
HopMAC128, HopMAC256, and ParallelHashXOF128, ParallelHashXOF256.
Other algorithms raise badarg. KT and HopMAC use 8192-byte leaves;
ParallelHash uses its configured block size. States remain immutable.
S0 = libdecaf:parallel_xof_init({parallelhashxof128, 8192}),
S1 = libdecaf:parallel_xof_absorb(S0, <<"invoice-42">>),
{_S2, Output} = libdecaf:parallel_xof_squeeze(S1, 32).-spec parallel_xof_squeeze(State, OutputLength) -> Result when State :: parallel_xof_state(), OutputLength :: output_length(), Result :: {parallel_xof_state(), binary()}.
Read output and return {NextState, Output}.
The returned state can keep squeezing, but cannot absorb further input. The input state remains reusable. Output lengths are in bytes.
S0 = libdecaf:parallel_xof_absorb(libdecaf:parallel_xof_init(kt128), <<"abc">>),
{S1, First} = libdecaf:parallel_xof_squeeze(S0, 32),
{_S2, Next} = libdecaf:parallel_xof_squeeze(S1, 32),
Combined = <<First/binary, Next/binary>>,
Combined = libdecaf:xof(kt128, <<"abc">>, 64).-spec xof(Parameters, Input, OutputLength) -> Output when Parameters :: xof_parameters(), Input :: input() | tuple_input(), OutputLength :: output_length(), Output :: binary().
Return OutputLength bytes using XOF initialization parameters and input.
The parameter atom or tuple is identical to xof_init/1; output length is supplied
separately. For TupleHashXOF, input is a list of separate elements.
Parameters = {cshake128, <<>>, <<"orders/v1">>},
Output = libdecaf:xof(Parameters, <<"invoice-42">>, 32),
State = libdecaf:xof_absorb(libdecaf:xof_init(Parameters), <<"invoice-42">>),
{_Next, Output} = libdecaf:xof_squeeze(State, 32).-spec xof_absorb(XOFState, Input) -> NewXOFState when XOFState :: xof_state(), Input :: input(), NewXOFState :: xof_state().
Add input to an absorbing XOF and return a new state.
Input accepts iodata. For TupleHashXOF each call adds one whole tuple element; for all other algorithms calls concatenate message bytes. After squeezing starts, the returned squeezing state rejects further input, even after a zero-byte squeeze. The original absorbing state remains reusable.
-spec xof_init(Parameters) -> Result when Parameters :: xof_parameters(), Result :: xof_state().
Initialize an XOF using an algorithm atom or a parameter tuple.
Tuple fields put the algorithm first, followed by its construction-specific options.
Choose customization, keys, block sizes, or domain separation here; output length
is chosen later with xof_squeeze/2.
The SHA-3 derived functions follow the streaming definitions in SP 800-185r1.
| Algorithms | Parameters |
|---|---|
| SHAKE, Keccak XOF | Algorithm |
| cSHAKE | Algorithm or {Algorithm, FunctionName, Customization} |
| KMACXOF128, KMACXOF256, HopMAC128, HopMAC256 | {Algorithm, Key} or {Algorithm, Key, Customization} |
| KT128, KT256, TupleHashXOF128, TupleHashXOF256 | Algorithm or {Algorithm, Customization} |
| TurboSHAKE | Algorithm or {Algorithm, Domain} |
| ParallelHashXOF128, ParallelHashXOF256 | {Algorithm, BlockSize} or {Algorithm, BlockSize, Customization} |
KMACXOF128, KMACXOF256, TupleHashXOF128, TupleHashXOF256, ParallelHashXOF128,
and ParallelHashXOF256 use the matching lowercase algorithm selectors. They produce
different output from KMAC128, KMAC256, TupleHash128, TupleHash256, ParallelHash128,
and ParallelHash256. Other XOF families are SHAKE, cSHAKE, Keccak XOF,
KT, TurboSHAKE, and HopMAC, each at strength 128 or 256.
Function names, keys, and customization accept iodata; empty cSHAKE strings yield
SHAKE output. TurboSHAKE uses an integer domain in 1..127, default 16#1F.
Keep KMACXOF and HopMAC states private like their keys.
State0 = libdecaf:xof_init({cshake128, <<>>, <<"orders/v1">>}),
State1 = libdecaf:xof_absorb(State0, <<"invoice-42">>),
{_State2, Output} = libdecaf:xof_squeeze(State1, 32),
Output = libdecaf:xof({cshake128, <<>>, <<"orders/v1">>}, <<"invoice-42">>, 32).-spec xof_squeeze(XOFState, Length) -> Result when XOFState :: xof_state(), Length :: output_length(), Result :: {xof_state(), binary()}.
Return {NextState, Output} with the next Length bytes of an XOF stream.
Continue with NextState to read subsequent bytes. Squeezing the same input state
again repeats those bytes, because states are immutable. A zero-byte squeeze still
enters the output phase. Customization is already stored by the initializer.
State0 = libdecaf:xof_init(shake128),
State1 = libdecaf:xof_absorb(State0, [<<"a">>, <<"bc">>]),
{State2, First} = libdecaf:xof_squeeze(State1, 16),
{_State3, Second} = libdecaf:xof_squeeze(State2, 16),
Output = <<First/binary, Second/binary>>,
Output = libdecaf:xof(shake128, <<"abc">>, 32).