hkds_server.h File Reference

This file contains HKDS server definitions. More...

#include "hkds_config.h"

Go to the source code of this file.

Data Structures
struct	hkds_master_key
	Contains the HKDS master key set. More...
struct	hkds_server_state
	Contains the HKDS server state. More...
struct	hkds_server_x8_state
	Contains the HKDS parallel x8 server state. More...

Functions
HKDS_EXPORT_API void	hkds_server_decrypt_message (hkds_server_state *state, const uint8_t *ciphertext, uint8_t *plaintext)
	Decrypt a message sent by the client.
HKDS_EXPORT_API bool	hkds_server_decrypt_verify_message (hkds_server_state *state, const uint8_t *ciphertext, const uint8_t *data, size_t datalen, uint8_t *plaintext)
	Verify a ciphertext's integrity with a keyed MAC and decrypt the message.
HKDS_EXPORT_API void	hkds_server_encrypt_token (hkds_server_state *state, uint8_t *etok)
	Encrypt a secret token key to send to the client.
HKDS_EXPORT_API void	hkds_server_generate_edk (const uint8_t *bdk, const uint8_t *did, uint8_t *edk)
	Generate the embedded device key (EDK) for a client.
HKDS_EXPORT_API void	hkds_server_generate_mdk (bool(*rng_generate)(uint8_t *, size_t), hkds_master_key *mdk, const uint8_t *kid)
	Generate a master key set.
HKDS_EXPORT_API void	hkds_server_initialize_state (hkds_server_state *state, hkds_master_key *mdk, const uint8_t *ksn)
	Initialize the HKDS server state.
HKDS_EXPORT_API void	hkds_server_decrypt_message_x8 (hkds_server_x8_state *state, const uint8_t ciphertext[HKDS_CACHX8_DEPTH][HKDS_MESSAGE_SIZE], uint8_t plaintext[HKDS_CACHX8_DEPTH][HKDS_MESSAGE_SIZE])
	Decrypt a 2-dimensional x8 set of client messages.
HKDS_EXPORT_API void	hkds_server_decrypt_verify_message_x8 (hkds_server_x8_state *state, const uint8_t ciphertext[HKDS_CACHX8_DEPTH][HKDS_MESSAGE_SIZE+HKDS_TAG_SIZE], const uint8_t data[HKDS_CACHX8_DEPTH][HKDS_MESSAGE_SIZE], size_t datalen, uint8_t plaintext[HKDS_CACHX8_DEPTH][HKDS_MESSAGE_SIZE], bool valid[HKDS_CACHX8_DEPTH])
	Verify and decrypt a 2-dimensional x8 set of client messages.
HKDS_EXPORT_API void	hkds_server_encrypt_token_x8 (hkds_server_x8_state *state, uint8_t etok[HKDS_CACHX8_DEPTH][HKDS_STK_SIZE+HKDS_TAG_SIZE])
	Encrypt a 2-dimensional x8 set of secret token keys.
HKDS_EXPORT_API void	hkds_server_generate_edk_x8 (const hkds_server_x8_state *state, const uint8_t did[HKDS_CACHX8_DEPTH][HKDS_DID_SIZE], uint8_t edk[HKDS_CACHX8_DEPTH][HKDS_EDK_SIZE])
	Generate a 2-dimensional x8 set of client embedded device keys.
HKDS_EXPORT_API void	hkds_server_initialize_state_x8 (hkds_server_x8_state *state, hkds_master_key *mdk, const uint8_t ksn[HKDS_CACHX8_DEPTH][HKDS_KSN_SIZE])
	Initialize a 2-dimensional x8 set of server states with client KSNs.

Detailed Description

This file contains HKDS server definitions.

This header defines the structures and function prototypes for the HKDS (Hierarchical Key Derivation System) server implementation. The HKDS server is responsible for managing key derivation, token exchange, and secure message processing for client devices. It supports both scalar operations and parallel vectorized operations (using x8 and x64 APIs) for improved performance.

Function Documentation

hkds_server_decrypt_message()

HKDS_EXPORT_API void hkds_server_decrypt_message	(	hkds_server_state *	state,
		const uint8_t *	ciphertext,
		uint8_t *	plaintext )

Decrypt a message sent by the client.

This function decrypts an encrypted message received from a client by generating a transaction key from the server state and XORing it with the ciphertext.

Parameters

state	[in,out] Pointer to the HKDS server state.
ciphertext	[in] Pointer to the encrypted message array.
plaintext	[out] Pointer to the buffer where the decrypted message will be stored.

hkds_server_decrypt_message_x8()

HKDS_EXPORT_API void hkds_server_decrypt_message_x8	(	hkds_server_x8_state *	state,
		const uint8_t	ciphertext[HKDS_CACHX8_DEPTH][HKDS_MESSAGE_SIZE],
		uint8_t	plaintext[HKDS_CACHX8_DEPTH][HKDS_MESSAGE_SIZE] )

Decrypt a 2-dimensional x8 set of client messages.

This function decrypts an array of 8 client messages in parallel. For each message, a transaction key is generated, and the ciphertext is decrypted by XORing with the key.

Parameters

state	[in,out] Pointer to the HKDS x8 server state.
ciphertext	[in] A 2D array of 8 encrypted messages.
plaintext	[out] A 2D array where the decrypted messages will be stored.

hkds_server_decrypt_verify_message()

HKDS_EXPORT_API bool hkds_server_decrypt_verify_message	(	hkds_server_state *	state,
		const uint8_t *	ciphertext,
		const uint8_t *	data,
		size_t	datalen,
		uint8_t *	plaintext )

Verify a ciphertext's integrity with a keyed MAC and decrypt the message.

This function uses KMAC to verify the integrity of an encrypted client message before decrypting it. An optional data array (e.g., the originating client's IP address) can be incorporated into the MAC computation. If the MAC verification succeeds, the ciphertext is decrypted (by XORing with the transaction key) to recover the plaintext. On failure, the plaintext is zeroed.

Parameters

state	[in,out] Pointer to the HKDS server state.
ciphertext	[in] Pointer to the encrypted message array (which includes an appended MAC tag).
data	[in] Pointer to the additional data array for MAC computation.
datalen	[in] The length in bytes of the additional data array.
plaintext	[out] Pointer to the buffer where the decrypted message will be stored.

Returns

Returns true if the MAC verification is successful and decryption occurs; otherwise, false.

hkds_server_decrypt_verify_message_x8()

HKDS_EXPORT_API void hkds_server_decrypt_verify_message_x8	(	hkds_server_x8_state *	state,
		const uint8_t	ciphertext[HKDS_CACHX8_DEPTH][HKDS_MESSAGE_SIZE+HKDS_TAG_SIZE],
		const uint8_t	data[HKDS_CACHX8_DEPTH][HKDS_MESSAGE_SIZE],
		size_t	datalen,
		uint8_t	plaintext[HKDS_CACHX8_DEPTH][HKDS_MESSAGE_SIZE],
		bool	valid[HKDS_CACHX8_DEPTH] )

Verify and decrypt a 2-dimensional x8 set of client messages.

This function uses KMAC to verify the integrity of 8 client messages in parallel. If the MAC check succeeds, each ciphertext is decrypted and marked as valid; otherwise, the output is zeroed.

Parameters

state	[in,out] Pointer to the HKDS x8 server state.
ciphertext	[in] A 2D array of 8 encrypted messages (with appended MAC tags).
data	[in] A 2D array of additional data for MAC computation.
datalen	[in] The length (in bytes) of the additional data arrays.
plaintext	[out] A 2D array where the decrypted messages will be stored.
valid	[out] A boolean array indicating the verification status of each message.

hkds_server_encrypt_token()

HKDS_EXPORT_API void hkds_server_encrypt_token	(	hkds_server_state *	state,
		uint8_t *	etok )

Encrypt a secret token key to send to the client.

This function encrypts the secret token key using a derived encryption key based on a custom token string and the client's embedded device key. A MAC is computed over the encrypted token and appended to the output.

Parameters

state	[in,out] Pointer to the HKDS server state.
etok	[out] Pointer to the buffer where the encrypted token output key array will be stored.

hkds_server_encrypt_token_x8()

HKDS_EXPORT_API void hkds_server_encrypt_token_x8	(	hkds_server_x8_state *	state,
		uint8_t	etok[HKDS_CACHX8_DEPTH][HKDS_STK_SIZE+HKDS_TAG_SIZE] )

Encrypt a 2-dimensional x8 set of secret token keys.

This function encrypts secret token keys for 8 clients in parallel. The output is a 2D array of encrypted token keys with appended MAC tags.

Parameters

state	[in,out] Pointer to the HKDS x8 server state.
etok	[out] A 2D array where the encrypted token output key arrays will be stored.

hkds_server_generate_edk()

HKDS_EXPORT_API void hkds_server_generate_edk	(	const uint8_t *	bdk,
		const uint8_t *	did,
		uint8_t *	edk )

Generate the embedded device key (EDK) for a client.

The EDK is derived by concatenating the device's unique identity (DID) with the base derivation key (BDK) and then hashing the result using a SHAKE function. The resulting key is used in subsequent token and key derivation operations.

Parameters

bdk	[in] Pointer to the base derivation key array.
did	[in] Pointer to the device's unique identity string.
edk	[out] Pointer to the buffer where the embedded device key will be stored.

hkds_server_generate_edk_x8()

HKDS_EXPORT_API void hkds_server_generate_edk_x8	(	const hkds_server_x8_state *	state,
		const uint8_t	did[HKDS_CACHX8_DEPTH][HKDS_DID_SIZE],
		uint8_t	edk[HKDS_CACHX8_DEPTH][HKDS_EDK_SIZE] )

Generate a 2-dimensional x8 set of client embedded device keys.

This function generates embedded device keys for 8 clients in parallel, based on each client's device identity and the master key set.

Parameters

state	[in] Pointer to the HKDS x8 server state.
did	[in] A 2D array containing the device unique identity strings for 8 clients.
edk	[out] A 2D array where the embedded device keys will be stored.

hkds_server_generate_mdk()

HKDS_EXPORT_API void hkds_server_generate_mdk	(	bool(*	rng_generate )(uint8_t *, size_t),
		hkds_master_key *	mdk,
		const uint8_t *	kid )

Generate a master key set.

This function generates a new master key set by invoking a provided random generator function to produce key material. The generated data is split into the base derivation key (BDK) and the secret token key (STK), and the provided key identity (KID) is copied into the master key structure.

Parameters

rng_generate	[in] Pointer to the random generator function.
mdk	[out] Pointer to the master key set structure where the keys will be stored.
kid	[in] Pointer to the master key identity string.

hkds_server_initialize_state()

HKDS_EXPORT_API void hkds_server_initialize_state	(	hkds_server_state *	state,
		hkds_master_key *	mdk,
		const uint8_t *	ksn )

Initialize the HKDS server state.

This function initializes the server state by copying the client's key serial number (KSN), assigning the master key pointer, and initializing the token count and derivation rate.

Parameters

state	[in,out] Pointer to the HKDS server state.
mdk	[in] Pointer to the master key set.
ksn	[in] Pointer to the client's key serial number.

hkds_server_initialize_state_x8()

HKDS_EXPORT_API void hkds_server_initialize_state_x8	(	hkds_server_x8_state *	state,
		hkds_master_key *	mdk,
		const uint8_t	ksn[HKDS_CACHX8_DEPTH][HKDS_KSN_SIZE] )

Initialize a 2-dimensional x8 set of server states with client KSNs.

This function initializes the vectorized server state by copying each client's key serial number (KSN) and assigning the master key set.

Parameters

state	[in,out] Pointer to the HKDS x8 server state.
mdk	[in] Pointer to the master key set.
ksn	[in] A 2D array containing the client key serial numbers.