crypto.h File Reference

MPDC Cryptographic Functions. More...

#include "common.h"
#include "mpdc.h"

Go to the source code of this file.

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

Functions
MPDC_EXPORT_API bool	mpdc_crypto_decrypt_stream (uint8_t *output, const uint8_t *seed, const uint8_t *input, size_t length)
	Decrypt a stream of bytes.
MPDC_EXPORT_API void	mpdc_crypto_encrypt_stream (uint8_t *output, const uint8_t *seed, const uint8_t *input, size_t length)
	Encrypt a stream of bytes.
MPDC_EXPORT_API void	mpdc_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.
MPDC_EXPORT_API void	mpdc_crypto_generate_application_salt (uint8_t *output, size_t outlen)
	Generate a user-unique application salt from OS sources.
MPDC_EXPORT_API void	mpdc_crypto_generate_hash_code (char *output, const char *message, size_t msglen)
	Hash a message and write the resulting hash to an output array.
MPDC_EXPORT_API void	mpdc_crypto_generate_mac_code (char *output, size_t outlen, const char *message, size_t msglen, const char *key, size_t keylen)
	Compute a MAC (Message Authentication Code) for a message.
MPDC_EXPORT_API void	mpdc_crypto_hash_password (char *output, size_t outlen, const char *username, size_t userlen, const char *password, size_t passlen)
	Hash a password and user name.
MPDC_EXPORT_API bool	mpdc_crypto_password_minimum_check (const char *password, size_t passlen)
	Check a password for a minimum secure threshold.
MPDC_EXPORT_API bool	mpdc_crypto_password_verify (const char *username, size_t userlen, const char *password, size_t passlen, const char *hash, size_t hashlen)
	Verify a password against a stored hash.
MPDC_EXPORT_API uint8_t *	mpdc_crypto_secure_memory_allocate (size_t length)
	Allocate a block of secure memory.
MPDC_EXPORT_API void	mpdc_crypto_secure_memory_deallocate (uint8_t *block, size_t length)
	Release an allocated block of secure memory.

Detailed Description

MPDC Cryptographic Functions.

This header defines the cryptographic functions used by the Multi-Party Domain Cryptosystem (MPDC). 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:

• MPDC_CRYPTO_PHASH_CPU_COST sets the CPU cost in iterations.
• MPDC_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 MPDC protocol.

Test

The MPDC 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 MPDC is robust and reliable.

Function Documentation

mpdc_crypto_decrypt_stream()

MPDC_EXPORT_API bool mpdc_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: MPDC_CRYPTO_SEED_SIZE).
input	[in, const] The cipher-text input.
length	The number of bytes to decrypt.

Returns

Returns true on success.

mpdc_crypto_encrypt_stream()

MPDC_EXPORT_API void mpdc_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: MPDC_CRYPTO_SEED_SIZE).
input	[in, const] The plain-text input.
length	The number of bytes to encrypt.

mpdc_crypto_generate_application_keychain()

MPDC_EXPORT_API void mpdc_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.

mpdc_crypto_generate_application_salt()

MPDC_EXPORT_API void mpdc_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.

mpdc_crypto_generate_hash_code()

MPDC_EXPORT_API void mpdc_crypto_generate_hash_code	(	char *	output,
		const char *	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.

mpdc_crypto_generate_mac_code()

MPDC_EXPORT_API void mpdc_crypto_generate_mac_code	(	char *	output,
		size_t	outlen,
		const char *	message,
		size_t	msglen,
		const char *	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.

mpdc_crypto_hash_password()

MPDC_EXPORT_API void mpdc_crypto_hash_password	(	char *	output,
		size_t	outlen,
		const char *	username,
		size_t	userlen,
		const char *	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.

mpdc_crypto_password_minimum_check()

MPDC_EXPORT_API bool mpdc_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.

mpdc_crypto_password_verify()

MPDC_EXPORT_API bool mpdc_crypto_password_verify	(	const char *	username,
		size_t	userlen,
		const char *	password,
		size_t	passlen,
		const char *	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.

mpdc_crypto_secure_memory_allocate()

MPDC_EXPORT_API uint8_t * mpdc_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.

mpdc_crypto_secure_memory_deallocate()

MPDC_EXPORT_API void mpdc_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.