UDIF key derivation functions. More...

#include "udif.h"

Functions
UDIF_EXPORT_API void	udif_kdf_hash (uint8_t output, size_t outlen, const uint8_t input, size_t inplen, const uint8_t *name, size_t namelen)
	Compute a domain-separated hash.
UDIF_EXPORT_API void	udif_kdf_hash_custom (uint8_t output, size_t outlen, const uint8_t input, size_t inplen, const uint8_t name, size_t namelen, const uint8_t custom, size_t custlen)
	Compute a domain-separated hash with custom data.
UDIF_EXPORT_API void	udif_kdf_session_keys (uint8_t txkey, uint8_t txnonce, uint8_t rxkey, uint8_t rxnonce, uint8_t state, const uint8_t ikm, size_t ikmlen, const uint8_t *transcript, size_t transcriptlen, bool initiator)
	Derive session keys from handshake material.
UDIF_EXPORT_API void	udif_kdf_ratchet (uint8_t txkey, uint8_t txnonce, uint8_t rxkey, uint8_t rxnonce, uint8_t newstate, const uint8_t prevstate, const uint8_t kemsecret, size_t kemseclen, const uint8_t sessionid, size_t sessidlen, uint64_t epoch, bool initiator)
	Derive ratchet keys from KEM exchange.
UDIF_EXPORT_API void	udif_kdf_object_digest (uint8_t digest, const udif_object obj)
	Compute object digest.
UDIF_EXPORT_API void	udif_kdf_anchor_digest (uint8_t digest, const udif_anchor_record anchor)
	Compute anchor record digest.
UDIF_EXPORT_API void	udif_kdf_capability_digest (uint8_t digest, const udif_capability cap)
	Compute capability digest.
UDIF_EXPORT_API void	udif_kdf_transfer_digest (uint8_t digest, const uint8_t objserial, const uint8_t txid, const uint8_t toowner, uint64_t timestamp)
	Compute transfer transaction digest.
UDIF_EXPORT_API void	udif_kdf_session_id (uint8_t sessionid, const uint8_t localser, const uint8_t remoteser, const uint8_t ikm, size_t ikmlen)
	Compute session identifier.

Detailed Description

UDIF key derivation functions.

This module implements domain-separated key derivation using SHAKE-256 and cSHAKE-256. All cryptographic operations use domain separation labels to prevent cross-context attacks.

Key Functions:

Domain-separated hashing
Session key derivation
Asymmetric ratchet derivation
Digest computation for various structures

Function Documentation

◆ udif_kdf_anchor_digest()

UDIF_EXPORT_API void udif_kdf_anchor_digest	(	uint8_t *	digest,
		const udif_anchor_record *	anchor )

Compute anchor record digest.

Computes a canonical digest of an anchor record for signing or verification.

Parameters

digest	The output digest (32 bytes)
anchor	[const] The anchor record structure

Returns: Returns true if the function succeeded

◆ udif_kdf_capability_digest()

UDIF_EXPORT_API void udif_kdf_capability_digest	(	uint8_t *	digest,
		const udif_capability *	cap )

Compute capability digest.

Computes a canonical digest of a capability token for KMAC authentication.

Parameters

digest	The output digest (32 bytes)
cap	[const] The capability structure

Returns: Returns true if the function succeeded

◆ udif_kdf_hash()

UDIF_EXPORT_API void udif_kdf_hash	(	uint8_t *	output,
		size_t	outlen,
		const uint8_t *	input,
		size_t	inplen,
		const uint8_t *	name,
		size_t	namelen )

Compute a domain-separated hash.

Uses cSHAKE-256 with a domain separation label to compute a hash. The label ensures that hashes computed for different purposes cannot be confused or substituted.

Parameters

output	The output hash buffer
outlen	The output length in bytes
name	[const] The domain separation label string
namelen	The name length in bytes
input	[const] The input data
inlen	The input length in bytes

◆ udif_kdf_hash_custom()

UDIF_EXPORT_API void udif_kdf_hash_custom	(	uint8_t *	output,
		size_t	outlen,
		const uint8_t *	input,
		size_t	inplen,
		const uint8_t *	name,
		size_t	namelen,
		const uint8_t *	custom,
		size_t	custlen )

Compute a domain-separated hash with custom data.

Uses cSHAKE-256 with both a domain label and custom data.

Parameters

output	The output hash buffer
outlen	The output length in bytes
input	[const] The input data
inplen	The input length in bytes
name	[const] The domain separation label string
custlen	The name data length
custom	[const] The custom data
custlen	The custom data length

◆ udif_kdf_object_digest()

UDIF_EXPORT_API void udif_kdf_object_digest	(	uint8_t *	digest,
		const udif_object *	obj )

Compute object digest.

Computes a canonical digest of an object for signing or verification.

Parameters

digest	The output digest (32 bytes)
obj	[const] The object structure

Returns: Returns true if the function succeeded

◆ udif_kdf_ratchet()

UDIF_EXPORT_API void udif_kdf_ratchet	(	uint8_t *	txkey,
		uint8_t *	txnonce,
		uint8_t *	rxkey,
		uint8_t *	rxnonce,
		uint8_t *	newstate,
		const uint8_t *	prevstate,
		const uint8_t *	kemsecret,
		size_t	kemseclen,
		const uint8_t *	sessionid,
		size_t	sessidlen,
		uint64_t	epoch,
		bool	initiator )

Derive ratchet keys from KEM exchange.

Derives new TX and RX keys for an asymmetric ratchet operation. Provides forward secrecy and post-compromise security.

Parameters

txkey	The new transmit encryption key output
txnonce	The new transmit nonce output
rxkey	The new receive encryption key output
rxnonce	The new receive nonce output
newstate	The new ratchet state output (32 bytes)
prevstate	[const] The previous ratchet state (32 bytes)
kemsecret	[const] The KEM shared secret
kemseclen	The KEM secret length
sessionid	[const] The session identifier
sessionidlen	The session ID length
epoch	The new epoch number
initiator	True if initiator, false if responder

◆ udif_kdf_session_id()

UDIF_EXPORT_API void udif_kdf_session_id	(	uint8_t *	sessionid,
		const uint8_t *	localser,
		const uint8_t *	remoteser,
		const uint8_t *	ikm,
		size_t	ikmlen )

Compute session identifier.

Derives a unique session ID from the entity serials and initial keying material.

Parameters

sessionid	The output session ID (32 bytes)
localser	[const] The local entity serial (16 bytes)
remoteser	[const] The remote entity serial (16 bytes)
ikm	[const] Input keying material
ikmlen	The IKM length

◆ udif_kdf_session_keys()

UDIF_EXPORT_API void udif_kdf_session_keys	(	uint8_t *	txkey,
		uint8_t *	txnonce,
		uint8_t *	rxkey,
		uint8_t *	rxnonce,
		uint8_t *	state,
		const uint8_t *	ikm,
		size_t	ikmlen,
		const uint8_t *	transcript,
		size_t	transcriptlen,
		bool	initiator )

Derive session keys from handshake material.

Derives TX and RX keys and nonces for symmetric encryption from the key exchange material and handshake transcript.

Parameters

txkey	The transmit encryption key output
txnonce	The transmit nonce output
rxkey	The receive encryption key output
rxnonce	The receive nonce output
state	The session state output (32 bytes)
ikm	[const] Input keying material (shared secrets)
ikmlen	The IKM length
transcript	[const] The handshake transcript
transcriptlen	The transcript length
initiator	True if initiator, false if responder

◆ udif_kdf_transfer_digest()

UDIF_EXPORT_API void udif_kdf_transfer_digest	(	uint8_t *	digest,
		const uint8_t *	objserial,
		const uint8_t *	txid,
		const uint8_t *	toowner,
		uint64_t	timestamp )

Compute transfer transaction digest.

Computes the digest for a bi-modal object transfer.

Parameters

digest	The output digest (32 bytes)
objserial	[const] The object serial (32 bytes)
txid	[const] The sender serial (16 bytes)
toowner	[const] The receiver serial (16 bytes)
timestamp	The transfer timestamp