wsgcrypt.h File Reference

#include <wireshark.h>
#include <gcrypt.h>

Go to the source code of this file.

Macros
#define	HASH_MD5_LENGTH   16
#define	HASH_SHA1_LENGTH   20
#define	HASH_SHA2_224_LENGTH   28
#define	HASH_SHA2_256_LENGTH   32
#define	HASH_SHA2_384_LENGTH   48
#define	HASH_SHA2_512_LENGTH   64
#define	AEAD_AES_128_GCM_KEY_LENGTH   16
#define	AEAD_AES_256_GCM_KEY_LENGTH   32
#define	AEAD_CHACHA20POLY1305_KEY_LENGTH   32
#define	AEAD_MAX_KEY_LENGTH   32
#define	HPKE_AEAD_NONCE_LENGTH   12
#define	HPKE_HKDF_SHA256   1
#define	HPKE_HKDF_SHA384   2
#define	HPKE_HKDF_SHA512   3
#define	HPKE_AEAD_AES_128_GCM   1
#define	HPKE_AEAD_AES_256_GCM   2
#define	HPKE_AEAD_CHACHA20POLY1305   3
#define	HPKE_SUIT_ID_LEN   10
#define	HPKE_SUIT_PREFIX   "HPKE"
#define	HPKE_VERSION_ID   "HPKE-v1"
#define	HPKE_MAX_KDF_LEN   HASH_SHA2_512_LENGTH
#define	HPKE_MODE_BASE   0
#define	HPKE_MODE_PSK   1
#define	HPKE_MODE_AUTH   2
#define	HPKE_MODE_AUTH_PSK   3

Functions
WS_DLL_PUBLIC gcry_error_t	ws_hmac_buffer (int algo, void *digest, const void *buffer, size_t length, const void *key, size_t keylen)
	Compute HMAC over a buffer using the specified algorithm.
WS_DLL_PUBLIC gcry_error_t	ws_cmac_buffer (int algo, void *digest, const void *buffer, size_t length, const void *key, size_t keylen)
	Compute CMAC over a buffer using the specified algorithm.
WS_DLL_PUBLIC void	crypt_des_ecb (uint8_t *output, const uint8_t *buffer, const uint8_t *key56)
	Encrypt 8 bytes using DES in ECB mode.
WS_DLL_PUBLIC size_t	rsa_decrypt_inplace (const unsigned len, unsigned char *data, gcry_sexp_t pk, bool pkcs1_padding, char **err)
	Perform RSA decryption in-place.
WS_DLL_PUBLIC gcry_error_t	hkdf_expand (int hashalgo, const uint8_t *prk, unsigned prk_len, const uint8_t *info, unsigned info_len, uint8_t *out, unsigned out_len)
	Perform HKDF-Expand as defined in RFC 5869.
WS_DLL_PUBLIC uint16_t	hpke_hkdf_len (uint16_t kdf_id)
	Return the output length of the HKDF for a given KDF identifier.
WS_DLL_PUBLIC uint16_t	hpke_aead_key_len (uint16_t aead_id)
	Return the key length for a given AEAD algorithm identifier.
WS_DLL_PUBLIC uint16_t	hpke_aead_nonce_len (uint16_t aead_id)
	Return the nonce length for a given AEAD algorithm identifier.
WS_DLL_PUBLIC void	hpke_suite_id (uint16_t kem_id, uint16_t kdf_id, uint16_t aead_id, uint8_t *suite_id)
	Construct the HPKE suite identifier.
WS_DLL_PUBLIC gcry_error_t	hpke_key_schedule (uint16_t kdf_id, uint16_t aead_id, const uint8_t *salt, unsigned salt_len, const uint8_t *suite_id, const uint8_t *ikm, unsigned ikm_len, uint8_t mode, uint8_t *key, uint8_t *base_nonce)
	Derive HPKE key and base nonce using the key schedule.
WS_DLL_PUBLIC gcry_error_t	hpke_setup_aead (gcry_cipher_hd_t *cipher, uint16_t aead_id, uint8_t *key)
	Initialize AEAD cipher context for HPKE.
WS_DLL_PUBLIC gcry_error_t	hpke_set_nonce (gcry_cipher_hd_t cipher, uint64_t seq, uint8_t *base_nonce, size_t nonce_len)
	Set the nonce for an AEAD cipher using sequence number and base nonce.

Detailed Description

Wrapper around libgcrypt's include file gcrypt.h. For libgcrypt 1.5.0, including gcrypt.h directly brings up lots of compiler warnings about deprecated definitions. Try to work around these warnings to ensure a clean build with -Werror.

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 2007 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

Function Documentation

crypt_des_ecb()

WS_DLL_PUBLIC void crypt_des_ecb	(	uint8_t *	output,
		const uint8_t *	buffer,
		const uint8_t *	key56
	)

Encrypt 8 bytes using DES in ECB mode.

Convenience function to encrypt 8 bytes from buffer using DES with a 56-bit key expanded to 64 bits. The encrypted output is written to output, which must be at least 8 bytes in size.

Parameters

output	Destination buffer for encrypted data (must be ≥ 8 bytes).
buffer	Source buffer containing 8 bytes of plaintext.
key56	56-bit DES key (expanded internally to 64 bits).

hkdf_expand()

WS_DLL_PUBLIC gcry_error_t hkdf_expand	(	int	hashalgo,
		const uint8_t *	prk,
		unsigned	prk_len,
		const uint8_t *	info,
		unsigned	info_len,
		uint8_t *	out,
		unsigned	out_len
	)

Perform HKDF-Expand as defined in RFC 5869.

RFC 5869 HMAC-based Extract-and-Expand Key Derivation Function (HKDF): HKDF-Expand(PRK, info, L) -> OKM

Parameters

hashalgo	[in] Libgcrypt hash algorithm identifier.
prk	[in] Pseudo-random key.
prk_len	[in] Length of prk.
info	[in] Optional context (can be NULL if info_len is zero).
info_len	[in] Length of info.
out	[out] Output keying material.
out_len	[in] Size of output keying material.

Returns

0 on success and an error code otherwise.

hpke_aead_key_len()

WS_DLL_PUBLIC uint16_t hpke_aead_key_len

(

uint16_t

aead_id

)

Return the key length for a given AEAD algorithm identifier.

Convenience function for Hybrid Public Key Encryption (HPKE) as specified in RFC 9180. Returns the length in bytes of the symmetric key required by the AEAD algorithm.

Parameters

aead_id

AEAD algorithm identifier (e.g., HPKE_AEAD_AES_GCM_128).

Returns

Key length in bytes.

hpke_aead_nonce_len()

WS_DLL_PUBLIC uint16_t hpke_aead_nonce_len

(

uint16_t

aead_id

)

Return the nonce length for a given AEAD algorithm identifier.

Returns the length in bytes of the nonce required by the AEAD algorithm, as specified in RFC 9180 for HPKE.

Parameters

aead_id

AEAD algorithm identifier.

Returns

Nonce length in bytes.

hpke_hkdf_len()

WS_DLL_PUBLIC uint16_t hpke_hkdf_len

(

uint16_t

kdf_id

)

Return the output length of the HKDF for a given KDF identifier.

Convenience function for Hybrid Public Key Encryption (HPKE) as specified in RFC 9180. Returns the length of the HKDF output in bytes for the specified key derivation function (KDF). The returned value must fit within a 16-bit integer to ensure compatibility with I2OSP(L, 2) used in the ExpandedLabel construction.

Parameters

kdf_id

Identifier for the KDF algorithm (e.g., HPKE_KDF_HKDF_SHA256).

Returns

Length of the HKDF output in bytes.

hpke_key_schedule()

WS_DLL_PUBLIC gcry_error_t hpke_key_schedule	(	uint16_t	kdf_id,
		uint16_t	aead_id,
		const uint8_t *	salt,
		unsigned	salt_len,
		const uint8_t *	suite_id,
		const uint8_t *	ikm,
		unsigned	ikm_len,
		uint8_t	mode,
		uint8_t *	key,
		uint8_t *	base_nonce
	)

Derive HPKE key and base nonce using the key schedule.

Implements the HPKE key schedule as defined in RFC 9180. Derives the symmetric encryption key and base nonce from the input keying material (IKM), suite ID, and optional salt, using the specified KDF and AEAD identifiers.

Parameters

kdf_id	KDF algorithm identifier.
aead_id	AEAD algorithm identifier.
salt	Optional salt value for key derivation.
salt_len	Length of the salt in bytes.
suite_id	Suite identifier (must be 6 bytes).
ikm	Input keying material.
ikm_len	Length of the IKM in bytes.
mode	HPKE mode (e.g., base, PSK, auth).
key	Output buffer for the derived symmetric key.
base_nonce	Output buffer for the derived base nonce.

Returns

0 on success, or a Libgcrypt error code on failure.

hpke_set_nonce()

WS_DLL_PUBLIC gcry_error_t hpke_set_nonce	(	gcry_cipher_hd_t	cipher,
		uint64_t	seq,
		uint8_t *	base_nonce,
		size_t	nonce_len
	)

Set the nonce for an AEAD cipher using sequence number and base nonce.

Computes the AEAD nonce by XORing the base nonce with the sequence number, as specified in RFC 9180. Updates the cipher context with the resulting nonce.

Parameters

cipher	AEAD cipher handle.
seq	Sequence number for the message.
base_nonce	Base nonce derived from the key schedule.
nonce_len	Length of the nonce in bytes.

Returns

0 on success, or a Libgcrypt error code on failure.

hpke_setup_aead()

WS_DLL_PUBLIC gcry_error_t hpke_setup_aead	(	gcry_cipher_hd_t *	cipher,
		uint16_t	aead_id,
		uint8_t *	key
	)

Initialize AEAD cipher context for HPKE.

Sets up the AEAD cipher handle using the specified AEAD algorithm and key. This function prepares the cipher for encryption or decryption operations.

Parameters

cipher	Pointer to the cipher handle to initialize.
aead_id	AEAD algorithm identifier.
key	Symmetric key for AEAD encryption/decryption.

Returns

0 on success, or a Libgcrypt error code on failure.

hpke_suite_id()

WS_DLL_PUBLIC void hpke_suite_id	(	uint16_t	kem_id,
		uint16_t	kdf_id,
		uint16_t	aead_id,
		uint8_t *	suite_id
	)

Construct the HPKE suite identifier.

Builds the suite ID byte string from the KEM, KDF, and AEAD identifiers, as defined in RFC 9180. The resulting suite ID is written to the caller-provided buffer suite_id, which must be at least 6 bytes long.

Parameters

kem_id	KEM algorithm identifier.
kdf_id	KDF algorithm identifier.
aead_id	AEAD algorithm identifier.
suite_id	Output buffer for the suite ID (must be ≥ 6 bytes).

rsa_decrypt_inplace()

WS_DLL_PUBLIC size_t rsa_decrypt_inplace	(	const unsigned	len,
		unsigned char *	data,
		gcry_sexp_t	pk,
		bool	pkcs1_padding,
		char **	err
	)

Perform RSA decryption in-place.

Decrypts the data in data using the RSA private key pk. The decryption is performed in-place, and the function returns the length of the decrypted data on success, or 0 on failure. Optionally applies PKCS#1 padding if pkcs1_padding is true. If an error occurs, a descriptive message may be returned in err.

Parameters

len	Length of the encrypted input data.
data	Buffer containing encrypted data; overwritten with plaintext.
pk	RSA private key (gcry_sexp_t).
pkcs1_padding	Whether to apply PKCS#1 padding during decryption.
err	Optional pointer to receive error message (may be NULL).

Returns

Length of decrypted data on success, 0 on failure.

ws_cmac_buffer()

WS_DLL_PUBLIC gcry_error_t ws_cmac_buffer	(	int	algo,
		void *	digest,
		const void *	buffer,
		size_t	length,
		const void *	key,
		size_t	keylen
	)

Compute CMAC over a buffer using the specified algorithm.

Convenience function to calculate the CMAC from the data in buffer of size length with key key of size keylen using the algorithm algo. The result is written to the caller-provided digest buffer, which must be large enough to hold the digest for the selected algorithm.

Parameters

algo	CMAC algorithm identifier (e.g., GCRY_CIPHER_AES).
digest	Output buffer for the computed CMAC.
buffer	Input data buffer.
length	Length of the input data in bytes.
key	Key used for CMAC computation.
keylen	Length of the key in bytes.

Returns

GPG error code (0 on success).

ws_hmac_buffer()

WS_DLL_PUBLIC gcry_error_t ws_hmac_buffer	(	int	algo,
		void *	digest,
		const void *	buffer,
		size_t	length,
		const void *	key,
		size_t	keylen
	)

Compute HMAC over a buffer using the specified algorithm.

Convenience function to calculate the HMAC from the data in buffer of size length with key key of size keylen using the algorithm algo, without explicitly creating a hash object. The result is written to the caller-provided digest buffer, which must be large enough to hold the digest for the selected algorithm.

Parameters

algo	HMAC algorithm identifier (e.g., GCRY_MD_SHA256).
digest	Output buffer for the computed HMAC.
buffer	Input data buffer.
length	Length of the input data in bytes.
key	Key used for HMAC computation.
keylen	Length of the key in bytes.

Returns

GPG error code (0 on success).