5 Module N_DIGEST
gullradriel edited this page 2026-10-09 00:55:18 +02:00

DIGEST: message digests and HMAC

Functions

Name
int n_pbkdf2_hmac_sha256(const unsigned char * pass, size_t pass_len, const unsigned char * salt, size_t salt_len, unsigned int iterations, unsigned char * out, size_t out_len)
derive out_len key bytes from pass and salt with PBKDF2-HMAC-SHA256 over iterations rounds (RFC 2898).
int n_pbkdf2_hmac_sha1(const unsigned char * pass, size_t pass_len, const unsigned char * salt, size_t salt_len, unsigned int iterations, unsigned char * out, size_t out_len)
derive out_len key bytes from pass and salt with PBKDF2-HMAC-SHA1 over iterations rounds (RFC 2898).
int n_kdf_scrypt(const unsigned char * pass, size_t pass_len, const unsigned char * salt, size_t salt_len, uint64_t n, uint32_t r, uint32_t p, uint64_t maxmem, unsigned char * out, size_t out_len)
scrypt (RFC 7914) of pass with salt and cost parameters n (CPU/memory, a power of two), r (block size) and p (parallelization) into out (out_len bytes); maxmem bounds the working-memory in bytes.
int n_kdf_hkdf_sha256(const unsigned char * ikm, size_t ikm_len, const unsigned char * salt, size_t salt_len, const unsigned char * info, size_t info_len, unsigned char * out, size_t out_len)
HKDF-SHA256 (RFC 5869 extract-then-expand) of ikm with the given salt and info into out (out_len bytes).
int n_hmac_sha512(const unsigned char * key, size_t key_len, const unsigned char * data, size_t data_len, unsigned char * out)
compute HMAC-SHA512 of data under key into out (N_DIGEST_SHA512_LEN bytes).
int n_hmac_sha384(const unsigned char * key, size_t key_len, const unsigned char * data, size_t data_len, unsigned char * out)
compute HMAC-SHA384 of data under key into out (N_DIGEST_SHA384_LEN bytes).
int n_hmac_sha256(const unsigned char * key, size_t key_len, const unsigned char * data, size_t data_len, unsigned char * out)
compute HMAC-SHA256 of data under key into out (N_DIGEST_SHA256_LEN bytes).
int n_hmac_sha1(const unsigned char * key, size_t key_len, const unsigned char * data, size_t data_len, unsigned char * out)
compute HMAC-SHA1 of data under key into out (N_DIGEST_SHA1_LEN bytes).
int n_digest_sha512(const unsigned char * data, size_t len, unsigned char * out)
compute the SHA-512 digest of len bytes of data into out (N_DIGEST_SHA512_LEN bytes).
int n_digest_sha384(const unsigned char * data, size_t len, unsigned char * out)
compute the SHA-384 digest of len bytes of data into out (N_DIGEST_SHA384_LEN bytes).
N_STR * n_digest_sha256_hex(const unsigned char * data, size_t len)
compute the SHA-256 digest of data and return it as a lowercase hex N_STR; free with free_nstr.
int n_digest_sha256(const unsigned char * data, size_t len, unsigned char * out)
compute the SHA-256 digest of len bytes of data into out (N_DIGEST_SHA256_LEN bytes).
int n_digest_sha1(const unsigned char * data, size_t len, unsigned char * out)
compute the SHA-1 digest of len bytes of data into out (N_DIGEST_SHA1_LEN bytes).
int n_digest_md5(const unsigned char * data, size_t len, unsigned char * out)
compute the MD5 digest of len bytes of data into out (N_DIGEST_MD5_LEN bytes).
int n_digest_consttime_equal(const unsigned char * a, const unsigned char * b, size_t len)
constant-time comparison of two equal-length byte buffers (for verifying MACs/signatures without a timing side channel).
int n_digest_blake2b512(const unsigned char * data, size_t len, unsigned char * out)
compute the BLAKE2b-512 digest of len bytes of data into out (N_DIGEST_BLAKE2B512_LEN bytes).
int n_aead_chacha20poly1305_encrypt(const unsigned char * key, const unsigned char * iv, size_t iv_len, const unsigned char * aad, size_t aad_len, const unsigned char * pt, size_t pt_len, unsigned char * out_ct, unsigned char * out_tag)
ChaCha20-Poly1305 (RFC 8439) authenticated encryption.
int n_aead_chacha20poly1305_decrypt(const unsigned char * key, const unsigned char * iv, size_t iv_len, const unsigned char * aad, size_t aad_len, const unsigned char * ct, size_t ct_len, const unsigned char * tag, unsigned char * out_pt)
ChaCha20-Poly1305 authenticated decryption.
int n_aead_aes256gcm_encrypt(const unsigned char * key, const unsigned char * iv, size_t iv_len, const unsigned char * aad, size_t aad_len, const unsigned char * pt, size_t pt_len, unsigned char * out_ct, unsigned char * out_tag)
AES-256-GCM authenticated encryption.
int n_aead_aes256gcm_decrypt(const unsigned char * key, const unsigned char * iv, size_t iv_len, const unsigned char * aad, size_t aad_len, const unsigned char * ct, size_t ct_len, const unsigned char * tag, unsigned char * out_pt)
AES-256-GCM authenticated decryption.

Defines

Name
N_KDF_HAVE_EVP_KDF
1 when the linked library provides the EVP_KDF provider API behind n_kdf_hkdf_sha256() and n_kdf_scrypt() (OpenSSL 3.0+; never on LibreSSL), 0 otherwise
N_DIGEST_SHA512_LEN
output size in bytes of a SHA-512 digest
N_DIGEST_SHA384_LEN
output size in bytes of a SHA-384 digest
N_DIGEST_SHA256_LEN
output size in bytes of a SHA-256 digest
N_DIGEST_SHA1_LEN
output size in bytes of a SHA-1 digest
N_DIGEST_MD5_LEN
output size in bytes of an MD5 digest
N_DIGEST_HAVE_BLAKE2B512
1 when the linked library provides BLAKE2b-512 for n_digest_blake2b512() (OpenSSL 1.1.0+; never on LibreSSL), 0 otherwise
N_DIGEST_BLAKE2B512_LEN
BLAKE2b-512 digest length in bytes.
N_AEAD_HAVE_CHACHA20POLY1305
1 when the linked library provides ChaCha20-Poly1305 for the n_aead_chacha20poly1305_* pair (OpenSSL 1.1.0+, LibreSSL 3.6+), 0 otherwise
N_AEAD_CHACHA20POLY1305_TAG_LEN
authentication tag size in bytes for ChaCha20-Poly1305
N_AEAD_CHACHA20POLY1305_KEY_LEN
key size in bytes for ChaCha20-Poly1305
N_AEAD_AES256GCM_TAG_LEN
authentication tag size in bytes for AES-256-GCM
N_AEAD_AES256GCM_KEY_LEN
key size in bytes for AES-256-GCM

Functions Documentation

function n_pbkdf2_hmac_sha256

int n_pbkdf2_hmac_sha256(
    const unsigned char * pass,
    size_t pass_len,
    const unsigned char * salt,
    size_t salt_len,
    unsigned int iterations,
    unsigned char * out,
    size_t out_len
)

derive out_len key bytes from pass and salt with PBKDF2-HMAC-SHA256 over iterations rounds (RFC 2898).

A NULL pass or salt is treated as empty when its length is 0. Returns 0 on success, -1 on error.

function n_pbkdf2_hmac_sha1

int n_pbkdf2_hmac_sha1(
    const unsigned char * pass,
    size_t pass_len,
    const unsigned char * salt,
    size_t salt_len,
    unsigned int iterations,
    unsigned char * out,
    size_t out_len
)

derive out_len key bytes from pass and salt with PBKDF2-HMAC-SHA1 over iterations rounds (RFC 2898).

A NULL pass or salt is treated as empty when its length is 0. Returns 0 on success, -1 on error.

function n_kdf_scrypt

int n_kdf_scrypt(
    const unsigned char * pass,
    size_t pass_len,
    const unsigned char * salt,
    size_t salt_len,
    uint64_t n,
    uint32_t r,
    uint32_t p,
    uint64_t maxmem,
    unsigned char * out,
    size_t out_len
)

scrypt (RFC 7914) of pass with salt and cost parameters n (CPU/memory, a power of two), r (block size) and p (parallelization) into out (out_len bytes); maxmem bounds the working-memory in bytes.

Requires OpenSSL 3.0+ (EVP_KDF), which N_KDF_HAVE_EVP_KDF reports; returns -1 on older OpenSSL. Returns 0 on success, -1 on error.

function n_kdf_hkdf_sha256

int n_kdf_hkdf_sha256(
    const unsigned char * ikm,
    size_t ikm_len,
    const unsigned char * salt,
    size_t salt_len,
    const unsigned char * info,
    size_t info_len,
    unsigned char * out,
    size_t out_len
)

HKDF-SHA256 (RFC 5869 extract-then-expand) of ikm with the given salt and info into out (out_len bytes).

salt/info may be NULL when their length is 0. Requires OpenSSL 3.0+ (EVP_KDF), which N_KDF_HAVE_EVP_KDF reports; returns -1 on older OpenSSL. Returns 0 on success, -1 on error.

function n_hmac_sha512

int n_hmac_sha512(
    const unsigned char * key,
    size_t key_len,
    const unsigned char * data,
    size_t data_len,
    unsigned char * out
)

compute HMAC-SHA512 of data under key into out (N_DIGEST_SHA512_LEN bytes).

A NULL key or data is treated as empty when its length is 0. Returns 0 on success, -1 on error.

function n_hmac_sha384

int n_hmac_sha384(
    const unsigned char * key,
    size_t key_len,
    const unsigned char * data,
    size_t data_len,
    unsigned char * out
)

compute HMAC-SHA384 of data under key into out (N_DIGEST_SHA384_LEN bytes).

A NULL key or data is treated as empty when its length is 0. Returns 0 on success, -1 on error.

function n_hmac_sha256

int n_hmac_sha256(
    const unsigned char * key,
    size_t key_len,
    const unsigned char * data,
    size_t data_len,
    unsigned char * out
)

compute HMAC-SHA256 of data under key into out (N_DIGEST_SHA256_LEN bytes).

A NULL key or data is treated as empty when its length is 0. Returns 0 on success, -1 on error.

function n_hmac_sha1

int n_hmac_sha1(
    const unsigned char * key,
    size_t key_len,
    const unsigned char * data,
    size_t data_len,
    unsigned char * out
)

compute HMAC-SHA1 of data under key into out (N_DIGEST_SHA1_LEN bytes).

A NULL key or data is treated as empty when its length is 0. Returns 0 on success, -1 on error.

function n_digest_sha512

int n_digest_sha512(
    const unsigned char * data,
    size_t len,
    unsigned char * out
)

compute the SHA-512 digest of len bytes of data into out (N_DIGEST_SHA512_LEN bytes).

Returns 0 on success, -1 on error.

function n_digest_sha384

int n_digest_sha384(
    const unsigned char * data,
    size_t len,
    unsigned char * out
)

compute the SHA-384 digest of len bytes of data into out (N_DIGEST_SHA384_LEN bytes).

Returns 0 on success, -1 on error.

function n_digest_sha256_hex

N_STR * n_digest_sha256_hex(
    const unsigned char * data,
    size_t len
)

compute the SHA-256 digest of data and return it as a lowercase hex N_STR; free with free_nstr.

Returns NULL on error.

function n_digest_sha256

int n_digest_sha256(
    const unsigned char * data,
    size_t len,
    unsigned char * out
)

compute the SHA-256 digest of len bytes of data into out (N_DIGEST_SHA256_LEN bytes).

Returns 0 on success, -1 on error.

function n_digest_sha1

int n_digest_sha1(
    const unsigned char * data,
    size_t len,
    unsigned char * out
)

compute the SHA-1 digest of len bytes of data into out (N_DIGEST_SHA1_LEN bytes).

Returns 0 on success, -1 on error.

function n_digest_md5

int n_digest_md5(
    const unsigned char * data,
    size_t len,
    unsigned char * out
)

compute the MD5 digest of len bytes of data into out (N_DIGEST_MD5_LEN bytes).

Returns 0 on success, -1 on error.

function n_digest_consttime_equal

int n_digest_consttime_equal(
    const unsigned char * a,
    const unsigned char * b,
    size_t len
)

constant-time comparison of two equal-length byte buffers (for verifying MACs/signatures without a timing side channel).

Returns 1 when equal, 0 otherwise.

function n_digest_blake2b512

int n_digest_blake2b512(
    const unsigned char * data,
    size_t len,
    unsigned char * out
)

compute the BLAKE2b-512 digest of len bytes of data into out (N_DIGEST_BLAKE2B512_LEN bytes).

Returns 0 on success, -1 on error, and always -1 when N_DIGEST_HAVE_BLAKE2B512 is 0.

function n_aead_chacha20poly1305_encrypt

int n_aead_chacha20poly1305_encrypt(
    const unsigned char * key,
    const unsigned char * iv,
    size_t iv_len,
    const unsigned char * aad,
    size_t aad_len,
    const unsigned char * pt,
    size_t pt_len,
    unsigned char * out_ct,
    unsigned char * out_tag
)

ChaCha20-Poly1305 (RFC 8439) authenticated encryption.

key is N_AEAD_CHACHA20POLY1305_KEY_LEN bytes; iv is iv_len bytes (12 recommended); aad may be NULL when aad_len is 0. Writes pt_len ciphertext bytes to out_ct and N_AEAD_CHACHA20POLY1305_TAG_LEN tag bytes to out_tag. Returns 0 on success, -1 on error, and always -1 when N_AEAD_HAVE_CHACHA20POLY1305 is 0.

function n_aead_chacha20poly1305_decrypt

int n_aead_chacha20poly1305_decrypt(
    const unsigned char * key,
    const unsigned char * iv,
    size_t iv_len,
    const unsigned char * aad,
    size_t aad_len,
    const unsigned char * ct,
    size_t ct_len,
    const unsigned char * tag,
    unsigned char * out_pt
)

ChaCha20-Poly1305 authenticated decryption.

Arguments mirror n_aead_chacha20poly1305_encrypt; tag is the N_AEAD_CHACHA20POLY1305_TAG_LEN expected tag. Writes ct_len plaintext bytes to out_pt (which may hold unauthenticated bytes on failure, the caller must discard them). Returns 0 on success (authentic), -1 on error or a tag mismatch, and always -1 when N_AEAD_HAVE_CHACHA20POLY1305 is 0.

function n_aead_aes256gcm_encrypt

int n_aead_aes256gcm_encrypt(
    const unsigned char * key,
    const unsigned char * iv,
    size_t iv_len,
    const unsigned char * aad,
    size_t aad_len,
    const unsigned char * pt,
    size_t pt_len,
    unsigned char * out_ct,
    unsigned char * out_tag
)

AES-256-GCM authenticated encryption.

key is N_AEAD_AES256GCM_KEY_LEN bytes; iv is iv_len bytes (12 recommended); aad may be NULL when aad_len is 0. Writes pt_len ciphertext bytes to out_ct and N_AEAD_AES256GCM_TAG_LEN tag bytes to out_tag. Returns 0 on success, -1 on error.

function n_aead_aes256gcm_decrypt

int n_aead_aes256gcm_decrypt(
    const unsigned char * key,
    const unsigned char * iv,
    size_t iv_len,
    const unsigned char * aad,
    size_t aad_len,
    const unsigned char * ct,
    size_t ct_len,
    const unsigned char * tag,
    unsigned char * out_pt
)

AES-256-GCM authenticated decryption.

Arguments mirror n_aead_aes256gcm_encrypt; tag is the N_AEAD_AES256GCM_TAG_LEN expected tag. Writes ct_len plaintext bytes to out_pt only when the tag verifies. Returns 0 on success (authentic), -1 on error or a tag mismatch.

Macros Documentation

define N_KDF_HAVE_EVP_KDF

#define N_KDF_HAVE_EVP_KDF N_OSSL_HAVE_EVP_KDF

1 when the linked library provides the EVP_KDF provider API behind n_kdf_hkdf_sha256() and n_kdf_scrypt() (OpenSSL 3.0+; never on LibreSSL), 0 otherwise

define N_DIGEST_SHA512_LEN

#define N_DIGEST_SHA512_LEN 64

output size in bytes of a SHA-512 digest

define N_DIGEST_SHA384_LEN

#define N_DIGEST_SHA384_LEN 48

output size in bytes of a SHA-384 digest

define N_DIGEST_SHA256_LEN

#define N_DIGEST_SHA256_LEN 32

output size in bytes of a SHA-256 digest

define N_DIGEST_SHA1_LEN

#define N_DIGEST_SHA1_LEN 20

output size in bytes of a SHA-1 digest

define N_DIGEST_MD5_LEN

#define N_DIGEST_MD5_LEN 16

output size in bytes of an MD5 digest

define N_DIGEST_HAVE_BLAKE2B512

#define N_DIGEST_HAVE_BLAKE2B512 N_OSSL_HAVE_BLAKE2B512

1 when the linked library provides BLAKE2b-512 for n_digest_blake2b512() (OpenSSL 1.1.0+; never on LibreSSL), 0 otherwise

define N_DIGEST_BLAKE2B512_LEN

#define N_DIGEST_BLAKE2B512_LEN 64

BLAKE2b-512 digest length in bytes.

define N_AEAD_HAVE_CHACHA20POLY1305

#define N_AEAD_HAVE_CHACHA20POLY1305 N_OSSL_HAVE_CHACHA20POLY1305

1 when the linked library provides ChaCha20-Poly1305 for the n_aead_chacha20poly1305_* pair (OpenSSL 1.1.0+, LibreSSL 3.6+), 0 otherwise

define N_AEAD_CHACHA20POLY1305_TAG_LEN

#define N_AEAD_CHACHA20POLY1305_TAG_LEN 16

authentication tag size in bytes for ChaCha20-Poly1305

define N_AEAD_CHACHA20POLY1305_KEY_LEN

#define N_AEAD_CHACHA20POLY1305_KEY_LEN 32

key size in bytes for ChaCha20-Poly1305

define N_AEAD_AES256GCM_TAG_LEN

#define N_AEAD_AES256GCM_TAG_LEN 16

authentication tag size in bytes for AES-256-GCM

define N_AEAD_AES256GCM_KEY_LEN

#define N_AEAD_AES256GCM_KEY_LEN 32

key size in bytes for AES-256-GCM