DIGEST: message digests and HMAC

Macros
#define	N_AEAD_AES256GCM_KEY_LEN   32
	key size in bytes for AES-256-GCM
#define	N_AEAD_AES256GCM_TAG_LEN   16
	authentication tag size in bytes for AES-256-GCM
#define	N_AEAD_CHACHA20POLY1305_KEY_LEN   32
	key size in bytes for ChaCha20-Poly1305
#define	N_AEAD_CHACHA20POLY1305_TAG_LEN   16
	authentication tag size in bytes for ChaCha20-Poly1305
#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_DIGEST_BLAKE2B512_LEN   64
	BLAKE2b-512 digest length in bytes.
#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_MD5_LEN   16
	output size in bytes of an MD5 digest
#define	N_DIGEST_SHA1_LEN   20
	output size in bytes of a SHA-1 digest
#define	N_DIGEST_SHA256_LEN   32
	output size in bytes of a SHA-256 digest
#define	N_DIGEST_SHA384_LEN   48
	output size in bytes of a SHA-384 digest
#define	N_DIGEST_SHA512_LEN   64
	output size in bytes of a SHA-512 digest
#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

Functions
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.
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_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_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_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_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_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_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_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).
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_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).
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_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_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_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_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_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_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_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_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).

Detailed Description

Macro Definition Documentation

N_AEAD_AES256GCM_KEY_LEN

#define N_AEAD_AES256GCM_KEY_LEN   32

key size in bytes for AES-256-GCM

Examples

ex_digest.c.

Definition at line 111 of file n_digest.h.

Referenced by test_aead().

N_AEAD_AES256GCM_TAG_LEN

#define N_AEAD_AES256GCM_TAG_LEN   16

authentication tag size in bytes for AES-256-GCM

Examples

ex_digest.c.

Definition at line 113 of file n_digest.h.

Referenced by n_aead_aes256gcm_decrypt(), n_aead_aes256gcm_encrypt(), and test_aead().

N_AEAD_CHACHA20POLY1305_KEY_LEN

#define N_AEAD_CHACHA20POLY1305_KEY_LEN   32

key size in bytes for ChaCha20-Poly1305

Examples

ex_digest.c.

Definition at line 121 of file n_digest.h.

Referenced by test_aead_chacha().

N_AEAD_CHACHA20POLY1305_TAG_LEN

#define N_AEAD_CHACHA20POLY1305_TAG_LEN   16

authentication tag size in bytes for ChaCha20-Poly1305

Examples

ex_digest.c.

Definition at line 123 of file n_digest.h.

Referenced by test_aead_chacha().

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

Definition at line 59 of file n_digest.h.

N_DIGEST_BLAKE2B512_LEN

#define N_DIGEST_BLAKE2B512_LEN   64

BLAKE2b-512 digest length in bytes.

Examples

ex_digest.c.

Definition at line 75 of file n_digest.h.

Referenced by test_digests().

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

Definition at line 56 of file n_digest.h.

N_DIGEST_MD5_LEN

#define N_DIGEST_MD5_LEN   16

output size in bytes of an MD5 digest

Examples

ex_digest.c.

Definition at line 65 of file n_digest.h.

Referenced by test_digests().

N_DIGEST_SHA1_LEN

#define N_DIGEST_SHA1_LEN   20

output size in bytes of a SHA-1 digest

Examples

ex_digest.c.

Definition at line 67 of file n_digest.h.

Referenced by n_hmac_sha1(), test_digests(), and test_hmac_variants().

N_DIGEST_SHA256_LEN

#define N_DIGEST_SHA256_LEN   32

output size in bytes of a SHA-256 digest

Examples

ex_digest.c.

Definition at line 69 of file n_digest.h.

Referenced by n_digest_sha256_hex(), n_hmac_sha256(), test_digests(), test_errors(), and test_hmac().

N_DIGEST_SHA384_LEN

#define N_DIGEST_SHA384_LEN   48

output size in bytes of a SHA-384 digest

Examples

ex_digest.c.

Definition at line 71 of file n_digest.h.

Referenced by n_hmac_sha384(), test_digests(), and test_hmac_variants().

N_DIGEST_SHA512_LEN

#define N_DIGEST_SHA512_LEN   64

output size in bytes of a SHA-512 digest

Examples

ex_digest.c.

Definition at line 73 of file n_digest.h.

Referenced by n_hmac_sha512(), test_digests(), and test_hmac_variants().

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

Definition at line 62 of file n_digest.h.

Function Documentation

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.

Definition at line 212 of file n_digest.c.

References key, LOG_ERR, N_AEAD_AES256GCM_TAG_LEN, and n_log.

Referenced by test_aead().

Here is the caller graph for this 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.

Definition at line 174 of file n_digest.c.

References key, LOG_ERR, N_AEAD_AES256GCM_TAG_LEN, and n_log.

Referenced by test_aead().

Here is the caller graph for this 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.

Definition at line 353 of file n_digest.c.

References key, LOG_ERR, and n_log.

Referenced by test_aead_chacha().

Here is the caller graph for this 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.

Definition at line 339 of file n_digest.c.

References key, LOG_ERR, and n_log.

Referenced by test_aead_chacha().

Here is the caller graph for this 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.

Definition at line 86 of file n_digest.c.

References LOG_ERR, and n_log.

Referenced by test_digests().

Here is the caller graph for this 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.

Definition at line 141 of file n_digest.c.

Referenced by test_consttime().

Here is the caller graph for this 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.

Definition at line 58 of file n_digest.c.

References n_digest_oneshot().

Referenced by test_digests().

Here is the call graph for this function:

Here is the caller graph for this 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.

Definition at line 62 of file n_digest.c.

References n_digest_oneshot().

Referenced by test_digests().

Here is the call graph for this function:

Here is the caller graph for this 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.

Definition at line 66 of file n_digest.c.

References n_digest_oneshot().

Referenced by n_digest_sha256_hex(), test_digests(), and test_errors().

Here is the call graph for this function:

Here is the caller graph for this 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.

Definition at line 95 of file n_digest.c.

References n_digest_sha256(), N_DIGEST_SHA256_LEN, and n_hex_encode().

Referenced by test_sha256_hex().

Here is the call graph for this function:

Here is the caller graph for this 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.

Definition at line 70 of file n_digest.c.

References n_digest_oneshot().

Referenced by test_digests().

Here is the call graph for this function:

Here is the caller graph for this 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.

Definition at line 74 of file n_digest.c.

References n_digest_oneshot().

Referenced by test_digests().

Here is the call graph for this function:

Here is the caller graph for this 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.

Definition at line 125 of file n_digest.c.

References key, N_DIGEST_SHA1_LEN, and n_hmac_oneshot().

Referenced by test_hmac_variants().

Here is the call graph for this function:

Here is the caller graph for this 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.

Definition at line 129 of file n_digest.c.

References key, N_DIGEST_SHA256_LEN, and n_hmac_oneshot().

Referenced by test_errors(), and test_hmac().

Here is the call graph for this function:

Here is the caller graph for this 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.

Definition at line 133 of file n_digest.c.

References key, N_DIGEST_SHA384_LEN, and n_hmac_oneshot().

Referenced by test_hmac_variants().

Here is the call graph for this function:

Here is the caller graph for this 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.

Definition at line 137 of file n_digest.c.

References key, N_DIGEST_SHA512_LEN, and n_hmac_oneshot().

Referenced by test_hmac_variants().

Here is the call graph for this function:

Here is the caller graph for this 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.

Definition at line 440 of file n_digest.c.

References LOG_ERR, and n_log.

Referenced by test_kdf().

Here is the caller graph for this 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.

Definition at line 452 of file n_digest.c.

References LOG_ERR, and n_log.

Referenced by test_kdf().

Here is the caller graph for this 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.

Definition at line 166 of file n_digest.c.

References n_pbkdf2_oneshot().

Referenced by test_pbkdf2().

Here is the call graph for this function:

Here is the caller graph for this 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.

Definition at line 170 of file n_digest.c.

References n_pbkdf2_oneshot().

Referenced by test_pbkdf2().

Here is the call graph for this function:

Here is the caller graph for this function: