crypto.h File Reference

Go to the source code of this file.

Data Structures
struct	crypto_context_t
	Endpoint cryptographic state for handshake, packet protection, authentication, and rekeying. More...

Macros
#define	SSH_KEY_TYPE_LENGTH_SIZE   4
#define	SSH_KEY_TYPE_STRING_SIZE   11
#define	SSH_KEY_PUBLIC_KEY_LENGTH_SIZE   4
#define	SSH_KEY_PUBLIC_KEY_SIZE   32
#define	SSH_KEY_HEADER_SIZE    (SSH_KEY_TYPE_LENGTH_SIZE + SSH_KEY_TYPE_STRING_SIZE + SSH_KEY_PUBLIC_KEY_LENGTH_SIZE + SSH_KEY_PUBLIC_KEY_SIZE)
#define	CRYPTO_KEY_SIZE   32
	Ed25519 key size in bytes.
#define	CRYPTO_FINGERPRINT_SIZE   32
	Ed25519 key fingerprint size in bytes.
#define	SSH_KEY_PERMISSIONS_MASK   (S_IRWXG | S_IRWXO)
#define	SSH_KEY_RECOMMENDED_PERMISSIONS   0600
Encryption Size Limits
#define	CRYPTO_MAX_PLAINTEXT_SIZE   ((size_t)1024 * 1024)
	Maximum plaintext size (1MB).
#define	CRYPTO_MAX_CIPHERTEXT_SIZE   (CRYPTO_MAX_PLAINTEXT_SIZE + CRYPTO_MAC_SIZE)
	Maximum ciphertext size (plaintext + MAC, ~1MB + 16 bytes).
Hex String Size Constants
#define	CRYPTO_HEX_KEY_SIZE   64
	Hex string size for 32-byte key (64 hex characters).
#define	CRYPTO_HEX_KEY_SIZE_NULL   65
	Hex string size for 32-byte key with null terminator (65 bytes).
#define	CRYPTO_HEX_KEY64_SIZE   128
	Hex string size for 64-byte key (128 hex characters).
#define	CRYPTO_HEX_KEY64_SIZE_NULL   129
	Hex string size for 64-byte key with null terminator (129 bytes).
Cryptographic String Literals
#define	SSH_ED25519_KEY_TYPE   "ssh-ed25519"
	SSH Ed25519 key type string ("ssh-ed25519").
#define	X25519_KEY_TYPE   "x25519"
	X25519 key type string ("x25519").
#define	NO_IDENTITY_MARKER   "no-identity"
	No-identity entry marker ("no-identity").

Typedefs
typedef struct crypto_context_t	crypto_context_t
	Endpoint cryptographic state for handshake, packet protection, authentication, and rekeying.

Enumerations
enum	crypto_result_t {   CRYPTO_OK = 0 , CRYPTO_ERROR_INIT_FAILED = -1 , CRYPTO_ERROR_INVALID_PARAMS = -2 , CRYPTO_ERROR_MEMORY = -3 ,   CRYPTO_ERROR_LIBSODIUM = -4 , CRYPTO_ERROR_KEY_GENERATION = -5 , CRYPTO_ERROR_PASSWORD_DERIVATION = -6 , CRYPTO_ERROR_ENCRYPTION = -7 ,   CRYPTO_ERROR_DECRYPTION = -8 , CRYPTO_ERROR_INVALID_MAC = -9 , CRYPTO_ERROR_BUFFER_TOO_SMALL = -10 , CRYPTO_ERROR_KEY_EXCHANGE_INCOMPLETE = -11 ,   CRYPTO_ERROR_NONCE_EXHAUSTED = -12 , CRYPTO_ERROR_REKEY_IN_PROGRESS = -13 , CRYPTO_ERROR_REKEY_FAILED = -14 , CRYPTO_ERROR_REKEY_RATE_LIMITED = -15 }
	Cryptographic operation result codes. More...

Functions
Core Initialization and Setup
crypto_result_t	crypto_init (crypto_context_t *ctx)
	Initialize libsodium and crypto context.
crypto_result_t	crypto_init_with_password (crypto_context_t *ctx, const char *password)
	Initialize with password-based encryption.
void	crypto_destroy (crypto_context_t *ctx)
	Cleanup crypto context with secure memory wiping.
crypto_result_t	crypto_generate_keypair (crypto_context_t *ctx)
	Generate new X25519 key pair for key exchange.
Key Exchange Protocol
Automatic HTTPS-like key exchange using X25519 Diffie-Hellman. Both parties exchange ephemeral public keys and compute a shared secret.
crypto_result_t	crypto_get_public_key (const crypto_context_t *ctx, uint8_t *public_key_out)
	Get public key for sending to peer (step 1 of handshake).
crypto_result_t	crypto_set_peer_public_key (crypto_context_t *ctx, const uint8_t *peer_public_key)
	Set peer's public key and compute shared secret (step 2 of handshake).
bool	crypto_is_ready (const crypto_context_t *ctx)
	Check if key exchange is complete and ready for encryption.
Password-Based Encryption
Optional additional encryption layer using password-derived keys. Uses Argon2id for memory-hard key derivation, providing resistance to offline brute-force attacks.
crypto_result_t	crypto_validate_password (const char *password)
	Validate password length requirements.
crypto_result_t	crypto_derive_password_key (crypto_context_t *ctx, const char *password)
	Derive key from password using Argon2id.
bool	crypto_verify_password (const crypto_context_t *ctx, const char *password)
	Verify password matches stored salt/key.
crypto_result_t	crypto_derive_password_encryption_key (const char *password, uint8_t encryption_key[32])
	Derive deterministic encryption key from password for handshake.
Encryption/Decryption Operations
Encrypt/decrypt data using XSalsa20-Poly1305 (via libsodium secretbox). Automatically handles nonce generation and MAC verification.
crypto_result_t	crypto_encrypt (crypto_context_t *ctx, const uint8_t *plaintext, size_t plaintext_len, uint8_t *ciphertext_out, size_t ciphertext_out_size, size_t *ciphertext_len_out)
	Encrypt data using XSalsa20-Poly1305.
crypto_result_t	crypto_decrypt (crypto_context_t *ctx, const uint8_t *ciphertext, size_t ciphertext_len, uint8_t *plaintext_out, size_t plaintext_out_size, size_t *plaintext_len_out)
	Decrypt data using XSalsa20-Poly1305.
Utility Functions
const char *	crypto_result_to_string (crypto_result_t result)
	Convert crypto result to human-readable string.
void	crypto_get_status (const crypto_context_t *ctx, char *status_buffer, size_t buffer_size)
	Get crypto context status information for debugging.
bool	crypto_secure_compare (const uint8_t *lhs, const uint8_t *rhs, size_t len)
	Secure constant-time comparison of byte arrays.
crypto_result_t	crypto_random_bytes (uint8_t *buffer, size_t len)
	Generate cryptographically secure random bytes.
Authentication and Handshake
HMAC-based authentication using HMAC-SHA256. Used for password authentication and challenge-response protocols.
crypto_result_t	crypto_generate_nonce (uint8_t nonce[32])
	Generate random nonce for authentication.
crypto_result_t	crypto_compute_hmac (crypto_context_t *ctx, const uint8_t key[32], const uint8_t data[32], uint8_t hmac[32])
	Compute HMAC-SHA256 for fixed 32-byte data.
crypto_result_t	crypto_compute_hmac_ex (const crypto_context_t *ctx, const uint8_t key[32], const uint8_t *data, size_t data_len, uint8_t hmac[32])
	Compute HMAC-SHA256 for variable-length data.
bool	crypto_verify_hmac (const uint8_t key[32], const uint8_t data[32], const uint8_t expected_hmac[32])
	Verify HMAC-SHA256 for fixed 32-byte data.
bool	crypto_verify_hmac_ex (const uint8_t key[32], const uint8_t *data, size_t data_len, const uint8_t expected_hmac[32])
	Verify HMAC-SHA256 for variable-length data.
High-Level Authentication Helpers
Authentication helpers that bind password/key authentication to the DH key exchange, preventing man-in-the-middle attacks.
crypto_result_t	crypto_compute_auth_response (const crypto_context_t *ctx, const uint8_t nonce[32], uint8_t hmac_out[32])
	Compute authentication response HMAC bound to DH shared_secret.
bool	crypto_verify_auth_response (const crypto_context_t *ctx, const uint8_t nonce[32], const uint8_t expected_hmac[32])
	Verify authentication response HMAC bound to DH shared_secret.
crypto_result_t	crypto_create_auth_challenge (const crypto_context_t *ctx, uint8_t *packet_out, size_t packet_size, size_t *packet_len_out)
	Create authentication challenge packet.
crypto_result_t	crypto_process_auth_challenge (crypto_context_t *ctx, const uint8_t *packet, size_t packet_len)
	Process authentication challenge packet.
crypto_result_t	crypto_process_auth_response (crypto_context_t *ctx, const uint8_t *packet, size_t packet_len)
	Process authentication response packet.
Network Integration Helpers
Packet creation and processing functions for network transmission. Handles packet formatting, encryption, and decryption automatically.
crypto_result_t	crypto_create_public_key_packet (const crypto_context_t *ctx, uint8_t *packet_out, size_t packet_size, size_t *packet_len_out)
	Create public key packet for network transmission.
crypto_result_t	crypto_process_public_key_packet (crypto_context_t *ctx, const uint8_t *packet, size_t packet_len)
	Process received public key packet from peer.
crypto_result_t	crypto_create_encrypted_packet (crypto_context_t *ctx, const uint8_t *data, size_t data_len, uint8_t *packet_out, size_t packet_size, size_t *packet_len_out)
	Create encrypted data packet for network transmission.
crypto_result_t	crypto_process_encrypted_packet (crypto_context_t *ctx, const uint8_t *packet, size_t packet_len, uint8_t *data_out, size_t data_size, size_t *data_len_out)
	Process received encrypted packet from peer.
Shared Cryptographic Operations
Low-level cryptographic operations used by both client and server for authentication and key exchange.
asciichat_error_t	crypto_compute_password_hmac (crypto_context_t *ctx, const uint8_t *password_key, const uint8_t *nonce, const uint8_t *shared_secret, uint8_t *hmac_out)
	Compute password-based HMAC for authentication.
asciichat_error_t	crypto_verify_peer_signature (const uint8_t *peer_public_key, const uint8_t *ephemeral_key, size_t ephemeral_key_size, const uint8_t *signature)
	Verify peer's signature on ephemeral key.
asciichat_error_t	crypto_sign_ephemeral_key (const private_key_t *private_key, const uint8_t *ephemeral_key, size_t ephemeral_key_size, uint8_t *signature_out)
	Sign ephemeral key with private key.
void	crypto_combine_auth_data (const uint8_t *hmac, const uint8_t *challenge_nonce, uint8_t *combined_out)
	Combine HMAC and challenge nonce for transmission.
void	crypto_extract_auth_data (const uint8_t *combined_data, uint8_t *hmac_out, uint8_t *challenge_out)
	Extract HMAC and challenge nonce from combined data.

Session Rekeying Protocol
Periodic key rotation to limit exposure if keys are compromised. Rekeys after time threshold (default: 1 hour) OR packet count threshold (default: 1 million), whichever comes first. Note Test environment detection: If CRITERION_TEST or TESTING environment variable is set, rekey thresholds are reduced to 30 seconds / 1000 packets for faster testing. Rekeying flow: Initiator calls crypto_rekey_init() and sends REKEY_REQUEST Responder processes request, calls crypto_rekey_process_request(), sends REKEY_RESPONSE Initiator processes response, calls crypto_rekey_process_response(), sends REKEY_COMPLETE Responder verifies REKEY_COMPLETE decrypts with new key, calls crypto_rekey_commit() Initiator calls crypto_rekey_commit() after receiving confirmation Old keys remain active until REKEY_COMPLETE is verified, ensuring no service interruption.
#define	REKEY_MIN_INTERVAL   (3LL * NS_PER_SEC_INT)
	Minimum time interval between rekey requests (3 seconds in nanoseconds for testing, 60 for production).
#define	REKEY_DEFAULT_TIME_THRESHOLD   (3600LL * NS_PER_SEC_INT)
	Default rekey time threshold (1 hour in nanoseconds).
#define	REKEY_DEFAULT_PACKET_THRESHOLD   1000000
	Default rekey packet threshold (1 million packets).
#define	REKEY_TEST_TIME_THRESHOLD   (30LL * NS_PER_SEC_INT)
	Test mode rekey time threshold (30 seconds in nanoseconds).
#define	REKEY_TEST_PACKET_THRESHOLD   1000
	Test mode rekey packet threshold (1000 packets).
#define	REKEY_MAX_FAILURE_COUNT   10
	Maximum consecutive rekey failures before giving up.
#define	REKEY_MIN_REQUEST_INTERVAL   (60LL * NS_PER_SEC_INT)
	Minimum interval between rekey requests (60 seconds in nanoseconds, DDoS protection).
bool	crypto_should_rekey (const crypto_context_t *ctx)
	Check if rekeying should be triggered based on time or packet count thresholds.
crypto_result_t	crypto_rekey_init (crypto_context_t *ctx)
	Initiate rekeying by generating new ephemeral keys.
crypto_result_t	crypto_rekey_process_request (crypto_context_t *ctx, const uint8_t *peer_new_public_key)
	Process REKEY_REQUEST from peer (responder side).
crypto_result_t	crypto_rekey_process_response (crypto_context_t *ctx, const uint8_t *peer_new_public_key)
	Process REKEY_RESPONSE from peer (initiator side).
crypto_result_t	crypto_rekey_commit (crypto_context_t *ctx)
	Commit to new keys after successful REKEY_COMPLETE.
void	crypto_rekey_abort (crypto_context_t *ctx)
	Abort rekeying and fallback to old keys.
void	crypto_get_rekey_status (const crypto_context_t *ctx, char *status_buffer, size_t buffer_size)
	Get the current rekeying state for debugging/logging.