crypto.h File Reference

UDIF Cryptographic Functions. More...

#include "udifcommon.h"
#include "udif.h"

Go to the source code of this file.

Macros
#define	UDIF_CRYPTO_PHASH_CPU_COST   4U
	The passphrase hash CPU cost in iterations (acceptable range: 1-100000).
#define	UDIF_CRYPTO_PHASH_MEMORY_COST   1U
	The passphrase hash memory cost in MB (acceptable range: 1-4096).

Functions
UDIF_EXPORT_API bool	udif_crypto_decrypt_stream (uint8_t *output, const uint8_t *seed, const uint8_t *input, size_t length)
	Decrypt a stream of bytes.
UDIF_EXPORT_API void	udif_crypto_encrypt_stream (uint8_t *output, const uint8_t *seed, const uint8_t *input, size_t length)
	Encrypt a stream of bytes.
UDIF_EXPORT_API void	udif_crypto_generate_application_keychain (uint8_t *seed, size_t seedlen, const char *password, size_t passlen, const char *username, size_t userlen)
	Generate a secure application key chain.
UDIF_EXPORT_API void	udif_crypto_generate_application_salt (uint8_t *output, size_t outlen)
	Generate a user-unique application salt from OS sources.
UDIF_EXPORT_API void	udif_crypto_generate_hash_code (uint8_t *output, const uint8_t *message, size_t msglen)
	Hash a message and write the resulting hash to an output array.
UDIF_EXPORT_API void	udif_crypto_generate_mac_code (uint8_t *output, size_t outlen, const uint8_t *message, size_t msglen, const uint8_t *key, size_t keylen)
	Compute a MAC (Message Authentication Code) for a message.
UDIF_EXPORT_API void	udif_crypto_hash_password (uint8_t *output, size_t outlen, const uint8_t *username, size_t userlen, const uint8_t *password, size_t passlen)
	Hash a password and user name.
UDIF_EXPORT_API bool	udif_crypto_password_minimum_check (const char *password, size_t passlen)
	Check a password for a minimum secure threshold.
UDIF_EXPORT_API bool	udif_crypto_password_verify (const uint8_t *username, size_t userlen, const uint8_t *password, size_t passlen, const uint8_t *hash, size_t hashlen)
	Verify a password against a stored hash.
UDIF_EXPORT_API uint8_t *	udif_crypto_secure_memory_allocate (size_t length)
	Allocate a block of secure memory.
UDIF_EXPORT_API void	udif_crypto_secure_memory_deallocate (uint8_t *block, size_t length)
	Release an allocated block of secure memory.

Detailed Description

UDIF Cryptographic Functions.

This header defines the cryptographic functions used by the Anonymous Encrypted Relay Network (UDIF). The crypto module encapsulates all operations required for secure data processing including:

• Stream encryption and decryption using a symmetric cipher based on the RCS (Randomized Cipher Stream) algorithm.
• Generation of secure key chains by combining a user's password and username with a unique application salt.
• Generation of message hashes and message authentication codes (MACs) using SHA3-256 and KMAC256.
• Password handling including a minimum quality check, secure password hashing, and verification.
• Secure memory management functions to allocate and deallocate memory that is immediately cleared to protect sensitive data.

Two configuration macros are provided to tune the passphrase hashing function:

• UDIF_CRYPTO_PHASH_CPU_COST sets the CPU cost in iterations.
• UDIF_CRYPTO_PHASH_MEMORY_COST sets the memory cost in megabytes.

Note

These cryptographic operations build upon underlying primitives provided by the QSC library (e.g. SHA3, cSHAKE, KMAC, and RCS). Correct operation of these functions is critical to the security of the UDIF protocol.

Test

The UDIF crypto functions are rigorously tested to ensure that:

• Data streams are properly encrypted and decrypted.
• The application key chain is securely generated from a user's password and username, using a salt derived from OS sources.
• Message hashes and MAC codes are computed accurately.
• Passwords are validated against a set minimum complexity and correctly verified against stored hashes.
• Secure memory is allocated and deallocated without leaving residual data.

These tests help ensure that the cryptographic foundation of UDIF is robust and reliable.

Function Documentation

udif_crypto_decrypt_stream()

UDIF_EXPORT_API bool udif_crypto_decrypt_stream	(	uint8_t *	output,
		const uint8_t *	seed,
		const uint8_t *	input,
		size_t	length )

Decrypt a stream of bytes.

Parameters

output	[out] The output array receiving the plain-text.
seed	[in, const] The secret seed array used as the decryption key (expected size: UDIF_CRYPTO_SEED_SIZE).
input	[in, const] The cipher-text input.
length	The number of bytes to decrypt.

Returns

Returns true on success.

udif_crypto_encrypt_stream()

UDIF_EXPORT_API void udif_crypto_encrypt_stream	(	uint8_t *	output,
		const uint8_t *	seed,
		const uint8_t *	input,
		size_t	length )

Encrypt a stream of bytes.

Parameters

output	[out] The output array receiving the cipher-text.
seed	[in, const] The secret seed array used as the encryption key (expected size: UDIF_CRYPTO_SEED_SIZE).
input	[in, const] The plain-text input.
length	The number of bytes to encrypt.

udif_crypto_generate_application_keychain()

UDIF_EXPORT_API void udif_crypto_generate_application_keychain	(	uint8_t *	seed,
		size_t	seedlen,
		const char *	password,
		size_t	passlen,
		const char *	username,
		size_t	userlen )

Generate a secure application key chain.

Derives a secure key chain (seed) from the provided password and username combined with an application salt generated from OS-specific sources.

Parameters

seed	[out] The output secret seed array.
seedlen	The length of the seed array.
password	[in, const] The password.
passlen	The byte length of the password.
username	[in, const] The computer's user name.
userlen	The byte length of the user name.

udif_crypto_generate_application_salt()

UDIF_EXPORT_API void udif_crypto_generate_application_salt	(	uint8_t *	output,
		size_t	outlen )

Generate a user-unique application salt from OS sources.

The salt is generated by collecting system parameters such as the computer name, user name, and MAC address, and then hashing these values using SHAKE256.

Parameters

output	[out] The secret seed array to receive the salt.
outlen	The length of the salt array.

udif_crypto_generate_hash_code()

UDIF_EXPORT_API void udif_crypto_generate_hash_code	(	uint8_t *	output,
		const uint8_t *	message,
		size_t	msglen )

Hash a message and write the resulting hash to an output array.

Computes the SHA3-256 hash of the specified message.

Parameters

output	[out] The output array receiving the hash.
message	[in, const] A pointer to the message array.
msglen	The length of the message.

udif_crypto_generate_mac_code()

UDIF_EXPORT_API void udif_crypto_generate_mac_code	(	uint8_t *	output,
		size_t	outlen,
		const uint8_t *	message,
		size_t	msglen,
		const uint8_t *	key,
		size_t	keylen )

Compute a MAC (Message Authentication Code) for a message.

Uses KMAC256 to compute a MAC from the provided message and key.

Parameters

output	[out] The output array receiving the MAC.
outlen	The byte length of the output array.
message	[in, const] A pointer to the message array.
msglen	The length of the message.
key	[in, const] A pointer to the key array.
keylen	The length of the key array.

udif_crypto_hash_password()

UDIF_EXPORT_API void udif_crypto_hash_password	(	uint8_t *	output,
		size_t	outlen,
		const uint8_t *	username,
		size_t	userlen,
		const uint8_t *	password,
		size_t	passlen )

Hash a password and user name.

Combines the username and password with an application salt to compute a secure hash via KMAC256.

Parameters

output	[out] The output array receiving the hash.
outlen	The length of the output array.
username	[in, const] The computer's user name.
userlen	The byte length of the user name.
password	[in, const] The password.
passlen	The length of the password.

udif_crypto_password_minimum_check()

UDIF_EXPORT_API bool udif_crypto_password_minimum_check	(	const char *	password,
		size_t	passlen )

Check a password for a minimum secure threshold.

Evaluates the password for minimum requirements (such as inclusion of uppercase, lowercase, numeric, and special characters, and a minimum length).

Parameters

password	[in, const] The password array.
passlen	The byte length of the password.

Returns

Returns true if the password meets the minimum requirements.

udif_crypto_password_verify()

UDIF_EXPORT_API bool udif_crypto_password_verify	(	const uint8_t *	username,
		size_t	userlen,
		const uint8_t *	password,
		size_t	passlen,
		const uint8_t *	hash,
		size_t	hashlen )

Verify a password against a stored hash.

Computes the hash of the username and password and compares it with a stored hash.

Parameters

username	[in, const] The computer's user name.
userlen	The byte length of the user name.
password	[in, const] The password.
passlen	The byte length of the password.
hash	The stored hash to compare.
hashlen	The length of the stored hash.

Returns

Returns true if the computed hash matches the stored value.

udif_crypto_secure_memory_allocate()

UDIF_EXPORT_API uint8_t * udif_crypto_secure_memory_allocate

(

size_t

length

)

Allocate a block of secure memory.

Allocates memory using secure allocation routines to prevent sensitive data from being paged or left in memory.

Parameters

length

The number of bytes to allocate.

Returns

Returns a pointer to the allocated secure memory, or NULL on failure.

udif_crypto_secure_memory_deallocate()

UDIF_EXPORT_API void udif_crypto_secure_memory_deallocate	(	uint8_t *	block,
		size_t	length )

Release an allocated block of secure memory.

Securely erases the memory block and then frees it.

Parameters

block	The pointer to the memory block.
length	The length of the memory block.