Crypto Module

🔐 Core cryptographic operations for ascii-chat More...

Files
file	crypto.c
	🔐 Core cryptography: encryption/decryption, key exchange, authentication, and session rekeying with BearSSL
file	discovery_keys.c
	Discovery Server Public Key Trust Management Implementation.
file	agent.c
	GPG agent connection and communication implementation.
file	export.c
	GPG public key export implementation.
file	homedir.c
	Temporary GPG homedir management implementation.
file	openpgp.c
	OpenPGP (RFC 4880) packet format parser implementation.
file	signing.c
	GPG signing operations implementation.
file	verification.c
	GPG signature verification implementation.
file	known_hosts.c
	📜 SSH known_hosts file parser for host key verification and trust management
file	pem.c
	📄 PEM format encoding/decoding utilities for certificates and keys (adapted from BearSSL)
file	regex.c
	PCRE2-based regex patterns for cryptographic parsing.
file	discovery_keys.h
	Discovery Server Public Key Trust Management.
file	agent.h
	GPG agent connection and communication interface.
file	export.h
	GPG public key export interface.
file	gpg.h
	GPG operations - main header.
file	homedir.h
	Temporary GPG homedir management for isolated key operations.
file	openpgp.h
	OpenPGP (RFC 4880) packet format parser.
file	signing.h
	GPG message signing interface.
file	verification.h
	GPG signature verification interface.
file	known_hosts.h
	Known hosts management for MITM attack prevention.
file	pem.h
	BearSSL PEM and trust anchor utilities adapted for in-memory data.
file	regex.h
	PCRE2-based regex patterns for cryptographic parsing.

Data Structures
struct	crypto_context_t
	Endpoint cryptographic state for handshake, packet protection, authentication, and rekeying. More...
struct	openpgp_packet_header_t
	The framing fields needed to locate and classify one OpenPGP packet body. More...
struct	openpgp_public_key_t
	The parsed identity portion of an OpenPGP public-key packet. More...
struct	openpgp_secret_key_t
	The parsed public and private material from an OpenPGP secret-key packet. More...
struct	anchor_list
	Vector type for trust anchors. 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

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...

Variables
br_x509_trust_anchor *	anchor_list::buf
size_t	anchor_list::ptr
size_t	anchor_list::len

Known Hosts Management
const char *	get_known_hosts_path (void)
	Get the path to the known_hosts file.
asciichat_error_t	add_known_host (const char *server_ip, uint16_t port, const uint8_t server_key[32])
	Add server to known_hosts.
asciichat_error_t	remove_known_host (const char *server_ip, uint16_t port)
	Remove server from known_hosts.

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.
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.
#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).

GPG Agent Connection Management
int	gpg_agent_connect (void)
	Connect to gpg-agent.
void	gpg_agent_disconnect (int sock)
	Disconnect from gpg-agent.
bool	gpg_agent_is_available (void)
	Check if GPG agent is available.

GPG Agent Signing Operations
int	gpg_agent_sign (int sock, const char *keygrip, const uint8_t *message, size_t message_len, uint8_t *signature_out, size_t *signature_len_out)
	Sign a message using GPG agent.

GPG Key Export
int	gpg_get_public_key (const char *key_id, uint8_t *public_key_out, char *keygrip_out)
	Get public key from GPG keyring by key ID.

PGP Armored Format Parsing
asciichat_error_t	openpgp_parse_armored_pubkey (const char *armored_text, uint8_t ed25519_pk[32])
	Parse PGP armored key block and extract Ed25519 public key.
asciichat_error_t	openpgp_parse_binary_pubkey (const uint8_t *data, size_t data_len, uint8_t ed25519_pk[32])
asciichat_error_t	openpgp_parse_armored_seckey (const char *armored_text, uint8_t ed25519_pk[32], uint8_t ed25519_sk[32])
	Parse PGP armored secret key block and extract Ed25519 keypair.
asciichat_error_t	openpgp_parse_binary_seckey (const uint8_t *data, size_t data_len, uint8_t ed25519_pk[32], uint8_t ed25519_sk[32])

OpenPGP Packet Parsing
asciichat_error_t	openpgp_parse_packet_header (const uint8_t *data, size_t data_len, openpgp_packet_header_t *header)
	Parse OpenPGP packet header.
asciichat_error_t	openpgp_parse_public_key_packet (const uint8_t *packet_body, size_t body_len, openpgp_public_key_t *pubkey)
	Parse OpenPGP Public Key Packet (tag 6).
asciichat_error_t	openpgp_parse_secret_key_packet (const uint8_t *packet_body, size_t body_len, openpgp_secret_key_t *seckey)
	Parse OpenPGP Secret Key Packet (tag 5).
asciichat_error_t	openpgp_extract_ed25519_from_mpi (const uint8_t *mpi, size_t mpi_len, uint8_t ed25519_pk[32])
	Extract Ed25519 public key from MPI-encoded data.

Base64 Decoding for PGP Armor
asciichat_error_t	openpgp_base64_decode (const char *base64, size_t base64_len, uint8_t **binary_out, size_t *binary_len)
	Decode PGP armored base64 data.

GPG Signing Operations
int	gpg_sign_with_key (const char *key_id, const uint8_t *message, size_t message_len, uint8_t *signature_out, size_t *signature_len_out)
	Sign a message using GPG key and return OpenPGP signature.
int	gpg_sign_detached_ed25519 (const char *key_id, const uint8_t *message, size_t message_len, uint8_t signature_out[ED25519_SIGNATURE_SIZE])
	Sign message with GPG and extract raw Ed25519 signature.

GPG Signature Verification
int	gpg_verify_detached_ed25519 (const char *key_id, const uint8_t *message, size_t message_len, const uint8_t signature[ED25519_SIGNATURE_SIZE])
	Verify Ed25519 signature using GPG binary.
int	gpg_verify_signature (const uint8_t *public_key, const uint8_t *message, size_t message_len, const uint8_t *signature)
	Verify Ed25519 signature using libgcrypt (no GPG binary required).
int	gpg_verify_signature_with_binary (const uint8_t *signature, size_t signature_len, const uint8_t *message, size_t message_len, const char *expected_key_id)
	Verify OpenPGP signature using GPG binary.

Known Hosts Verification
asciichat_error_t	check_known_host (const char *server_ip, uint16_t port, const uint8_t server_key[32])
	Check if server key is in known_hosts.
asciichat_error_t	check_known_host_with_key (const char *server_ip, uint16_t port, const uint8_t server_key[32], uint8_t expected_key[32], bool *has_expected_key)
asciichat_error_t	check_known_host_no_identity (const char *server_ip, uint16_t port)
	Check known_hosts for servers without identity key (no-identity entries).

User Interaction
bool	display_mitm_warning (const char *server_ip, uint16_t port, const uint8_t expected_key[32], const uint8_t received_key[32])
	Display MITM warning with key comparison and prompt user for confirmation.
bool	prompt_unknown_host (const char *server_ip, uint16_t port, const uint8_t server_key[32])
	Interactive prompt for unknown host - returns true if user wants to add, false to abort.
bool	prompt_unknown_host_no_identity (const char *server_ip, uint16_t port)
	Interactive prompt for unknown host without identity key - returns true if user wants to continue, false to abort.

Key Fingerprinting
void	compute_key_fingerprint (const uint8_t key[32], char fingerprint[(32 *2+1)])
	Compute SHA256 fingerprint of Ed25519 key for display.

Cleanup
void	known_hosts_destroy (void)
	Cleanup function to free cached known_hosts path.

Trust Anchor Management
Vector type for trust anchors
size_t	read_trust_anchors_from_memory (anchor_list *dst, const unsigned char *pem_data, size_t pem_len)
	Read trust anchors from PEM-encoded data in memory.
void	free_ta_contents (br_x509_trust_anchor *ta)
	Free the contents of a trust anchor.
#define	ANCHOR_LIST_INIT   {NULL, 0, 0}
	Initializer for anchor_list.

SSH Agent Detection
bool	ssh_agent_is_available (void)
	Check if ssh-agent is running and available.

SSH Agent Key Management
asciichat_error_t	ssh_agent_add_key (const private_key_t *private_key, const char *key_path)
	Add a private key to ssh-agent.
bool	ssh_agent_has_key (const public_key_t *public_key)
	Check if a public key is already in ssh-agent.
asciichat_error_t	ssh_agent_get_key (const public_key_t *public_key, private_key_t *key_out)
	Retrieve a private key from ssh-agent by matching public key.
asciichat_error_t	ssh_agent_sign (const public_key_t *public_key, const uint8_t *message, size_t message_len, uint8_t signature[64])
	Sign data using SSH agent with the specified public key.

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").

OpenPGP Constants
The framing fields needed to locate and classify one OpenPGP packet body The parsed identity portion of an OpenPGP public-key packet The parsed public and private material from an OpenPGP secret-key packet
#define	OPENPGP_TAG_PUBLIC_KEY   6
	OpenPGP packet tag for Public Key Packet.
#define	OPENPGP_TAG_SECRET_KEY   5
	OpenPGP packet tag for Secret Key Packet.
#define	OPENPGP_TAG_USER_ID   13
	OpenPGP packet tag for User ID Packet.
#define	OPENPGP_TAG_SIGNATURE   2
	OpenPGP packet tag for Signature Packet.
#define	OPENPGP_ALGO_EDDSA   22
	OpenPGP algorithm ID for EdDSA (Ed25519).
#define	OPENPGP_ALGO_ECDH   18
	OpenPGP algorithm ID for ECDH (Curve25519).

Detailed Description

🔐 Core cryptographic operations for ascii-chat

This header provides the core cryptographic operations for secure communication in ascii-chat, including key exchange, encryption/decryption, authentication, and session rekeying.

The interface provides:

• Cryptographic context management
• X25519 key exchange (Diffie-Hellman)
• XSalsa20-Poly1305 encryption/decryption
• Argon2id password-based key derivation
• HMAC-SHA256 authentication
• Session rekeying protocol

Note

Key Exchange: Uses ephemeral X25519 keys for perfect forward secrecy. Each connection generates new keys automatically.

Encryption: XSalsa20-Poly1305 provides authenticated encryption with automatic MAC verification. Nonces are generated as session_id || counter to avoid nonce reuse; this alone does not detect replayed ciphertext.

Password Authentication: Optional password-based encryption using Argon2id for memory-hard key derivation. Passwords are bound to DH shared secrets to prevent MITM attacks.

Rekeying: Automatic periodic key rotation after time threshold (1 hour) OR packet count threshold (1 million), whichever comes first. Test mode uses reduced thresholds (30 seconds / 1000 packets).

Test Environment: Automatically detects test environment via CRITERION_TEST or TESTING environment variables and adjusts thresholds accordingly.

Byte Order: Client must convert network byte order to host byte order for crypto parameters. Server uses host byte order directly.

Key Exchange Formats:

• Simple format: Only ephemeral public key (when server has no identity key)
• Authenticated format: Ephemeral key + identity key + signature (when server has identity key)

Warning

Always use crypto_secure_compare() for comparing sensitive data (keys, MACs, HMACs). Do NOT use regular memcmp() as it is vulnerable to timing attacks.

Nonce counter starts at 1 (0 is reserved for testing). Returns CRYPTO_ERROR_NONCE_EXHAUSTED if counter reaches 0 or UINT64_MAX (extremely unlikely, but triggers rekeying).

Password salt is deterministic ("ascii-chat-password-salt-v1") for consistent key derivation across client/server. Only use for session encryption, not long-term storage.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

October 2025

This header provides GPG agent (gpg-agent) integration for signing operations with GPG keys. Allows private keys to stay in GPG agent without being loaded into application memory.

Note

GPG agent protocol: Implements Assuan protocol for communicating with gpg-agent. Keys stay in agent and are never loaded into application memory.

Platform support:

• Unix: Uses GPG_AGENT_INFO or connects to standard socket (~/.gnupg/S.gpg-agent)
• Windows: Connects to standard named pipe (Gpg4win installs gpg-agent as service)

Key format: Only Ed25519 GPG keys are supported. RSA/ECDSA GPG keys are NOT supported.

Keygrip: GPG uses keygrips (40-char hex strings) to identify keys in the agent. Keygrips are computed from public key material and are stable identifiers.

Agent detection: Checks for agent socket/pipe existence and accessibility. On Unix, verifies socket is accessible. On Windows, checks for named pipe.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

October 2025

This header provides functions for exporting public keys from GPG keyring. Supports retrieving Ed25519 public keys and keygrips for use in authentication and signing operations.

Note

Key export: Uses gpg --export to extract public key from local keyring. Parses OpenPGP packet format to extract Ed25519 public key material.

Keygrip extraction: Optionally extracts keygrip for use with GPG agent. Keygrip is a stable 40-char hex identifier computed from public key.

Key ID formats: Supports short (8-char), long (16-char), and full (40-char) key IDs. Accepts key IDs with or without "0x" prefix.

Ed25519 only: Only Ed25519 GPG keys are supported. RSA/ECDSA keys will cause export to fail.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

October 2025

This header provides the complete GPG interface by including all submodule headers. Users can include this single header to access all GPG functionality.

Submodules:

• agent.h: GPG agent connection and communication
• export.h: Public key export from GPG keyring
• signing.h: Message signing operations
• verification.h: Signature verification operations

Implements parsing of OpenPGP packet format (RFC 4880) for extracting Ed25519 public keys from PGP armored key blocks.

Supported features:

• PGP armored format (--—BEGIN PGP PUBLIC KEY BLOCK--—)
• Base64 decoding of armored data
• OpenPGP packet header parsing (old and new formats)
• Public Key Packet (tag 6) parsing
• Ed25519 (algorithm 22) key extraction

Note

Limitations:

• Only supports Ed25519 keys (algorithm 22)
• Only parses public key packets (tag 6)
• Does not verify signatures or checksums
• Does not support encrypted keys

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

This header provides GPG signing operations for creating detached signatures. Supports both OpenPGP-formatted signatures and raw Ed25519 signatures extracted from GPG output.

Note

Signing method: Uses gpg --detach-sign to create detached signatures. Signatures are separate from message data (not inline signatures).

Key requirements: Only Ed25519 GPG keys are supported. RSA/ECDSA keys will cause signing operations to fail.

Output formats:

• gpg_sign_with_key(): Returns full OpenPGP signature packet (variable length)
• gpg_sign_detached_ed25519(): Extracts raw 64-byte Ed25519 signature (R||S)

GPG binary: Requires gpg binary in PATH for all operations. Returns error if GPG is not installed or not accessible.

Key passphrase: If key is encrypted, GPG may prompt for passphrase. Use ssh-agent or gpg-agent for password-free signing, or set $ASCII_CHAT_KEY_PASSWORD environment variable.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

October 2025

This header provides GPG signature verification operations supporting both GPG binary-based verification and direct cryptographic verification via libgcrypt. Handles both raw Ed25519 signatures and OpenPGP-formatted signatures.

Note

Verification methods:

• GPG binary: Uses gpg --verify for full OpenPGP packet verification
• libgcrypt: Direct Ed25519 signature verification without GPG binary

Key requirements: Only Ed25519 signatures are supported. RSA/ECDSA signatures will cause verification to fail.

Signature formats:

• Raw Ed25519: 64-byte signature (R||S format) from gpg_sign_detached_ed25519()
• OpenPGP: Variable-length signature packet from gpg_sign_with_key()

GPG binary dependency: Functions using GPG binary require gpg in PATH. libgcrypt-based verification works without GPG binary installed.

Key trust: GPG binary verification checks key trust and validity. libgcrypt verification only checks cryptographic signature validity.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

October 2025

This header provides known hosts management functionality similar to SSH's known_hosts. Tracks server identity keys to detect man-in-the-middle attacks and key changes.

Known hosts file format:

• Identity key entries: <IP:port> x25519 <hex_key> [comment]
• No-identity entries: <IP:port> no-identity [comment]

Note

File format examples:

• IPv4: 192.0.2.1:8080 x25519 1234abcd... ascii-chat
• IPv6: [2001:db8::1]:8080 x25519 1234abcd... ascii-chat
• No-identity: 192.0.2.1:8080 no-identity

No-identity servers: Servers without identity keys use "no-identity" entries. Cannot verify key (ephemeral keys change each connection) but can track server identity.

Key comparison: Uses constant-time comparison (sodium_memcmp) to prevent timing attacks.

MITM detection: Detects key mismatches by comparing received key with stored key. If key doesn't match, displays warning and prompts user for confirmation.

Multiple entries: Can have multiple entries for same IP:port (e.g., key rotation). Function searches all entries and uses first matching key.

Zero key handling: Special case for no-identity servers with zero keys. Zero key matches zero key (secure no-identity connection previously accepted).

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

October 2025

This file contains BearSSL tools utilities adapted to work with in-memory PEM data instead of files. Original code from BearSSL tools (ISC license).

These utilities are used for loading system CA certificates for TLS validation.

Note

BearSSL adaptation: Original BearSSL tools read PEM data from files. This version works with in-memory PEM data for better flexibility.

Trust anchors: Trust anchors are root CA certificates used for TLS validation. Loaded from system CA certificate store and used to validate server certificates.

Memory management: Trust anchors contain dynamically allocated memory. Must call free_ta_contents() for each anchor and free anchor_list.buf.

Author

Thomas Pornin (original BearSSL tools)

Zachary Fogg me@zf.nosp@m.o.gg (adaptation for ascii-chat)

Date

October 2025

This header provides SSH agent integration for signing operations. Allows keys to stay in SSH agent (not loaded into memory) for better security.

Note

SSH agent: Uses SSH agent protocol to communicate with ssh-agent. Keys stay in agent and are never loaded into application memory.

Platform support:

• Unix: Uses SSH_AUTH_SOCK environment variable (Unix domain socket)
• Windows: Uses SSH_AUTH_SOCK environment variable (named pipe)

Key format: Only Ed25519 keys are supported. RSA/ECDSA keys are NOT supported.

Agent detection: Checks SSH_AUTH_SOCK environment variable. On Unix, also verifies socket is accessible. On Windows, only checks environment variable (named pipes handled differently).

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

October 2025

Macro Definition Documentation

ANCHOR_LIST_INIT

#define ANCHOR_LIST_INIT   {NULL, 0, 0}

#include <include/ascii-chat/crypto/pem.h>

Initializer for anchor_list.

Macro for initializing an empty anchor_list structure. Sets all fields to zero/NULL.

Definition at line 94 of file pem.h.

Referenced by https_get().

CRYPTO_FINGERPRINT_SIZE

#define CRYPTO_FINGERPRINT_SIZE   32

#include <include/ascii-chat/crypto/crypto.h>

Ed25519 key fingerprint size in bytes.

SHA-256 hash of the key, resulting in 32 bytes.

Definition at line 254 of file include/ascii-chat/crypto/crypto.h.

CRYPTO_HEX_KEY64_SIZE

#define CRYPTO_HEX_KEY64_SIZE   128

#include <include/ascii-chat/crypto/crypto.h>

Hex string size for 64-byte key (128 hex characters).

Definition at line 270 of file include/ascii-chat/crypto/crypto.h.

CRYPTO_HEX_KEY64_SIZE_NULL

#define CRYPTO_HEX_KEY64_SIZE_NULL   129

#include <include/ascii-chat/crypto/crypto.h>

Hex string size for 64-byte key with null terminator (129 bytes).

Definition at line 272 of file include/ascii-chat/crypto/crypto.h.

CRYPTO_HEX_KEY_SIZE

#define CRYPTO_HEX_KEY_SIZE   64

#include <include/ascii-chat/crypto/crypto.h>

Hex string size for 32-byte key (64 hex characters).

Definition at line 266 of file include/ascii-chat/crypto/crypto.h.

Referenced by add_known_host(), and compute_key_fingerprint().

CRYPTO_HEX_KEY_SIZE_NULL

#define CRYPTO_HEX_KEY_SIZE_NULL   65

#include <include/ascii-chat/crypto/crypto.h>

Hex string size for 32-byte key with null terminator (65 bytes).

Definition at line 268 of file include/ascii-chat/crypto/crypto.h.

Referenced by add_known_host(), compute_key_fingerprint(), and prompt_unknown_host().

CRYPTO_KEY_SIZE

#define CRYPTO_KEY_SIZE   32

#include <include/ascii-chat/crypto/crypto.h>

Ed25519 key size in bytes.

Ed25519 public and private keys are 32 bytes each.

Definition at line 245 of file include/ascii-chat/crypto/crypto.h.

CRYPTO_MAX_CIPHERTEXT_SIZE

#define CRYPTO_MAX_CIPHERTEXT_SIZE   (CRYPTO_MAX_PLAINTEXT_SIZE + CRYPTO_MAC_SIZE)

#include <include/ascii-chat/crypto/crypto.h>

Maximum ciphertext size (plaintext + MAC, ~1MB + 16 bytes).

Definition at line 83 of file include/ascii-chat/crypto/crypto.h.

CRYPTO_MAX_PLAINTEXT_SIZE

#define CRYPTO_MAX_PLAINTEXT_SIZE   ((size_t)1024 * 1024)

#include <include/ascii-chat/crypto/crypto.h>

Maximum plaintext size (1MB).

Definition at line 81 of file include/ascii-chat/crypto/crypto.h.

Referenced by acip_packet_plan(), acip_packet_seal(), crypto_create_encrypted_packet(), crypto_encrypt(), crypto_record_open_sequence(), and crypto_record_seal_into_domain().

NO_IDENTITY_MARKER

#define NO_IDENTITY_MARKER   "no-identity"

#include <include/ascii-chat/crypto/crypto.h>

No-identity entry marker ("no-identity").

Definition at line 290 of file include/ascii-chat/crypto/crypto.h.

Referenced by add_known_host(), and check_known_host_with_key().

OPENPGP_ALGO_ECDH

#define OPENPGP_ALGO_ECDH   18

#include <include/ascii-chat/crypto/gpg/openpgp.h>

OpenPGP algorithm ID for ECDH (Curve25519).

Definition at line 60 of file openpgp.h.

OPENPGP_ALGO_EDDSA

#define OPENPGP_ALGO_EDDSA   22

#include <include/ascii-chat/crypto/gpg/openpgp.h>

OpenPGP algorithm ID for EdDSA (Ed25519).

Definition at line 57 of file openpgp.h.

Referenced by openpgp_parse_public_key_packet(), and openpgp_parse_secret_key_packet().

OPENPGP_TAG_PUBLIC_KEY

#define OPENPGP_TAG_PUBLIC_KEY   6

#include <include/ascii-chat/crypto/gpg/openpgp.h>

OpenPGP packet tag for Public Key Packet.

Definition at line 45 of file openpgp.h.

Referenced by openpgp_parse_binary_pubkey().

OPENPGP_TAG_SECRET_KEY

#define OPENPGP_TAG_SECRET_KEY   5

#include <include/ascii-chat/crypto/gpg/openpgp.h>

OpenPGP packet tag for Secret Key Packet.

Definition at line 48 of file openpgp.h.

Referenced by openpgp_parse_armored_seckey(), and openpgp_parse_binary_seckey().

OPENPGP_TAG_SIGNATURE

#define OPENPGP_TAG_SIGNATURE   2

#include <include/ascii-chat/crypto/gpg/openpgp.h>

OpenPGP packet tag for Signature Packet.

Definition at line 54 of file openpgp.h.

OPENPGP_TAG_USER_ID

#define OPENPGP_TAG_USER_ID   13

#include <include/ascii-chat/crypto/gpg/openpgp.h>

OpenPGP packet tag for User ID Packet.

Definition at line 51 of file openpgp.h.

REKEY_DEFAULT_PACKET_THRESHOLD

#define REKEY_DEFAULT_PACKET_THRESHOLD   1000000

#include <include/ascii-chat/crypto/crypto.h>

Default rekey packet threshold (1 million packets).

Definition at line 1115 of file include/ascii-chat/crypto/crypto.h.

Referenced by crypto_init().

REKEY_DEFAULT_TIME_THRESHOLD

#define REKEY_DEFAULT_TIME_THRESHOLD   (3600LL * NS_PER_SEC_INT)

#include <include/ascii-chat/crypto/crypto.h>

Default rekey time threshold (1 hour in nanoseconds).

Definition at line 1113 of file include/ascii-chat/crypto/crypto.h.

Referenced by crypto_init().

REKEY_MAX_FAILURE_COUNT

#define REKEY_MAX_FAILURE_COUNT   10

#include <include/ascii-chat/crypto/crypto.h>

Maximum consecutive rekey failures before giving up.

Definition at line 1121 of file include/ascii-chat/crypto/crypto.h.

Referenced by crypto_rekey_init().

REKEY_MIN_INTERVAL

#define REKEY_MIN_INTERVAL   (3LL * NS_PER_SEC_INT)

#include <include/ascii-chat/crypto/crypto.h>

Minimum time interval between rekey requests (3 seconds in nanoseconds for testing, 60 for production).

Definition at line 1111 of file include/ascii-chat/crypto/crypto.h.

Referenced by crypto_rekey_init().

REKEY_MIN_REQUEST_INTERVAL

#define REKEY_MIN_REQUEST_INTERVAL   (60LL * NS_PER_SEC_INT)

#include <include/ascii-chat/crypto/crypto.h>

Minimum interval between rekey requests (60 seconds in nanoseconds, DDoS protection).

Definition at line 1123 of file include/ascii-chat/crypto/crypto.h.

REKEY_TEST_PACKET_THRESHOLD

#define REKEY_TEST_PACKET_THRESHOLD   1000

#include <include/ascii-chat/crypto/crypto.h>

Test mode rekey packet threshold (1000 packets).

Definition at line 1119 of file include/ascii-chat/crypto/crypto.h.

Referenced by crypto_init().

REKEY_TEST_TIME_THRESHOLD

#define REKEY_TEST_TIME_THRESHOLD   (30LL * NS_PER_SEC_INT)

#include <include/ascii-chat/crypto/crypto.h>

Test mode rekey time threshold (30 seconds in nanoseconds).

Definition at line 1117 of file include/ascii-chat/crypto/crypto.h.

Referenced by crypto_init().

SSH_ED25519_KEY_TYPE

#define SSH_ED25519_KEY_TYPE   "ssh-ed25519"

#include <include/ascii-chat/crypto/crypto.h>

SSH Ed25519 key type string ("ssh-ed25519").

Definition at line 286 of file include/ascii-chat/crypto/crypto.h.

SSH_KEY_HEADER_SIZE

#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)

#include <include/ascii-chat/crypto/crypto.h>

Definition at line 231 of file include/ascii-chat/crypto/crypto.h.

#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)

Referenced by parse_ssh_ed25519_line().

SSH_KEY_PERMISSIONS_MASK

#define SSH_KEY_PERMISSIONS_MASK   (S_IRWXG | S_IRWXO)

#include <include/ascii-chat/crypto/crypto.h>

Definition at line 299 of file include/ascii-chat/crypto/crypto.h.

Referenced by validate_ssh_key_file().

SSH_KEY_PUBLIC_KEY_LENGTH_SIZE

#define SSH_KEY_PUBLIC_KEY_LENGTH_SIZE   4

#include <include/ascii-chat/crypto/crypto.h>

Definition at line 229 of file include/ascii-chat/crypto/crypto.h.

SSH_KEY_PUBLIC_KEY_SIZE

#define SSH_KEY_PUBLIC_KEY_SIZE   32

#include <include/ascii-chat/crypto/crypto.h>

Definition at line 230 of file include/ascii-chat/crypto/crypto.h.

SSH_KEY_RECOMMENDED_PERMISSIONS

#define SSH_KEY_RECOMMENDED_PERMISSIONS   0600

#include <include/ascii-chat/crypto/crypto.h>

Definition at line 300 of file include/ascii-chat/crypto/crypto.h.

SSH_KEY_TYPE_LENGTH_SIZE

#define SSH_KEY_TYPE_LENGTH_SIZE   4

#include <include/ascii-chat/crypto/crypto.h>

Definition at line 227 of file include/ascii-chat/crypto/crypto.h.

SSH_KEY_TYPE_STRING_SIZE

#define SSH_KEY_TYPE_STRING_SIZE   11

#include <include/ascii-chat/crypto/crypto.h>

Definition at line 228 of file include/ascii-chat/crypto/crypto.h.

X25519_KEY_TYPE

#define X25519_KEY_TYPE   "x25519"

#include <include/ascii-chat/crypto/crypto.h>

X25519 key type string ("x25519").

Definition at line 288 of file include/ascii-chat/crypto/crypto.h.

Referenced by add_known_host().

Typedef Documentation

crypto_context_t

typedef struct crypto_context_t crypto_context_t

#include <include/ascii-chat/crypto/crypto.h>

Endpoint cryptographic state for handshake, packet protection, authentication, and rekeying.

The context owns ephemeral X25519 material, the derived shared and optional password keys, negotiated wire sizes, authentication nonces, packet counters, and temporary keys during a rotation. Transports borrow it when sealing or opening packets. It is initialized through the crypto API and destroyed with crypto_destroy() so secret fields are wiped rather than copied or freed by callers.

Note

Nonce generation: Nonces are constructed as session_id || counter where session_id is 16 bytes and counter fills the remaining bytes. This construction aims to avoid nonce reuse, not to detect replays.

Session ID: Randomly generated for each connection and again on rekey. It contributes to nonce uniqueness; the decryptor does not check it.

Nonce counter: Starts at 1 (0 is reserved for testing) and increments for each encryption operation. Prevents nonce reuse within a session.

Byte order: Client must convert network byte order to host byte order for crypto parameters. Server uses host byte order directly.

Key exchange formats:

• Simple format: Only ephemeral public key (when server has no identity key)
• Authenticated format: Ephemeral key + identity key + signature (when server has identity key)

Endpoint cryptographic state for handshake, packet protection, authentication, and rekeying.

The context owns ephemeral X25519 material, the derived shared and optional password keys, negotiated wire sizes, authentication nonces, packet counters, and temporary keys during a rotation. Transports borrow it when sealing or opening packets. It must be initialized through the crypto API and destroyed through crypto_destroy() so secret fields are wiped rather than copied or freed by callers.

Enumeration Type Documentation

crypto_result_t

enum crypto_result_t

#include <include/ascii-chat/crypto/crypto.h>

Cryptographic operation result codes.

Enumerator
CRYPTO_OK	Operation succeeded
CRYPTO_ERROR_INIT_FAILED	Initialization failed
CRYPTO_ERROR_INVALID_PARAMS	Invalid parameters provided
CRYPTO_ERROR_MEMORY	Memory allocation failed
CRYPTO_ERROR_LIBSODIUM	libsodium operation failed
CRYPTO_ERROR_KEY_GENERATION	Key generation failed
CRYPTO_ERROR_PASSWORD_DERIVATION	Password-based key derivation failed
CRYPTO_ERROR_ENCRYPTION	Encryption operation failed
CRYPTO_ERROR_DECRYPTION	Decryption operation failed
CRYPTO_ERROR_INVALID_MAC	MAC verification failed (possible tampering)
CRYPTO_ERROR_BUFFER_TOO_SMALL	Output buffer too small
CRYPTO_ERROR_KEY_EXCHANGE_INCOMPLETE	Key exchange not complete
CRYPTO_ERROR_NONCE_EXHAUSTED	Nonce counter exhausted (should rekey)
CRYPTO_ERROR_REKEY_IN_PROGRESS	Rekey already in progress
CRYPTO_ERROR_REKEY_FAILED	Rekey handshake failed
CRYPTO_ERROR_REKEY_RATE_LIMITED	Too many rekey attempts (DDoS protection)

Definition at line 203 of file include/ascii-chat/crypto/crypto.h.

             {
  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       
} crypto_result_t;

Function Documentation

add_known_host()

asciichat_error_t add_known_host	(	const char *	server_ip,
		uint16_t	port,
		const uint8_t	server_key[32] )

#include <include/ascii-chat/crypto/known_hosts.h>

Add server to known_hosts.

Parameters

server_ip	Server IP address (IPv4 or IPv6, must not be NULL)
port	Server port number
server_key	Server's Ed25519 public key (32 bytes, must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Adds server identity key to known_hosts file. Creates file if it doesn't exist and creates directory if needed.

Note

File format: Adds entry as <IP:port> x25519 <hex_key> [comment]. Uses proper bracket notation for IPv6 addresses.

File creation: Creates ~/.ascii-chat/known_hosts if it doesn't exist. Creates ~/.ascii-chat/ directory if needed.

File permissions: Sets file permissions to 0600 (Unix only). Windows does not have Unix-style permissions.

Append mode: Appends entry to end of file (does not overwrite existing entries). Multiple entries for same IP:port are allowed (e.g., key rotation).

Key format: Converts server key to hex string (64 hex chars) for storage. Key is stored as X25519 format (32 bytes).

Warning

File permissions: Sets restrictive permissions (0600) but function may fail if file was just created by fopen (chmod may fail). This is acceptable.

References ED25519_PUBLIC_KEY_SIZE.

check_known_host()

asciichat_error_t check_known_host	(	const char *	server_ip,
		uint16_t	port,
		const uint8_t	server_key[32] )

#include <include/ascii-chat/crypto/known_hosts.h>

Check if server key is in known_hosts.

Parameters

server_ip	Server IP address (IPv4 or IPv6, must not be NULL)
port	Server port number
server_key	Server's Ed25519 public key (32 bytes, must not be NULL)

Returns

ASCIICHAT_OK if server not in known_hosts (first connection), positive value if key matches (connection verified), ERROR_CRYPTO_VERIFICATION if key mismatch (MITM warning)

Checks if server key matches known hosts entry for the given IP:port. Returns different values based on verification result.

Note

Return values:

• ASCIICHAT_OK (0): Server not in known_hosts (first connection, needs verification)
• Positive value (1): Key matches known_hosts (connection verified, safe to proceed)
• ERROR_CRYPTO_VERIFICATION: Key mismatch (MITM attack or key rotation, needs user confirmation)

File format: Searches for entries matching <IP:port> x25519 <hex_key>. Supports both IPv4 and IPv6 addresses with proper bracket notation.

Multiple entries: If multiple entries exist for same IP:port, searches all entries and uses first matching key. Continues searching if key doesn't match.

No-identity entries: Skips "no-identity" entries when checking identity keys. If server has identity key but entry is "no-identity", continues searching.

Zero key handling: Special case for no-identity servers with zero keys. If both server key and stored key are zero, returns match (verified no-identity connection).

Key comparison: Uses constant-time comparison (sodium_memcmp) to prevent timing attacks.

File location: Uses ~/.ascii-chat/known_hosts (or equivalent on Windows). Returns ASCIICHAT_OK if file doesn't exist (first connection).

Warning

This function should NOT be called for servers without identity keys. Use check_known_host_no_identity() for servers without identity keys.

Key mismatch: Returns ERROR_CRYPTO_VERIFICATION if key doesn't match. This indicates potential MITM attack or key rotation. User should verify.

References ED25519_PUBLIC_KEY_SIZE.

check_known_host_no_identity()

asciichat_error_t check_known_host_no_identity	(	const char *	server_ip,
		uint16_t	port )

#include <include/ascii-chat/crypto/known_hosts.h>

Check known_hosts for servers without identity key (no-identity entries).

Parameters

server_ip	Server IP address (IPv4 or IPv6, must not be NULL)
port	Server port number

Returns

ASCIICHAT_OK if server not in known_hosts (first connection), positive value if no-identity entry found (connection previously accepted), ERROR_CRYPTO_VERIFICATION if server previously had identity key but now has none

Checks if server has "no-identity" entry in known_hosts. Used for servers that don't have identity keys (ephemeral keys only).

Note

Return values:

• ASCIICHAT_OK (0): Server not in known_hosts (first connection, needs verification)
• Positive value (1): No-identity entry found (connection previously accepted)
• ERROR_CRYPTO_VERIFICATION: Server previously had identity key but now has none (security concern)

File format: Searches for entries matching <IP:port> no-identity. Does NOT verify keys (no keys to verify for no-identity servers).

Purpose: This function is NOT for key verification (no keys to verify). Use check_known_host() for servers with identity keys.

Security: Cannot verify server identity (no identity key to verify). Only tracks whether user previously accepted connection to this server.

Warning

This function should NOT be used for key verification. Use check_known_host() for servers with identity keys.

Security limitation: Cannot verify server identity (no keys to compare). Only provides tracking of previously accepted connections.

Definition at line 244 of file known_hosts.c.

                                                                                     {
  const char *path = get_known_hosts_path();
  int fd = platform_open("known_hosts_file", path, PLATFORM_O_RDONLY, FILE_PERM_PRIVATE);
  if (fd < 0) {
    // File doesn't exist - this is an unknown host that needs verification
    log_warn("Known hosts file does not exist: %s", path);
    return ASCIICHAT_OK; // Return 0 to indicate unknown host (first connection)
  }
 
  FILE *f = platform_fdopen("known_hosts_stream", fd, "r");
  defer(SAFE_FCLOSE(f));
  if (!f) {
    // Failed to open file descriptor as FILE*
    platform_close(fd);
    log_warn("Failed to open known hosts file: %s", path);
    return ASCIICHAT_OK; // Return 0 to indicate unknown host (first connection)
  }
 
  char line[BUFFER_SIZE_XLARGE];
  char expected_prefix[BUFFER_SIZE_MEDIUM];
 
  // Format IP:port with proper bracket notation for IPv6
  char ip_with_port[BUFFER_SIZE_MEDIUM];
  if (format_ip_with_port(server_ip, port, ip_with_port, sizeof(ip_with_port)) != ASCIICHAT_OK) {
 
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IP format: %s", server_ip);
  }
 
  // Add space after IP:port for prefix matching
  safe_snprintf(expected_prefix, sizeof(expected_prefix), "%s ", ip_with_port);
 
  while (fgets(line, sizeof(line), f)) {
    if (line[0] == '#')
      continue; // Comment
 
    // Use regex to parse and extract known_hosts line components
    char *parsed_ip_port = NULL, *parsed_key_type = NULL, *parsed_hex_key = NULL, *parsed_comment = NULL;
    if (!crypto_regex_match_known_hosts(line, &parsed_ip_port, &parsed_key_type, &parsed_hex_key, &parsed_comment)) {
      continue; // Line doesn't match known_hosts format
    }
    defer(SAFE_FREE(parsed_comment));
    defer(SAFE_FREE(parsed_hex_key));
    defer(SAFE_FREE(parsed_key_type));
    defer(SAFE_FREE(parsed_ip_port));
 
    // Check if IP:port matches what we're looking for (with IPv6 normalization)
    if (!compare_ip_port_strings(parsed_ip_port, ip_with_port)) {
      continue; // Different IP:port
    }
 
    // Found matching IP:port - check key type
    if (strcmp(parsed_key_type, "no-identity") == 0) {
      // This is a server without identity key that was previously accepted by the user
      // No warnings or user confirmation needed - user already accepted this server
      return 1; // Known host (no-identity entry) - secure connection
    }
 
    // If we found a normal identity key entry, this is a mismatch
    // Server previously had identity key but now has none
    NOTICE(DANGER, "SERVER IDENTITY REMOVED",
           "Server previously had identity key but now has none - potential security issue");
    return ERROR_CRYPTO_VERIFICATION; // Mismatch - server changed from identity to no-identity
  }
 
  return ASCIICHAT_OK; // Not found = first connection
}

References ASCIICHAT_OK, BUFFER_SIZE_MEDIUM, BUFFER_SIZE_XLARGE, compare_ip_port_strings(), crypto_regex_match_known_hosts(), ERROR_CRYPTO_VERIFICATION, ERROR_INVALID_PARAM, format_ip_with_port(), get_known_hosts_path(), log_warn, NOTICE, SAFE_FCLOSE, SAFE_FREE, safe_snprintf(), and SET_ERRNO.

Referenced by crypto_handshake_client_key_exchange().

check_known_host_with_key()

asciichat_error_t check_known_host_with_key	(	const char *	server_ip,
		uint16_t	port,
		const uint8_t	server_key[32],
		uint8_t	expected_key[32],
		bool *	has_expected_key )

#include <include/ascii-chat/crypto/known_hosts.h>

Same trust decision; optionally return the first stored nonzero identity for diagnostics. A mismatch can have multiple stored candidates. No fabricated key is returned for no-identity entries.

References ED25519_PUBLIC_KEY_SIZE.

compute_key_fingerprint()

void compute_key_fingerprint	(	const uint8_t	key[32],
		char	fingerprint[(32 *2+1)] )

#include <include/ascii-chat/crypto/known_hosts.h>

Compute SHA256 fingerprint of Ed25519 key for display.

Parameters

key	Ed25519 public key (32 bytes, must not be NULL)
fingerprint	Output buffer for fingerprint (65 bytes including null terminator)

Computes SHA256 fingerprint of Ed25519 public key for display. Fingerprint is displayed in hex format (64 hex chars + null terminator).

Note

Fingerprint format: SHA256 hash of key, displayed as 64 hex characters. Example: "a1b2c3d4e5f6..."

Output format: Fingerprint is stored as null-terminated hex string (65 bytes total). First 64 bytes are hex characters, 65th byte is null terminator.

Key format: Accepts Ed25519 public key (32 bytes). Fingerprint is computed over raw key bytes.

Use case: Used for displaying key fingerprints in warnings and prompts. Helps users verify keys visually.

Warning

Output buffer must be at least 65 bytes (64 hex chars + null terminator). Function does not validate buffer size (may overflow).

References ED25519_PUBLIC_KEY_SIZE, and HEX_STRING_SIZE_32.

crypto_combine_auth_data()

void crypto_combine_auth_data	(	const uint8_t *	hmac,
		const uint8_t *	challenge_nonce,
		uint8_t *	combined_out )

#include <include/ascii-chat/crypto/crypto.h>

Combine HMAC and challenge nonce for transmission.

Parameters

hmac	HMAC to transmit (32 bytes)
challenge_nonce	Challenge nonce to transmit (32 bytes)
combined_out	Output buffer for combined data (64 bytes)

Combines HMAC and challenge nonce into a single buffer: [HMAC:32][nonce:32] Used to pack authentication response data for transmission.

Note

Format: [HMAC:32][challenge_nonce:32] (64 bytes total)

Definition at line 1132 of file lib/crypto/crypto.c.

                                                                                                          {
  if (!hmac || !challenge_nonce || !combined_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: hmac=%p, challenge_nonce=%p, combined_out=%p", hmac,
              challenge_nonce, combined_out);
    return;
  }
 
  // Combine HMAC (32 bytes) + challenge nonce (32 bytes) = 64 bytes total
  memcpy(combined_out, hmac, HMAC_SHA256_SIZE);
  memcpy(combined_out + AUTH_HMAC_SIZE, challenge_nonce, AUTH_CHALLENGE_SIZE);
}

References AUTH_CHALLENGE_SIZE, AUTH_HMAC_SIZE, ERROR_INVALID_PARAM, HMAC_SHA256_SIZE, and SET_ERRNO.

crypto_compute_auth_response()

crypto_result_t crypto_compute_auth_response	(	const crypto_context_t *	ctx,
		const uint8_t	nonce[32],
		uint8_t	hmac_out[32] )

#include <include/ascii-chat/crypto/crypto.h>

Compute authentication response HMAC bound to DH shared_secret.

Parameters

ctx	Crypto context with keys (must have completed key exchange)
nonce	Challenge nonce from server (32 bytes)
hmac_out	Output HMAC (32 bytes)

Returns

CRYPTO_OK on success, error code on failure

Computes: HMAC(auth_key, nonce || shared_secret) This binds the password/key authentication to the DH exchange, preventing MITM.

Note

Key selection: Uses password_key if available, otherwise uses shared_key. This allows password authentication to be optional while still binding to DH.

Key exchange requirement: ctx->key_exchange_complete must be true. Returns CRYPTO_ERROR_INVALID_PARAMS if key exchange is not complete.

MITM prevention: By including shared_secret in the HMAC computation, an attacker cannot intercept and replay authentication responses without knowing the shared secret.

Warning

Context must have completed key exchange before calling this function.

References AUTH_CHALLENGE_SIZE, and HMAC_SHA256_SIZE.

crypto_compute_hmac()

crypto_result_t crypto_compute_hmac	(	crypto_context_t *	ctx,
		const uint8_t	key[32],
		const uint8_t	data[32],
		uint8_t	hmac[32] )

#include <include/ascii-chat/crypto/crypto.h>

Compute HMAC-SHA256 for fixed 32-byte data.

Parameters

ctx	Crypto context (for libsodium initialization check)
key	HMAC key (32 bytes)
data	Data to authenticate (32 bytes)
hmac	Output buffer for HMAC (32 bytes)

Returns

CRYPTO_OK on success, error code on failure

Computes HMAC-SHA256 over exactly 32 bytes of data. Useful for authenticating challenge nonces and other fixed-size values.

Note

Automatically initializes libsodium if not already initialized.

References AUTH_CHALLENGE_SIZE, HMAC_SHA256_KEY_SIZE, and HMAC_SHA256_SIZE.

crypto_compute_hmac_ex()

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] )

#include <include/ascii-chat/crypto/crypto.h>

Compute HMAC-SHA256 for variable-length data.

Parameters

ctx	Crypto context (for libsodium initialization check)
key	HMAC key (32 bytes)
data	Data to authenticate (variable length)
data_len	Length of data (must be > 0)
hmac	Output buffer for HMAC (32 bytes)

Returns

CRYPTO_OK on success, error code on failure

Computes HMAC-SHA256 over variable-length data. Useful for authenticating combined values (e.g., nonce || shared_secret).

Note

Automatically initializes libsodium if not already initialized.

References HMAC_SHA256_KEY_SIZE, and HMAC_SHA256_SIZE.

crypto_compute_password_hmac()

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 )

#include <include/ascii-chat/crypto/crypto.h>

Compute password-based HMAC for authentication.

Parameters

ctx	Crypto context
password_key	Password-derived key (32 bytes)
nonce	Challenge nonce (32 bytes)
shared_secret	DH shared secret (32 bytes)
hmac_out	Output buffer for HMAC (32 bytes)

Returns

ASCIICHAT_OK on success, error code on failure

Computes: HMAC(password_key, nonce || shared_secret) Binds password authentication to DH key exchange, preventing MITM.

Note

Used by authentication handlers to prove knowledge of password AND shared secret.

Combined data: nonce || shared_secret (64 bytes total)

Definition at line 1062 of file lib/crypto/crypto.c.

                                                                                                {
  if (!ctx || !password_key || !nonce || !shared_secret || !hmac_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM,
                     "Invalid parameters: ctx=%p, password_key=%p, nonce=%p, shared_secret=%p, hmac_out=%p", ctx,
                     password_key, nonce, shared_secret, hmac_out);
  }
 
  // Combine nonce and shared_secret for HMAC computation
  // This binds the password to the DH shared secret, preventing MITM attacks
  uint8_t combined_data[AUTH_CHALLENGE_SIZE + CRYPTO_SHARED_KEY_SIZE];
  memcpy(combined_data, nonce, AUTH_CHALLENGE_SIZE);
  memcpy(combined_data + AUTH_CHALLENGE_SIZE, shared_secret, CRYPTO_SHARED_KEY_SIZE);
 
  // Compute HMAC using the password-derived key
  if (crypto_compute_hmac_ex(ctx, password_key, combined_data, 64, hmac_out) != 0) {
    // Securely zero sensitive data containing shared secret even on error
    sodium_memzero(combined_data, sizeof(combined_data));
    return SET_ERRNO(ERROR_CRYPTO, "Failed to compute password HMAC");
  }
 
  // Securely zero sensitive data containing shared secret
  sodium_memzero(combined_data, sizeof(combined_data));
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, AUTH_CHALLENGE_SIZE, crypto_compute_hmac_ex(), CRYPTO_SHARED_KEY_SIZE, ERROR_CRYPTO, ERROR_INVALID_PARAM, and SET_ERRNO.

crypto_create_auth_challenge()

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 )

#include <include/ascii-chat/crypto/crypto.h>

Create authentication challenge packet.

Parameters

ctx	Crypto context (must be initialized)
packet_out	Output buffer for challenge packet
packet_size	Size of output buffer
packet_len_out	Output parameter for actual packet length

Returns

CRYPTO_OK on success, error code on failure

Creates an authentication challenge packet: [type:4][nonce:auth_challenge_size] Generates a random nonce and stores it in ctx->auth_nonce for later verification.

Note

Packet format: [PACKET_TYPE_AUTH_CHALLENGE:4][random_nonce:32] Total size: sizeof(uint32_t) + ctx->auth_challenge_size (typically 36 bytes)

The generated nonce is stored in ctx->auth_nonce and should be used later to verify the authentication response.

Definition at line 963 of file lib/crypto/crypto.c.

                                                                     {
  if (!ctx || !ctx->initialized || !packet_out || !packet_len_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters (ctx=%p, initialized=%d, packet_out=%p, packet_len_out=%p)", ctx,
              ctx ? ctx->initialized : 0, packet_out, packet_len_out);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  size_t required_size = sizeof(uint32_t) + ctx->auth_challenge_size; // type + nonce
  if (packet_size < required_size) {
    SET_ERRNO(ERROR_BUFFER, "Buffer too small (size=%zu, required=%zu)", packet_size, required_size);
    return CRYPTO_ERROR_BUFFER_TOO_SMALL;
  }
 
  // Generate random nonce (stores result in ctx->auth_nonce)
  crypto_result_t result = crypto_generate_nonce(ctx->auth_nonce);
  if (result != CRYPTO_OK) {
    return result;
  }
 
  // Pack packet: [type:4][nonce:auth_challenge_size]
  uint32_t packet_type = CRYPTO_PACKET_AUTH_CHALLENGE;
  SAFE_MEMCPY(packet_out, sizeof(packet_type), &packet_type, sizeof(packet_type));
  SAFE_MEMCPY(packet_out + sizeof(packet_type), ctx->auth_challenge_size, ctx->auth_nonce, ctx->auth_challenge_size);
 
  *packet_len_out = required_size;
  return CRYPTO_OK;
}

References crypto_context_t::auth_challenge_size, crypto_context_t::auth_nonce, CRYPTO_ERROR_BUFFER_TOO_SMALL, CRYPTO_ERROR_INVALID_PARAMS, crypto_generate_nonce(), CRYPTO_OK, ERROR_BUFFER, ERROR_INVALID_PARAM, crypto_context_t::initialized, SAFE_MEMCPY, and SET_ERRNO.

crypto_create_encrypted_packet()

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 )

#include <include/ascii-chat/crypto/crypto.h>

Create encrypted data packet for network transmission.

Parameters

ctx	Crypto context (must be initialized and ready)
data	Plaintext data to encrypt
data_len	Length of plaintext data
packet_out	Output buffer for encrypted packet
packet_size	Size of output buffer
packet_len_out	Output parameter for actual packet length

Returns

CRYPTO_OK on success, error code on failure

Creates an encrypted data packet: [type:4][length:4][encrypted_data:var] Encrypts the data using crypto_encrypt() and prepends packet type and length.

Note

Packet format: [PACKET_TYPE_ENCRYPTED_DATA:4][data_length:4][encrypted_data] Encrypted data format: [nonce:24][encrypted_data][MAC:16] Total size: sizeof(uint32_t) + sizeof(uint32_t) + data_len + nonce_size + mac_size

Context must be ready (crypto_is_ready() returns true) before calling. This requires either completed key exchange or password-based encryption.

Warning

Ensure packet_size is large enough for encrypted data + headers.

Definition at line 711 of file lib/crypto/crypto.c.

                                                                                                                {
  if (!ctx || !data || !packet_out || !packet_len_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters (ctx=%p, data=%p, packet_out=%p, packet_len_out=%p)", ctx, data,
              packet_out, packet_len_out);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  if (!crypto_is_ready(ctx)) {
    SET_ERRNO(ERROR_CRYPTO, "Crypto context not ready");
    return CRYPTO_ERROR_KEY_EXCHANGE_INCOMPLETE;
  }
 
  // Validate data_len to prevent integer overflow in size calculations.
  if (data_len > CRYPTO_MAX_PLAINTEXT_SIZE) {
    SET_ERRNO(ERROR_INVALID_PARAM, "data_len %zu exceeds max %d", data_len, CRYPTO_MAX_PLAINTEXT_SIZE);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  // Check for integer overflow: data_len + nonce_size + mac_size
  if (data_len > SIZE_MAX - ctx->nonce_size - ctx->mac_size) {
    SET_ERRNO(ERROR_BUFFER, "encrypted_size overflow");
    return CRYPTO_ERROR_BUFFER_TOO_SMALL;
  }
  size_t encrypted_size = data_len + ctx->nonce_size + ctx->mac_size;
 
  // Check for integer overflow: header + encrypted_size
  size_t header_size = sizeof(uint32_t) + sizeof(uint32_t);
  if (encrypted_size > SIZE_MAX - header_size) {
    SET_ERRNO(ERROR_BUFFER, "required_size overflow");
    return CRYPTO_ERROR_BUFFER_TOO_SMALL;
  }
  size_t required_size = header_size + encrypted_size; // type + len + encrypted_data
 
  if (packet_size < required_size) {
    SET_ERRNO(ERROR_BUFFER, "Buffer too small (size=%zu, required=%zu)", packet_size, required_size);
    return CRYPTO_ERROR_BUFFER_TOO_SMALL;
  }
 
  // Encrypt the data
  size_t ciphertext_len;
  uint8_t *encrypted_data = packet_out + sizeof(uint32_t) + sizeof(uint32_t);
  crypto_result_t result = crypto_encrypt(ctx, data, data_len, encrypted_data,
                                          packet_size - sizeof(uint32_t) - sizeof(uint32_t), &ciphertext_len);
  if (result != CRYPTO_OK) {
    return result;
  }
 
  // Pack packet: [type:4][length:4][encrypted_data:var]
  uint32_t packet_type = CRYPTO_PACKET_ENCRYPTED_DATA;
  uint32_t data_length = (uint32_t)ciphertext_len;
 
  SAFE_MEMCPY(packet_out, sizeof(packet_type), &packet_type, sizeof(packet_type));
  SAFE_MEMCPY(packet_out + sizeof(packet_type), sizeof(data_length), &data_length, sizeof(data_length));
 
  *packet_len_out = required_size;
  return CRYPTO_OK;
}

References crypto_encrypt(), CRYPTO_ERROR_BUFFER_TOO_SMALL, CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_ERROR_KEY_EXCHANGE_INCOMPLETE, crypto_is_ready(), CRYPTO_MAX_PLAINTEXT_SIZE, CRYPTO_OK, ERROR_BUFFER, ERROR_CRYPTO, ERROR_INVALID_PARAM, crypto_context_t::mac_size, crypto_context_t::nonce_size, SAFE_MEMCPY, and SET_ERRNO.

crypto_create_public_key_packet()

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 )

#include <include/ascii-chat/crypto/crypto.h>

Create public key packet for network transmission.

Parameters

ctx	Crypto context (must be initialized)
packet_out	Output buffer for packet
packet_size	Size of output buffer
packet_len_out	Output parameter for actual packet length

Returns

CRYPTO_OK on success, error code on failure

Creates a public key packet: [type:4][public_key:public_key_size] Used during key exchange handshake to send ephemeral public key to peer.

Note

Packet format: [PACKET_TYPE_PUBLIC_KEY:4][ephemeral_public_key:32] Total size: sizeof(uint32_t) + ctx->public_key_size (typically 36 bytes)

This packet is NOT encrypted - it's part of the key exchange protocol.

Definition at line 658 of file lib/crypto/crypto.c.

                                                                        {
  if (!ctx || !ctx->initialized || !packet_out || !packet_len_out) {
    SET_ERRNO(ERROR_INVALID_PARAM,
              "Invalid parameters (ctx=%p, initialized=%d, packet_out=%p, "
              "packet_len_out=%p)",
              ctx, ctx ? ctx->initialized : 0, packet_out, packet_len_out);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  size_t required_size = sizeof(uint32_t) + ctx->public_key_size; // type + key
  if (packet_size < required_size) {
    SET_ERRNO(ERROR_BUFFER, "Buffer too small (size=%zu, required=%zu)", packet_size, required_size);
    return CRYPTO_ERROR_BUFFER_TOO_SMALL;
  }
 
  // Pack packet: [type:4][public_key:32]
  uint32_t packet_type = CRYPTO_PACKET_PUBLIC_KEY;
  SAFE_MEMCPY(packet_out, sizeof(packet_type), &packet_type, sizeof(packet_type));
  // Bounds check to prevent buffer overflow
  size_t copy_size = (ctx->public_key_size <= X25519_KEY_SIZE) ? ctx->public_key_size : X25519_KEY_SIZE;
  SAFE_MEMCPY(packet_out + sizeof(packet_type), copy_size, ctx->public_key, copy_size);
 
  *packet_len_out = required_size;
  return CRYPTO_OK;
}

References CRYPTO_ERROR_BUFFER_TOO_SMALL, CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_OK, ERROR_BUFFER, ERROR_INVALID_PARAM, crypto_context_t::initialized, crypto_context_t::public_key, crypto_context_t::public_key_size, SAFE_MEMCPY, SET_ERRNO, and X25519_KEY_SIZE.

crypto_decrypt()

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 )

#include <include/ascii-chat/crypto/crypto.h>

Decrypt data using XSalsa20-Poly1305.

Parameters

ctx	Crypto context (must be initialized and ready)
ciphertext	Ciphertext data to decrypt
ciphertext_len	Length of ciphertext (must be >= nonce_size + mac_size)
plaintext_out	Output buffer for plaintext
plaintext_out_size	Size of output buffer
plaintext_len_out	Output parameter for actual plaintext length

Returns

CRYPTO_OK on success, CRYPTO_ERROR_INVALID_MAC if MAC verification fails

Decrypts data using XSalsa20-Poly1305 authenticated encryption. Uses shared_key if key exchange is complete, otherwise falls back to password_key.

Note

Ciphertext format: [nonce:nonce_size][encrypted_data][MAC:mac_size] Nonce is extracted from the first nonce_size bytes of ciphertext.

MAC verification: Automatically verified during decryption. Returns CRYPTO_ERROR_INVALID_MAC if MAC verification fails (indicating tampering or wrong key).

Plaintext size: ciphertext_len - nonce_size - mac_size

Buffer requirements: plaintext_out_size must be >= ciphertext_len - nonce_size - mac_size

Warning

Context must be ready (crypto_is_ready() returns true) before calling this function.

Always check return value. CRYPTO_ERROR_INVALID_MAC indicates tampering or wrong key.

Definition at line 511 of file lib/crypto/crypto.c.

                                                                                                             {
  ASCII_OTEL_SCOPE(CRYPTO_DECRYPT);
  ASCII_OTEL_ATTR_STRING("crypto.operation", "decrypt");
  ASCII_OTEL_ATTR_STRING("crypto.algorithm", "xsalsa20-poly1305");
  ASCII_OTEL_ATTR_INT("crypto.input.size", (int64_t)ciphertext_len);
  ASCII_OTEL_ATTR_INT("crypto.output.capacity", (int64_t)plaintext_out_size);
  if (!ctx || !ctx->initialized || !ciphertext || !plaintext_out || !plaintext_len_out) {
    SET_ERRNO(ERROR_INVALID_PARAM,
              "Invalid parameters: ctx=%p, initialized=%d, ciphertext=%p, plaintext_out=%p, plaintext_len_out=%p", ctx,
              ctx ? ctx->initialized : 0, ciphertext, plaintext_out, plaintext_len_out);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  if (!crypto_is_ready(ctx)) {
    SET_ERRNO(ERROR_CRYPTO, "Crypto context not ready for decryption");
    return CRYPTO_ERROR_KEY_EXCHANGE_INCOMPLETE;
  }
 
  ASCII_OTEL_ATTR_INT("crypto.nonce.size", ctx->nonce_size);
  ASCII_OTEL_ATTR_INT("crypto.mac.size", ctx->mac_size);
  ASCII_OTEL_ATTR_INT("crypto.key.size", ctx->encryption_key_size);
  ASCII_OTEL_ATTR_STRING("crypto.key.source", ctx->key_exchange_complete ? "x25519" : "password");
  // Check minimum ciphertext size (nonce + MAC)
  size_t min_ciphertext_size = ctx->nonce_size + ctx->mac_size;
  if (ciphertext_len < min_ciphertext_size) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Ciphertext too small: %zu < %zu", ciphertext_len, min_ciphertext_size);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  size_t plaintext_len = ciphertext_len - ctx->nonce_size - ctx->mac_size;
  if (plaintext_out_size < plaintext_len) {
    SET_ERRNO(ERROR_BUFFER, "Plaintext buffer too small: %zu < %zu", plaintext_out_size, plaintext_len);
    return CRYPTO_ERROR_BUFFER_TOO_SMALL;
  }
 
  // Extract nonce from beginning of ciphertext
  const uint8_t *nonce = ciphertext;
  const uint8_t *encrypted_data = ciphertext + ctx->nonce_size;
 
  // Choose decryption key (prefer shared key over password key)
  const uint8_t *decryption_key = NULL;
  if (ctx->key_exchange_complete) {
    decryption_key = ctx->shared_key;
  } else if (ctx->has_password) {
    decryption_key = ctx->password_key;
  } else {
    SET_ERRNO(ERROR_CRYPTO, "No decryption key available");
    return CRYPTO_ERROR_KEY_EXCHANGE_INCOMPLETE;
  }
 
  // Decrypt using NaCl secretbox (XSalsa20 + Poly1305)
  if (crypto_secretbox_open_easy(plaintext_out, encrypted_data, ciphertext_len - ctx->nonce_size, nonce,
                                 decryption_key) != 0) {
    log_error_every(US_PER_SEC_INT,
                    "Decryption failed: cipherlen=%zu key_exchange_complete=%d has_password=%d (invalid MAC)",
                    ciphertext_len - ctx->nonce_size, ctx->key_exchange_complete, ctx->has_password);
    SET_ERRNO(ERROR_CRYPTO, "Decryption failed - invalid MAC or corrupted data");
    return CRYPTO_ERROR_INVALID_MAC;
  }
 
  *plaintext_len_out = plaintext_len;
  ctx->bytes_decrypted += plaintext_len;
 
  ASCII_OTEL_ATTR_INT("crypto.output.size", (int64_t)*plaintext_len_out);
  ASCII_OTEL_ATTR_INT("crypto.authenticated", 1);
  ascii_otel_metric(ASCII_OTEL_METRIC_CRYPTO_DECRYPT_BYTES, (double)ciphertext_len);
  return CRYPTO_OK;
}

References ASCII_OTEL_ATTR_INT, ASCII_OTEL_ATTR_STRING, ascii_otel_metric(), ASCII_OTEL_SCOPE, crypto_context_t::bytes_decrypted, CRYPTO_ERROR_BUFFER_TOO_SMALL, CRYPTO_ERROR_INVALID_MAC, CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_ERROR_KEY_EXCHANGE_INCOMPLETE, crypto_is_ready(), CRYPTO_OK, crypto_context_t::encryption_key_size, ERROR_BUFFER, ERROR_CRYPTO, ERROR_INVALID_PARAM, crypto_context_t::has_password, crypto_context_t::initialized, crypto_context_t::key_exchange_complete, log_error_every, crypto_context_t::mac_size, crypto_context_t::nonce_size, crypto_context_t::password_key, SET_ERRNO, crypto_context_t::shared_key, and US_PER_SEC_INT.

Referenced by crypto_process_encrypted_packet(), and crypto_record_open_sequence().

crypto_derive_password_encryption_key()

crypto_result_t crypto_derive_password_encryption_key	(	const char *	password,
		uint8_t	encryption_key[32] )

#include <include/ascii-chat/crypto/crypto.h>

Derive deterministic encryption key from password for handshake.

Parameters

password	Password to derive key from
encryption_key	Output buffer for derived key (CRYPTO_ENCRYPTION_KEY_SIZE bytes)

Returns

CRYPTO_OK on success, error code on failure

Derives a deterministic key using a fixed salt (for handshake purposes). This allows password-protected sessions without requiring key exchange to be completed first.

Note

Uses same deterministic salt ("ascii-chat-password-salt-v1") as crypto_derive_password_key() for consistency.

Same password always produces same key. Only use for handshake encryption, not for long-term key storage.

References buffer_size, and CRYPTO_ENCRYPTION_KEY_SIZE.

crypto_derive_password_key()

crypto_result_t crypto_derive_password_key	(	crypto_context_t *	ctx,
		const char *	password )

#include <include/ascii-chat/crypto/crypto.h>

Derive key from password using Argon2id.

Parameters

ctx	Crypto context (must be initialized)
password	Password to derive key from

Returns

CRYPTO_OK on success, error code on failure

Derives a 32-byte encryption key from the password using Argon2id KDF. The salt is deterministic ("ascii-chat-password-salt-v1") for consistent key derivation across client/server.

Note

Argon2id is memory-hard, making offline brute-force attacks expensive.

Salt: Uses deterministic salt ("ascii-chat-password-salt-v1") padded to ARGON2ID_SALT_SIZE (32 bytes) with zeros. This ensures the same password produces the same key on both client and server.

Argon2id parameters: Uses INTERACTIVE limits (~0.1 seconds, ~64MB memory).

Warning

Deterministic salt: Same password always produces same key. Only use for session encryption, not long-term key storage.

Definition at line 316 of file lib/crypto/crypto.c.

                                                                                        {
  if (!ctx || !ctx->initialized || !password) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters (ctx=%p, initialized=%d, password=%p)", ctx,
              ctx ? ctx->initialized : 0, password);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  // Validate password length requirements
  crypto_result_t validation_result = crypto_validate_password(password);
  if (validation_result != CRYPTO_OK) {
    return validation_result;
  }
 
  // Use deterministic salt for consistent key derivation across client/server
  // This ensures the same password produces the same key on both sides
  // Salt must be exactly ARGON2ID_SALT_SIZE (32) bytes
  const char *deterministic_salt = "ascii-chat-password-salt-v1";
  size_t salt_str_len = strlen(deterministic_salt);
 
  // Zero-initialize the salt buffer first
  memset(ctx->password_salt, 0, ctx->salt_size);
 
  // Copy the salt string (will be padded with zeros to ctx->salt_size)
  memcpy(ctx->password_salt, deterministic_salt, (salt_str_len < ctx->salt_size) ? salt_str_len : ctx->salt_size);
 
  // Derive key using Argon2id (memory-hard, secure against GPU attacks)
  if (crypto_pwhash(ctx->password_key, ctx->encryption_key_size, password, strlen(password), ctx->password_salt,
                    crypto_pwhash_OPSLIMIT_INTERACTIVE, // ~0.1 seconds
                    crypto_pwhash_MEMLIMIT_INTERACTIVE, // ~64MB
                    crypto_pwhash_ALG_DEFAULT) != 0) {
    SET_ERRNO(ERROR_CRYPTO, "Password key derivation failed - possibly out of memory");
    return CRYPTO_ERROR_PASSWORD_DERIVATION;
  }
 
  log_dev("Password key derived successfully using Argon2id with deterministic salt");
  return CRYPTO_OK;
}

References CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_ERROR_PASSWORD_DERIVATION, CRYPTO_OK, crypto_validate_password(), crypto_context_t::encryption_key_size, ERROR_CRYPTO, ERROR_INVALID_PARAM, crypto_context_t::initialized, log_dev, crypto_context_t::password_key, crypto_context_t::password_salt, crypto_context_t::salt_size, and SET_ERRNO.

Referenced by crypto_handshake_client_auth_response(), and crypto_init_with_password().

crypto_destroy()

void crypto_destroy

(

crypto_context_t *

ctx

)

#include <include/ascii-chat/crypto/crypto.h>

Cleanup crypto context with secure memory wiping.

Parameters

ctx	Crypto context to cleanup

Securely zeroes all sensitive data (keys, salts, etc.) before freeing. Always call this when done with a crypto context.

Note

Uses sodium_memzero() to prevent key material from persisting in memory.

Definition at line 197 of file lib/crypto/crypto.c.

                                           {
  if (!ctx || !ctx->initialized) {
    return;
  }
 
  crypto_session_destroy(ctx);
 
  // Securely wipe sensitive data
  secure_memzero(ctx->private_key, sizeof(ctx->private_key));
  secure_memzero(ctx->shared_key, sizeof(ctx->shared_key));
  secure_memzero(ctx->password_key, sizeof(ctx->password_key));
  secure_memzero(ctx->password_salt, sizeof(ctx->password_salt));
 
  char encrypted_str[CRYPTO_ENCRYPTED_BUFFER_SIZE], decrypted_str[CRYPTO_DECRYPTED_BUFFER_SIZE];
  format_bytes_pretty(ctx->bytes_encrypted, encrypted_str, sizeof(encrypted_str));
  format_bytes_pretty(ctx->bytes_decrypted, decrypted_str, sizeof(decrypted_str));
 
  log_debug("Crypto context cleaned up (encrypted: %s, decrypted: %s)", encrypted_str, decrypted_str);
 
  // Clear entire context
  secure_memzero(ctx, sizeof(crypto_context_t));
}

References crypto_context_t::bytes_decrypted, crypto_context_t::bytes_encrypted, CRYPTO_DECRYPTED_BUFFER_SIZE, CRYPTO_ENCRYPTED_BUFFER_SIZE, crypto_session_destroy(), format_bytes_pretty(), crypto_context_t::initialized, log_debug, crypto_context_t::password_key, crypto_context_t::password_salt, crypto_context_t::private_key, and crypto_context_t::shared_key.

Referenced by crypto_handshake_destroy(), and crypto_init_with_password().

crypto_encrypt()

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 )

#include <include/ascii-chat/crypto/crypto.h>

Encrypt data using XSalsa20-Poly1305.

Parameters

ctx	Crypto context (must be initialized and ready)
plaintext	Plaintext data to encrypt
plaintext_len	Length of plaintext (must be > 0 and <= CRYPTO_MAX_PLAINTEXT_SIZE)
ciphertext_out	Output buffer for ciphertext
ciphertext_out_size	Size of output buffer
ciphertext_len_out	Output parameter for actual ciphertext length

Returns

CRYPTO_OK on success, error code on failure

Encrypts data using XSalsa20-Poly1305 authenticated encryption. Uses shared_key if key exchange is complete, otherwise falls back to password_key.

Note

Nonce generation: Automatically generates nonce as session_id || counter. Nonce is prepended to ciphertext: [nonce:24][encrypted_data + MAC]. Counter increments after each encryption to prevent nonce reuse.

Ciphertext format: [nonce:nonce_size][encrypted_data][MAC:mac_size] Total size = plaintext_len + nonce_size + mac_size

Buffer requirements: ciphertext_out_size must be >= plaintext_len + nonce_size + mac_size

Nonce counter: Starts at 1 (0 reserved for testing). Returns CRYPTO_ERROR_NONCE_EXHAUSTED if counter reaches 0 or UINT64_MAX (extremely unlikely, but triggers rekeying).

Maximum plaintext size: CRYPTO_MAX_PLAINTEXT_SIZE (1MB)

Rekeying: Automatically increments rekey_packet_count. Check crypto_should_rekey() after encryption to determine if rekeying should be initiated.

Warning

Context must be ready (crypto_is_ready() returns true) before calling this function.

Definition at line 431 of file lib/crypto/crypto.c.

                                                                                                                {
  ASCII_OTEL_SCOPE(CRYPTO_ENCRYPT);
  ASCII_OTEL_ATTR_STRING("crypto.operation", "encrypt");
  ASCII_OTEL_ATTR_STRING("crypto.algorithm", "xsalsa20-poly1305");
  ASCII_OTEL_ATTR_INT("crypto.input.size", (int64_t)plaintext_len);
  ASCII_OTEL_ATTR_INT("crypto.output.capacity", (int64_t)ciphertext_out_size);
  if (!ctx || !ctx->initialized || !plaintext || !ciphertext_out || !ciphertext_len_out) {
    SET_ERRNO(ERROR_INVALID_PARAM,
              "Invalid parameters: ctx=%p, initialized=%d, plaintext=%p, ciphertext_out=%p, ciphertext_len_out=%p", ctx,
              ctx ? ctx->initialized : 0, plaintext, ciphertext_out, ciphertext_len_out);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  if (plaintext_len == 0 || plaintext_len > CRYPTO_MAX_PLAINTEXT_SIZE) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid plaintext length: %zu (max: %d)", plaintext_len, CRYPTO_MAX_PLAINTEXT_SIZE);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  if (!crypto_is_ready(ctx)) {
    SET_ERRNO(ERROR_CRYPTO, "Crypto context not ready for encryption");
    return CRYPTO_ERROR_KEY_EXCHANGE_INCOMPLETE;
  }
 
  ASCII_OTEL_ATTR_INT("crypto.nonce.size", ctx->nonce_size);
  ASCII_OTEL_ATTR_INT("crypto.mac.size", ctx->mac_size);
  ASCII_OTEL_ATTR_INT("crypto.key.size", ctx->encryption_key_size);
  ASCII_OTEL_ATTR_STRING("crypto.key.source", ctx->key_exchange_complete ? "x25519" : "password");
  // Check output buffer size
  size_t required_size = plaintext_len + ctx->nonce_size + ctx->mac_size;
  if (ciphertext_out_size < required_size) {
    SET_ERRNO(ERROR_BUFFER, "Ciphertext buffer too small: %zu < %zu", ciphertext_out_size, required_size);
    return CRYPTO_ERROR_BUFFER_TOO_SMALL;
  }
 
  // Check for nonce counter exhaustion (extremely unlikely in practice)
  // Starting from 1, reaching UINT64_MAX would require ~292 billion years at 60 FPS.
  // With key rotation required at 1M packets (~16 seconds), exhaustion is virtually impossible.
  // This check is a safety fallback that should never trigger in practice.
  if (ctx->nonce_counter == 0 || ctx->nonce_counter == UINT64_MAX) {
    SET_ERRNO(ERROR_CRYPTO, "Nonce counter exhausted - key rotation required");
    return CRYPTO_ERROR_NONCE_EXHAUSTED;
  }
 
  // Choose encryption key BEFORE generating nonce (prevents nonce_counter increment on error)
  const uint8_t *encryption_key = NULL;
  if (ctx->key_exchange_complete) {
    encryption_key = ctx->shared_key;
  } else if (ctx->has_password) {
    encryption_key = ctx->password_key;
  } else {
    SET_ERRNO(ERROR_CRYPTO, "No encryption key available");
    return CRYPTO_ERROR_KEY_EXCHANGE_INCOMPLETE;
  }
 
  // Generate nonce and place at beginning of ciphertext
  uint8_t nonce[XSALSA20_NONCE_SIZE]; // Use maximum nonce size for buffer
  generate_nonce(ctx, nonce);
  SAFE_MEMCPY(ciphertext_out, ctx->nonce_size, nonce, ctx->nonce_size);
 
  log_debug_every(US_PER_SEC_INT, "Encrypting packet: counter=%llu plaintext_len=%zu",
                  (unsigned long long)(ctx->nonce_counter - 1), plaintext_len);
 
  // Encrypt using NaCl secretbox (XSalsa20 + Poly1305)
  if (crypto_secretbox_easy(ciphertext_out + ctx->nonce_size, plaintext, plaintext_len, nonce, encryption_key) != 0) {
    SET_ERRNO(ERROR_CRYPTO, "Encryption failed");
    return CRYPTO_ERROR_ENCRYPTION;
  }
 
  *ciphertext_len_out = required_size;
  ctx->bytes_encrypted += plaintext_len;
 
  // Increment rekey packet counter for rekeying trigger detection
  ctx->rekey_packet_count++;
 
  ASCII_OTEL_ATTR_INT("crypto.output.size", (int64_t)*ciphertext_len_out);
  ascii_otel_metric(ASCII_OTEL_METRIC_CRYPTO_ENCRYPT_BYTES, (double)plaintext_len);
  return CRYPTO_OK;
}

References ASCII_OTEL_ATTR_INT, ASCII_OTEL_ATTR_STRING, ascii_otel_metric(), ASCII_OTEL_SCOPE, crypto_context_t::bytes_encrypted, CRYPTO_ERROR_BUFFER_TOO_SMALL, CRYPTO_ERROR_ENCRYPTION, CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_ERROR_KEY_EXCHANGE_INCOMPLETE, CRYPTO_ERROR_NONCE_EXHAUSTED, crypto_is_ready(), CRYPTO_MAX_PLAINTEXT_SIZE, CRYPTO_OK, crypto_context_t::encryption_key_size, ERROR_BUFFER, ERROR_CRYPTO, ERROR_INVALID_PARAM, crypto_context_t::has_password, crypto_context_t::initialized, crypto_context_t::key_exchange_complete, log_debug_every, crypto_context_t::mac_size, crypto_context_t::nonce_counter, crypto_context_t::nonce_size, crypto_context_t::password_key, crypto_context_t::rekey_packet_count, SAFE_MEMCPY, SET_ERRNO, crypto_context_t::shared_key, US_PER_SEC_INT, and XSALSA20_NONCE_SIZE.

Referenced by crypto_create_encrypted_packet(), and crypto_record_seal_into_domain().

crypto_extract_auth_data()

void crypto_extract_auth_data	(	const uint8_t *	combined_data,
		uint8_t *	hmac_out,
		uint8_t *	challenge_out )

#include <include/ascii-chat/crypto/crypto.h>

Extract HMAC and challenge nonce from combined data.

Parameters

combined_data	Combined data received from peer (64 bytes)
hmac_out	Output buffer for HMAC (32 bytes)
challenge_out	Output buffer for challenge nonce (32 bytes)

Extracts HMAC and challenge nonce from combined buffer: [HMAC:32][nonce:32] Used to unpack authentication response data received from peer.

Note

Format: [HMAC:32][challenge_nonce:32] (64 bytes total)

Definition at line 1144 of file lib/crypto/crypto.c.

                                                                                                       {
  if (!combined_data || !hmac_out || !challenge_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: combined_data=%p, hmac_out=%p, challenge_out=%p", combined_data,
              hmac_out, challenge_out);
    return;
  }
 
  // Extract HMAC (first 32 bytes) and challenge nonce (last 32 bytes)
  memcpy(hmac_out, combined_data, HMAC_SHA256_SIZE);
  memcpy(challenge_out, combined_data + AUTH_CHALLENGE_SIZE, AUTH_CHALLENGE_SIZE);
}

References AUTH_CHALLENGE_SIZE, ERROR_INVALID_PARAM, HMAC_SHA256_SIZE, and SET_ERRNO.

crypto_generate_keypair()

crypto_result_t crypto_generate_keypair

(

crypto_context_t *

ctx

)

#include <include/ascii-chat/crypto/crypto.h>

Generate new X25519 key pair for key exchange.

Parameters

ctx	Crypto context

Returns

CRYPTO_OK on success, error code on failure

Generates a new ephemeral X25519 key pair. Called automatically by crypto_init(). Can be called again to regenerate keys (e.g., for rekeying).

Definition at line 220 of file lib/crypto/crypto.c.

                                                               {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "NULL context");
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  log_debug("About to call crypto_box_keypair");
  // Generate X25519 key pair for key exchange
  if (crypto_box_keypair(ctx->public_key, ctx->private_key) != 0) {
    SET_ERRNO(ERROR_CRYPTO, "Failed to generate X25519 key pair");
    return CRYPTO_ERROR_KEY_GENERATION;
  }
 
  log_debug("Generated X25519 key pair for key exchange");
  return CRYPTO_OK;
}

References CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_ERROR_KEY_GENERATION, CRYPTO_OK, ERROR_CRYPTO, ERROR_INVALID_PARAM, log_debug, crypto_context_t::private_key, crypto_context_t::public_key, and SET_ERRNO.

Referenced by crypto_init().

crypto_generate_nonce()

crypto_result_t crypto_generate_nonce

(

uint8_t

nonce[32]

)

#include <include/ascii-chat/crypto/crypto.h>

Generate random nonce for authentication.

Parameters

nonce

Output buffer for 32-byte random nonce

Returns

CRYPTO_OK on success, error code on failure

Generates a cryptographically secure random nonce for authentication challenges. Uses libsodium's secure random number generator.

Note

Automatically initializes libsodium if not already initialized.

References AUTH_CHALLENGE_SIZE.

crypto_get_public_key()

crypto_result_t crypto_get_public_key	(	const crypto_context_t *	ctx,
		uint8_t *	public_key_out )

#include <include/ascii-chat/crypto/crypto.h>

Get public key for sending to peer (step 1 of handshake).

Parameters

ctx	Crypto context
public_key_out	Output buffer for public key (must be CRYPTO_PUBLIC_KEY_SIZE bytes)

Returns

CRYPTO_OK on success, error code on failure

Retrieves our ephemeral public key for transmission to the peer. This is the first step in the key exchange handshake.

Definition at line 241 of file lib/crypto/crypto.c.

                                                                                            {
  if (!ctx || !ctx->initialized || !public_key_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters (ctx=%p, initialized=%d, public_key_out=%p)", ctx,
              ctx ? ctx->initialized : 0, public_key_out);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  // Bounds check to prevent buffer overflow
  size_t copy_size = (ctx->public_key_size <= X25519_KEY_SIZE) ? ctx->public_key_size : X25519_KEY_SIZE;
  SAFE_MEMCPY(public_key_out, copy_size, ctx->public_key, copy_size);
  return CRYPTO_OK;
}

References CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_OK, ERROR_INVALID_PARAM, crypto_context_t::initialized, crypto_context_t::public_key, crypto_context_t::public_key_size, SAFE_MEMCPY, SET_ERRNO, and X25519_KEY_SIZE.

crypto_get_rekey_status()

void crypto_get_rekey_status	(	const crypto_context_t *	ctx,
		char *	status_buffer,
		size_t	buffer_size )

#include <include/ascii-chat/crypto/crypto.h>

Get the current rekeying state for debugging/logging.

Parameters

ctx	Crypto context
status_buffer	Output buffer for status string
buffer_size	Size of status buffer

Formats a human-readable status string with rekeying state:

• Packet count since last rekey
• Time since last rekey
• Rekey in progress status
• Failure count
• Threshold values

Note

Safe to call with NULL ctx or buffer (does nothing).

Definition at line 1356 of file lib/crypto/crypto.c.

                                                                                                   {
  if (!ctx || !status_buffer || buffer_size == 0) {
    return;
  }
 
  time_t now = time(NULL);
  time_t elapsed = now - ctx->rekey_last_time;
  time_t remaining_time = (ctx->rekey_time_threshold > elapsed) ? (ctx->rekey_time_threshold - elapsed) : 0;
  uint64_t remaining_packets = (ctx->rekey_packet_threshold > ctx->rekey_packet_count)
                                   ? (ctx->rekey_packet_threshold - ctx->rekey_packet_count)
                                   : 0;
 
  safe_snprintf(status_buffer, buffer_size,
                "Rekey status: %s | "
                "Packets: %llu/%llu (%llu remaining) | "
                "Time: %ld/%ld sec (%ld sec remaining) | "
                "Rekeys: %llu | Failures: %d",
                ctx->rekey_in_progress ? "IN_PROGRESS" : "IDLE", (unsigned long long)ctx->rekey_packet_count,
                (unsigned long long)ctx->rekey_packet_threshold, (unsigned long long)remaining_packets, (long)elapsed,
                (long)ctx->rekey_time_threshold, (long)remaining_time, (unsigned long long)ctx->rekey_count,
                ctx->rekey_failure_count);
}

References buffer_size, crypto_context_t::rekey_count, crypto_context_t::rekey_failure_count, crypto_context_t::rekey_in_progress, crypto_context_t::rekey_last_time, crypto_context_t::rekey_packet_count, crypto_context_t::rekey_packet_threshold, crypto_context_t::rekey_time_threshold, and safe_snprintf().

crypto_get_status()

void crypto_get_status	(	const crypto_context_t *	ctx,
		char *	status_buffer,
		size_t	buffer_size )

#include <include/ascii-chat/crypto/crypto.h>

Get crypto context status information for debugging.

Parameters

ctx	Crypto context
status_buffer	Output buffer for status string
buffer_size	Size of status buffer

Formats a human-readable status string with context state information:

• Initialization status
• Password status
• Key exchange status
• Ready status
• Encrypted/decrypted byte counts
• Nonce counter value

Note

Safe to call with NULL ctx or buffer (does nothing).

Definition at line 614 of file lib/crypto/crypto.c.

                                                                                             {
  if (!ctx || !status_buffer || buffer_size == 0) {
    return;
  }
 
  if (!ctx->initialized) {
    SAFE_SNPRINTF(status_buffer, buffer_size, "Not initialized");
    return;
  }
 
  SAFE_SNPRINTF(status_buffer, buffer_size,
                "Initialized: %s, Password: %s, Key Exchange: %s, Ready: %s, "
                "Encrypted: %" PRIu64 " bytes, Decrypted: %" PRIu64 " bytes, Nonce: %" PRIu64,
                ctx->initialized ? "yes" : "no", ctx->has_password ? "yes" : "no",
                ctx->key_exchange_complete ? "complete" : "incomplete", crypto_is_ready(ctx) ? "yes" : "no",
                ctx->bytes_encrypted, ctx->bytes_decrypted, ctx->nonce_counter);
}

References buffer_size, crypto_context_t::bytes_decrypted, crypto_context_t::bytes_encrypted, crypto_is_ready(), crypto_context_t::has_password, crypto_context_t::initialized, crypto_context_t::key_exchange_complete, crypto_context_t::nonce_counter, and SAFE_SNPRINTF.

crypto_init()

crypto_result_t crypto_init

(

crypto_context_t *

ctx

)

#include <include/ascii-chat/crypto/crypto.h>

Initialize libsodium and crypto context.

Parameters

ctx	Crypto context to initialize

Returns

CRYPTO_OK on success, error code on failure

Initializes libsodium (thread-safe, idempotent) and generates a new X25519 key pair for key exchange.

Note

libsodium initialization is global and thread-safe. Multiple calls to crypto_init() will only initialize libsodium once.

Generates a new ephemeral key pair automatically. The nonce counter starts at 1 (0 is reserved for testing).

Definition at line 90 of file lib/crypto/crypto.c.

                                                   {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  // Initialize libsodium
  crypto_result_t result = init_libsodium();
  if (result != CRYPTO_OK) {
    return result;
  }
 
  // Clear context
  secure_memzero(ctx, sizeof(crypto_context_t));
 
  // Generate key pair for X25519 key exchange
  result = crypto_generate_keypair(ctx);
  if (result != CRYPTO_OK) {
    return result;
  }
 
  ctx->initialized = true;
  ctx->has_password = false;
  ctx->key_exchange_complete = false;
  ctx->peer_key_received = false;
  ctx->handshake_complete = false;
  ctx->encrypt_data = true; // Default: enable payload encryption
  ctx->nonce_counter = 1;   // Start from 1 (0 reserved for testing)
  ctx->bytes_encrypted = 0;
  ctx->bytes_decrypted = 0;
 
  // Set default algorithm-specific parameters (can be overridden during handshake)
  ctx->nonce_size = XSALSA20_NONCE_SIZE;
  ctx->mac_size = POLY1305_MAC_SIZE;
  ctx->hmac_size = HMAC_SHA256_SIZE;
  ctx->encryption_key_size = SECRETBOX_KEY_SIZE;
  ctx->auth_challenge_size = AUTH_CHALLENGE_SIZE;
  ctx->public_key_size = X25519_KEY_SIZE;
  ctx->private_key_size = X25519_KEY_SIZE;
  ctx->shared_key_size = X25519_KEY_SIZE;
  ctx->salt_size = ARGON2ID_SALT_SIZE;
  // signature_size and auth_public_key_size remain 0 until set by CRYPTO_PARAMETERS
  // (must be 0 for unauthenticated format detection in crypto_handshake_client_key_exchange)
 
  // Generate a random nonce prefix for this connection.
  randombytes_buf(ctx->session_id, sizeof(ctx->session_id));
 
  // Initialize rekeying state
  ctx->rekey_packet_count = 0;
  ctx->rekey_last_time = time(NULL); // Initialize to current time
  ctx->rekey_last_request_time = 0;  // No rekey request yet
  ctx->rekey_in_progress = false;
  ctx->rekey_failure_count = 0;
  ctx->has_temp_key = false;
  ctx->rekey_count = 0;
 
  // SECURITY: Use production-safe rekey thresholds by default
  // Rekey every 1 hour OR 1 million packets (whichever comes first)
  // Only use test mode if explicitly requested via environment variable
  if (is_test_environment()) {
    ctx->rekey_packet_threshold = REKEY_TEST_PACKET_THRESHOLD; // 1,000 packets
    ctx->rekey_time_threshold = REKEY_TEST_TIME_THRESHOLD;     // 30 seconds
    char duration_str[TIME_DURATION_BUFFER_SIZE];
    time_pretty(ctx->rekey_time_threshold, -1, duration_str, sizeof(duration_str));
    log_dev("Crypto context initialized with X25519 key exchange (TEST MODE rekey thresholds: %llu packets, %s)",
            (unsigned long long)ctx->rekey_packet_threshold, duration_str);
  } else {
    ctx->rekey_packet_threshold = REKEY_DEFAULT_PACKET_THRESHOLD; // 1 million packets
    ctx->rekey_time_threshold = REKEY_DEFAULT_TIME_THRESHOLD;     // already in nanoseconds (3600 * NS_PER_SEC_INT)
    char duration_str[TIME_DURATION_BUFFER_SIZE];
    time_pretty(ctx->rekey_time_threshold, -1, duration_str, sizeof(duration_str));
    log_dev("Crypto context initialized with X25519 key exchange (rekey thresholds: %llu packets, %s)",
            (unsigned long long)ctx->rekey_packet_threshold, duration_str);
  }
  return crypto_session_create(ctx) == ASCIICHAT_OK ? CRYPTO_OK : CRYPTO_ERROR_MEMORY;
}

References ARGON2ID_SALT_SIZE, ASCIICHAT_OK, AUTH_CHALLENGE_SIZE, crypto_context_t::auth_challenge_size, crypto_context_t::bytes_decrypted, crypto_context_t::bytes_encrypted, CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_ERROR_MEMORY, crypto_generate_keypair(), CRYPTO_OK, crypto_session_create(), crypto_context_t::encrypt_data, crypto_context_t::encryption_key_size, ERROR_INVALID_PARAM, crypto_context_t::handshake_complete, crypto_context_t::has_password, crypto_context_t::has_temp_key, HMAC_SHA256_SIZE, crypto_context_t::hmac_size, crypto_context_t::initialized, crypto_context_t::key_exchange_complete, log_dev, crypto_context_t::mac_size, crypto_context_t::nonce_counter, crypto_context_t::nonce_size, crypto_context_t::peer_key_received, POLY1305_MAC_SIZE, crypto_context_t::private_key_size, crypto_context_t::public_key_size, crypto_context_t::rekey_count, REKEY_DEFAULT_PACKET_THRESHOLD, REKEY_DEFAULT_TIME_THRESHOLD, crypto_context_t::rekey_failure_count, crypto_context_t::rekey_in_progress, crypto_context_t::rekey_last_request_time, crypto_context_t::rekey_last_time, crypto_context_t::rekey_packet_count, crypto_context_t::rekey_packet_threshold, REKEY_TEST_PACKET_THRESHOLD, REKEY_TEST_TIME_THRESHOLD, crypto_context_t::rekey_time_threshold, crypto_context_t::salt_size, SECRETBOX_KEY_SIZE, crypto_context_t::session_id, SET_ERRNO, crypto_context_t::shared_key_size, TIME_DURATION_BUFFER_SIZE, time_pretty(), X25519_KEY_SIZE, and XSALSA20_NONCE_SIZE.

Referenced by crypto_handshake_init(), and crypto_init_with_password().

crypto_init_with_password()

crypto_result_t crypto_init_with_password	(	crypto_context_t *	ctx,
		const char *	password )

#include <include/ascii-chat/crypto/crypto.h>

Initialize with password-based encryption.

Parameters

ctx	Crypto context to initialize
password	Password for key derivation

Returns

CRYPTO_OK on success, error code on failure

Initializes context and derives encryption key from password using Argon2id. The password is used as an additional layer on top of DH key exchange.

Note

Password must meet length requirements (8-256 characters).

Definition at line 167 of file lib/crypto/crypto.c.

                                                                                       {
  if (!ctx || !password) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, password=%p", ctx, password);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  if (strlen(password) == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Password cannot be empty");
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  // First initialize basic crypto
  crypto_result_t result = crypto_init(ctx);
  if (result != CRYPTO_OK) {
    return result;
  }
 
  // Derive password key
  result = crypto_derive_password_key(ctx, password);
  if (result != CRYPTO_OK) {
    crypto_destroy(ctx);
    return result;
  }
 
  ctx->has_password = true;
 
  log_dev("Crypto context initialized with password-based encryption");
  return CRYPTO_OK;
}

References crypto_derive_password_key(), crypto_destroy(), CRYPTO_ERROR_INVALID_PARAMS, crypto_init(), CRYPTO_OK, ERROR_INVALID_PARAM, crypto_context_t::has_password, log_dev, and SET_ERRNO.

Referenced by crypto_handshake_init_with_password().

crypto_is_ready()

bool crypto_is_ready

(

const crypto_context_t *

ctx

)

#include <include/ascii-chat/crypto/crypto.h>

Check if key exchange is complete and ready for encryption.

Parameters

ctx	Crypto context

Returns

true if key exchange is complete, false otherwise

Returns true only after both parties have exchanged public keys and the shared secret has been computed.

Definition at line 280 of file lib/crypto/crypto.c.

                                                  {
  if (!ctx || !ctx->initialized) {
    return false;
  }
 
  // Ready if either key exchange is complete OR password is set
  return ctx->key_exchange_complete || ctx->has_password;
}

References crypto_context_t::has_password, crypto_context_t::initialized, and crypto_context_t::key_exchange_complete.

Referenced by acip_packet_plan(), crypto_create_encrypted_packet(), crypto_decrypt(), crypto_encrypt(), crypto_get_status(), crypto_handshake_is_ready(), crypto_process_encrypted_packet(), packet_send_error(), packet_send_remote_log(), and send_packet_secure().

crypto_process_auth_challenge()

crypto_result_t crypto_process_auth_challenge	(	crypto_context_t *	ctx,
		const uint8_t *	packet,
		size_t	packet_len )

#include <include/ascii-chat/crypto/crypto.h>

Process authentication challenge packet.

Parameters

ctx	Crypto context (must be initialized)
packet	Challenge packet received from peer
packet_len	Length of challenge packet

Returns

CRYPTO_OK on success, error code on failure

Processes an authentication challenge packet: [type:4][nonce:auth_challenge_size] Extracts the nonce and stores it in ctx->auth_nonce for generating the response.

Note

Packet format: [PACKET_TYPE_AUTH_CHALLENGE:4][nonce:32] Expected size: sizeof(uint32_t) + ctx->auth_challenge_size (typically 36 bytes)

The extracted nonce is stored in ctx->auth_nonce and should be used with crypto_compute_auth_response() to generate the authentication response.

Definition at line 992 of file lib/crypto/crypto.c.

                                                                                                               {
  if (!ctx || !ctx->initialized || !packet) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters (ctx=%p, initialized=%d, packet=%p)", ctx,
              ctx ? ctx->initialized : 0, packet);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  size_t expected_size = sizeof(uint32_t) + ctx->auth_challenge_size; // type + nonce
  if (packet_len != expected_size) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid packet size (expected=%zu, got=%zu)", expected_size, packet_len);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  // Unpack packet: [type:4][nonce:auth_challenge_size]
  uint32_t packet_type;
  SAFE_MEMCPY(&packet_type, sizeof(packet_type), packet, sizeof(packet_type));
 
  if (packet_type != CRYPTO_PACKET_AUTH_CHALLENGE) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid packet type (expected=%u, got=%u)", CRYPTO_PACKET_AUTH_CHALLENGE,
              packet_type);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  // Store the nonce for HMAC computation (use buffer size for memcpy size, actual size from context)
  SAFE_MEMCPY(ctx->auth_nonce, sizeof(ctx->auth_nonce), packet + sizeof(packet_type), ctx->auth_challenge_size);
 
  log_debug("Auth challenge received and processed");
  return CRYPTO_OK;
}

References crypto_context_t::auth_challenge_size, crypto_context_t::auth_nonce, CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_OK, ERROR_INVALID_PARAM, crypto_context_t::initialized, log_debug, SAFE_MEMCPY, and SET_ERRNO.

crypto_process_auth_response()

crypto_result_t crypto_process_auth_response	(	crypto_context_t *	ctx,
		const uint8_t *	packet,
		size_t	packet_len )

#include <include/ascii-chat/crypto/crypto.h>

Process authentication response packet.

Parameters

ctx	Crypto context (must be initialized and have completed key exchange)
packet	Response packet received from peer
packet_len	Length of response packet

Returns

CRYPTO_OK on success, error code on failure

Processes an authentication response packet containing HMAC. Verifies the HMAC using crypto_verify_auth_response().

Note

Packet format depends on authentication method:

• Password: [HMAC:32][challenge_nonce:32] (64 bytes)
• Signature: [signature:64][challenge_nonce:32] (96 bytes)

Warning

Context must have completed key exchange before calling this function.

Definition at line 1022 of file lib/crypto/crypto.c.

                                                                                                              {
  if (!ctx || !ctx->initialized || !packet) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid context or packet (ctx=%p, initialized=%d, packet=%p)", ctx,
              ctx ? ctx->initialized : 0, packet);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  size_t expected_size = sizeof(uint32_t) + 32; // type + hmac
  if (packet_len != expected_size) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid packet size (expected=%zu, got=%zu)", expected_size, packet_len);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  // Unpack packet: [type:4][hmac:32]
  uint32_t packet_type;
  SAFE_MEMCPY(&packet_type, sizeof(packet_type), packet, sizeof(packet_type));
 
  if (packet_type != CRYPTO_PACKET_AUTH_RESPONSE) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid packet type (expected=0x%x, got=0x%x)", CRYPTO_PACKET_AUTH_RESPONSE,
              packet_type);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  const uint8_t *received_hmac = packet + sizeof(packet_type);
 
  // Verify HMAC using shared secret
  if (!crypto_verify_hmac(ctx->shared_key, ctx->auth_nonce, received_hmac)) {
    SET_ERRNO(ERROR_CRYPTO, "HMAC verification failed");
    return CRYPTO_ERROR_INVALID_MAC;
  }
 
  ctx->handshake_complete = true;
  log_debug("Authentication successful - handshake complete");
  return CRYPTO_OK;
}

References crypto_context_t::auth_nonce, CRYPTO_ERROR_INVALID_MAC, CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_OK, crypto_verify_hmac(), ERROR_CRYPTO, ERROR_INVALID_PARAM, crypto_context_t::handshake_complete, crypto_context_t::initialized, log_debug, SAFE_MEMCPY, SET_ERRNO, and crypto_context_t::shared_key.

crypto_process_encrypted_packet()

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 )

#include <include/ascii-chat/crypto/crypto.h>

Process received encrypted packet from peer.

Parameters

ctx	Crypto context (must be initialized and ready)
packet	Encrypted packet received from peer
packet_len	Length of packet
data_out	Output buffer for decrypted plaintext
data_size	Size of output buffer
data_len_out	Output parameter for actual plaintext length

Returns

CRYPTO_OK on success, CRYPTO_ERROR_INVALID_MAC if MAC verification fails

Processes an encrypted data packet: [type:4][length:4][encrypted_data:var] Decrypts the data using crypto_decrypt().

Note

Packet format: [PACKET_TYPE_ENCRYPTED_DATA:4][data_length:4][encrypted_data] Encrypted data format: [nonce:24][encrypted_data][MAC:16] Plaintext size: data_length - nonce_size - mac_size

Context must be ready (crypto_is_ready() returns true) before calling.

Warning

Always check return value. CRYPTO_ERROR_INVALID_MAC indicates tampering or wrong key.

Definition at line 770 of file lib/crypto/crypto.c.

                                                                                                           {
  if (!ctx || !packet || !data_out || !data_len_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters (ctx=%p, packet=%p, data_out=%p, data_len_out=%p)", ctx, packet,
              data_out, data_len_out);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  if (!crypto_is_ready(ctx)) {
    SET_ERRNO(ERROR_CRYPTO, "Crypto context not ready");
    return CRYPTO_ERROR_KEY_EXCHANGE_INCOMPLETE;
  }
 
  if (packet_len < sizeof(uint32_t) + sizeof(uint32_t)) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Packet too small (size=%zu)", packet_len);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  // Unpack packet: [type:4][length:4][encrypted_data:var]
  uint32_t packet_type;
  uint32_t data_length;
  SAFE_MEMCPY(&packet_type, sizeof(packet_type), packet, sizeof(packet_type));
  SAFE_MEMCPY(&data_length, sizeof(data_length), packet + sizeof(packet_type), sizeof(data_length));
 
  if (packet_type != CRYPTO_PACKET_ENCRYPTED_DATA) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid packet type (expected=%u, got=%u)", CRYPTO_PACKET_ENCRYPTED_DATA,
              packet_type);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  if (packet_len != sizeof(uint32_t) + sizeof(uint32_t) + data_length) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Packet length mismatch (expected=%zu, got=%zu)",
              sizeof(uint32_t) + sizeof(uint32_t) + data_length, packet_len);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  const uint8_t *encrypted_data = packet + sizeof(uint32_t) + sizeof(uint32_t);
  return crypto_decrypt(ctx, encrypted_data, data_length, data_out, data_size, data_len_out);
}

References crypto_decrypt(), CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_ERROR_KEY_EXCHANGE_INCOMPLETE, crypto_is_ready(), ERROR_CRYPTO, ERROR_INVALID_PARAM, SAFE_MEMCPY, and SET_ERRNO.

crypto_process_public_key_packet()

crypto_result_t crypto_process_public_key_packet	(	crypto_context_t *	ctx,
		const uint8_t *	packet,
		size_t	packet_len )

#include <include/ascii-chat/crypto/crypto.h>

Process received public key packet from peer.

Parameters

ctx	Crypto context (must be initialized)
packet	Public key packet received from peer
packet_len	Length of packet

Returns

CRYPTO_OK on success, error code on failure

Processes a public key packet: [type:4][public_key:public_key_size] Extracts peer's public key and computes shared secret automatically.

Note

Packet format: [PACKET_TYPE_PUBLIC_KEY:4][peer_public_key:32] Expected size: sizeof(uint32_t) + ctx->public_key_size (typically 36 bytes)

Automatically computes shared secret via crypto_set_peer_public_key(). After this call, crypto_is_ready() may return true if key exchange is complete.

Definition at line 685 of file lib/crypto/crypto.c.

                                                                                                                  {
  if (!ctx || !ctx->initialized || !packet) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters (ctx=%p, initialized=%d, packet=%p)", ctx,
              ctx ? ctx->initialized : 0, packet);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  size_t expected_size = sizeof(uint32_t) + ctx->public_key_size;
  if (packet_len != expected_size) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid packet size (expected=%zu, got=%zu)", expected_size, packet_len);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  // Unpack packet: [type:4][public_key:32]
  uint32_t packet_type;
  SAFE_MEMCPY(&packet_type, sizeof(packet_type), packet, sizeof(packet_type));
 
  if (packet_type != CRYPTO_PACKET_PUBLIC_KEY) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid packet type (expected=%u, got=%u)", CRYPTO_PACKET_PUBLIC_KEY, packet_type);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  const uint8_t *peer_public_key = packet + sizeof(packet_type);
  return crypto_set_peer_public_key(ctx, peer_public_key);
}

References CRYPTO_ERROR_INVALID_PARAMS, crypto_set_peer_public_key(), ERROR_INVALID_PARAM, crypto_context_t::initialized, crypto_context_t::public_key_size, SAFE_MEMCPY, and SET_ERRNO.

crypto_random_bytes()

crypto_result_t crypto_random_bytes	(	uint8_t *	buffer,
		size_t	len )

#include <include/ascii-chat/crypto/crypto.h>

Generate cryptographically secure random bytes.

Parameters

buffer	Output buffer for random bytes
len	Number of random bytes to generate (must be > 0)

Returns

CRYPTO_OK on success, error code on failure

Uses libsodium's secure random number generator (randombytes_buf). Suitable for generating nonces, keys, salts, and other cryptographic material.

Note

Automatically initializes libsodium if not already initialized.

Warning

Returns CRYPTO_ERROR_INVALID_PARAMS if buffer is NULL or len is 0.

Definition at line 639 of file lib/crypto/crypto.c.

                                                                 {
  if (!buffer || len == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters (buffer=%p, len=%zu)", buffer, len);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  crypto_result_t result = init_libsodium();
  if (result != CRYPTO_OK) {
    return result;
  }
 
  randombytes_buf(buffer, len);
  return CRYPTO_OK;
}

References CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_OK, ERROR_INVALID_PARAM, and SET_ERRNO.

crypto_rekey_abort()

void crypto_rekey_abort

(

crypto_context_t *

ctx

)

#include <include/ascii-chat/crypto/crypto.h>

Abort rekeying and fallback to old keys.

Parameters

ctx	Crypto context

Aborts ongoing rekey and clears temp_* keys. Called on rekey failure (timeout, bad keys, decryption failure, etc.).

Note

Clears temp_* keys and sets rekey_in_progress = false.

Old keys remain active (no service interruption).

Increments rekey_failure_count for exponential backoff.

Definition at line 1334 of file lib/crypto/crypto.c.

                                               {
  if (!ctx) {
    return;
  }
 
  log_warn("Aborting rekey (attempt %d failed), keeping old encryption key", ctx->rekey_failure_count + 1);
 
  // Wipe temporary keys securely
  secure_memzero(ctx->temp_public_key, sizeof(ctx->temp_public_key));
  secure_memzero(ctx->temp_private_key, sizeof(ctx->temp_private_key));
  secure_memzero(ctx->temp_shared_key, sizeof(ctx->temp_shared_key));
 
  // Reset rekey state
  ctx->has_temp_key = false;
  ctx->rekey_in_progress = false;
 
  // Increment failure counter for exponential backoff
  ctx->rekey_failure_count++;
 
  // Continue using old key - no disruption to connection
}

References crypto_context_t::has_temp_key, log_warn, crypto_context_t::rekey_failure_count, crypto_context_t::rekey_in_progress, crypto_context_t::temp_private_key, crypto_context_t::temp_public_key, and crypto_context_t::temp_shared_key.

Referenced by crypto_rekey_process_response(), and crypto_rekey_session_cleanup().

crypto_rekey_commit()

crypto_result_t crypto_rekey_commit

(

crypto_context_t *

ctx

)

#include <include/ascii-chat/crypto/crypto.h>

Commit to new keys after successful REKEY_COMPLETE.

Parameters

ctx	Crypto context

Returns

CRYPTO_OK on success, error code on failure

Switches from old shared_key to temp_shared_key, resets counters. Called after REKEY_COMPLETE is verified (decrypts successfully with new key).

Note

Replaces shared_key with temp_shared_key.

Resets rekey_packet_count, rekey_last_time, and rekey_in_progress.

Clears temp_* keys (they are now the active keys).

Warning

Only call after verifying REKEY_COMPLETE decrypts with new key.

Definition at line 1290 of file lib/crypto/crypto.c.

                                                           {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid context");
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  if (!ctx->rekey_in_progress || !ctx->has_temp_key) {
    SET_ERRNO(ERROR_CRYPTO, "No rekey in progress to commit");
    return CRYPTO_ERROR_REKEY_FAILED;
  }
 
  // Wipe old shared secret securely
  secure_memzero(ctx->shared_key, sizeof(ctx->shared_key));
 
  // Switch to new shared secret
  SAFE_MEMCPY(ctx->shared_key, sizeof(ctx->shared_key), ctx->temp_shared_key, sizeof(ctx->temp_shared_key));
 
  // Reset nonce counter to 1 (fresh start with new key)
  ctx->nonce_counter = 1;
 
  // Generate a new random nonce prefix for this key epoch.
  randombytes_buf(ctx->session_id, sizeof(ctx->session_id));
 
  // Reset rekey tracking
  ctx->rekey_packet_count = 0;
  ctx->rekey_last_time = time(NULL);
  ctx->rekey_count++;
 
  // Clear rekey state
  secure_memzero(ctx->temp_public_key, sizeof(ctx->temp_public_key));
  secure_memzero(ctx->temp_private_key, sizeof(ctx->temp_private_key));
  secure_memzero(ctx->temp_shared_key, sizeof(ctx->temp_shared_key));
  ctx->has_temp_key = false;
  ctx->rekey_in_progress = false;
 
  // Reset failure counter on successful rekey
  ctx->rekey_failure_count = 0;
 
  log_debug("Rekey committed successfully (rekey #%llu, nonce reset to 1, new session_id generated)",
            (unsigned long long)ctx->rekey_count);
 
  return CRYPTO_OK;
}

References CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_ERROR_REKEY_FAILED, CRYPTO_OK, ERROR_CRYPTO, ERROR_INVALID_PARAM, crypto_context_t::has_temp_key, crypto_context_t::initialized, log_debug, crypto_context_t::nonce_counter, crypto_context_t::rekey_count, crypto_context_t::rekey_failure_count, crypto_context_t::rekey_in_progress, crypto_context_t::rekey_last_time, crypto_context_t::rekey_packet_count, SAFE_MEMCPY, crypto_context_t::session_id, SET_ERRNO, crypto_context_t::shared_key, crypto_context_t::temp_private_key, crypto_context_t::temp_public_key, and crypto_context_t::temp_shared_key.

Referenced by crypto_record_commit_epoch().

crypto_rekey_init()

crypto_result_t crypto_rekey_init

(

crypto_context_t *

ctx

)

#include <include/ascii-chat/crypto/crypto.h>

Initiate rekeying by generating new ephemeral keys.

Parameters

ctx	Crypto context

Returns

CRYPTO_OK on success, error code on failure

Generates new ephemeral key pair and stores in temp_* fields. Called by the initiator (client or server) before sending REKEY_REQUEST.

Note

New keys are stored in temp_public_key and temp_private_key. They are NOT active until crypto_rekey_commit() is called.

Sets ctx->rekey_in_progress = true and updates rekey_last_request_time.

Warning

Do not call if rekey is already in progress.

Definition at line 1194 of file lib/crypto/crypto.c.

                                                         {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid context");
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  if (ctx->rekey_in_progress) {
    SET_ERRNO(ERROR_CRYPTO, "Rekey already in progress");
    return CRYPTO_ERROR_REKEY_IN_PROGRESS;
  }
 
  // Rate limiting: check minimum interval since last rekey
  time_t now = time(NULL);
  time_t since_last_rekey = now - ctx->rekey_last_time;
  time_t min_interval_seconds = (time_t)(REKEY_MIN_INTERVAL / NS_PER_SEC_INT);
  if (since_last_rekey < min_interval_seconds) {
    char elapsed_str[TIME_DURATION_BUFFER_SIZE], min_str[TIME_DURATION_BUFFER_SIZE];
    time_pretty((uint64_t)(since_last_rekey * 1e9), -1, elapsed_str, sizeof(elapsed_str));
    time_pretty((uint64_t)(min_interval_seconds * 1e9), -1, min_str, sizeof(min_str));
    log_warn("Rekey rate limited: %s since last rekey (minimum: %s)", elapsed_str, min_str);
    return CRYPTO_ERROR_REKEY_RATE_LIMITED;
  }
 
  // Check if too many consecutive failures
  if (ctx->rekey_failure_count >= REKEY_MAX_FAILURE_COUNT) {
    log_error("Too many consecutive rekey failures (%d), giving up", ctx->rekey_failure_count);
    return CRYPTO_ERROR_REKEY_FAILED;
  }
 
  // Generate new ephemeral X25519 keypair for rekeying
  if (crypto_box_keypair(ctx->temp_public_key, ctx->temp_private_key) != 0) {
    SET_ERRNO(ERROR_CRYPTO, "Failed to generate rekey ephemeral keypair");
    return CRYPTO_ERROR_KEY_GENERATION;
  }
 
  ctx->rekey_in_progress = true;
  ctx->has_temp_key = true;
 
  log_debug("Rekey initiated (packets: %llu, time elapsed: %ld sec, attempt %d)",
            (unsigned long long)ctx->rekey_packet_count, (long)since_last_rekey, ctx->rekey_failure_count + 1);
 
  return CRYPTO_OK;
}

References CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_ERROR_KEY_GENERATION, CRYPTO_ERROR_REKEY_FAILED, CRYPTO_ERROR_REKEY_IN_PROGRESS, CRYPTO_ERROR_REKEY_RATE_LIMITED, CRYPTO_OK, ERROR_CRYPTO, ERROR_INVALID_PARAM, crypto_context_t::has_temp_key, crypto_context_t::initialized, log_debug, log_error, log_warn, NS_PER_SEC_INT, crypto_context_t::rekey_failure_count, crypto_context_t::rekey_in_progress, crypto_context_t::rekey_last_time, REKEY_MAX_FAILURE_COUNT, REKEY_MIN_INTERVAL, crypto_context_t::rekey_packet_count, SET_ERRNO, crypto_context_t::temp_private_key, crypto_context_t::temp_public_key, TIME_DURATION_BUFFER_SIZE, and time_pretty().

Referenced by crypto_rekey_session_tick().

crypto_rekey_process_request()

crypto_result_t crypto_rekey_process_request	(	crypto_context_t *	ctx,
		const uint8_t *	peer_new_public_key )

#include <include/ascii-chat/crypto/crypto.h>

Process REKEY_REQUEST from peer (responder side).

Parameters

ctx	Crypto context
peer_new_public_key	Peer's new ephemeral public key (32 bytes)

Returns

CRYPTO_OK on success, error code on failure

Processes peer's new ephemeral public key from REKEY_REQUEST. Generates our own new ephemeral keys and computes new shared secret.

Note

Generates new temp_* keys and computes temp_shared_key. Keys are NOT active until crypto_rekey_commit() is called.

Should send REKEY_RESPONSE with our new public key after this call.

Definition at line 1238 of file lib/crypto/crypto.c.

                                                                                                        {
  if (!ctx || !ctx->initialized || !peer_new_public_key) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  // Generate our own new ephemeral keypair (responder side)
  if (crypto_box_keypair(ctx->temp_public_key, ctx->temp_private_key) != 0) {
    SET_ERRNO(ERROR_CRYPTO, "Failed to generate rekey ephemeral keypair");
    return CRYPTO_ERROR_KEY_GENERATION;
  }
 
  // Compute new shared secret: DH(our_new_private_key, peer_new_public_key)
  if (crypto_scalarmult(ctx->temp_shared_key, ctx->temp_private_key, peer_new_public_key) != 0) {
    SET_ERRNO(ERROR_CRYPTO, "Failed to compute rekey shared secret");
    secure_memzero(ctx->temp_private_key, sizeof(ctx->temp_private_key));
    secure_memzero(ctx->temp_public_key, sizeof(ctx->temp_public_key));
    return CRYPTO_ERROR_KEY_GENERATION;
  }
 
  ctx->rekey_in_progress = true;
  ctx->has_temp_key = true;
 
  log_debug("Rekey request processed (responder side), new shared secret computed");
 
  return CRYPTO_OK;
}

References CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_ERROR_KEY_GENERATION, CRYPTO_OK, ERROR_CRYPTO, ERROR_INVALID_PARAM, crypto_context_t::has_temp_key, crypto_context_t::initialized, log_debug, crypto_context_t::rekey_in_progress, SET_ERRNO, crypto_context_t::temp_private_key, crypto_context_t::temp_public_key, and crypto_context_t::temp_shared_key.

Referenced by crypto_rekey_session_tick().

crypto_rekey_process_response()

crypto_result_t crypto_rekey_process_response	(	crypto_context_t *	ctx,
		const uint8_t *	peer_new_public_key )

#include <include/ascii-chat/crypto/crypto.h>

Process REKEY_RESPONSE from peer (initiator side).

Parameters

ctx	Crypto context
peer_new_public_key	Peer's new ephemeral public key (32 bytes)

Returns

CRYPTO_OK on success, error code on failure

Processes peer's new ephemeral public key from REKEY_RESPONSE. Computes new shared secret using our temp_private_key and peer's temp_public_key.

Note

Computes temp_shared_key. Keys are NOT active until crypto_rekey_commit() is called.

Should send REKEY_COMPLETE encrypted with NEW key after this call.

Definition at line 1266 of file lib/crypto/crypto.c.

                                                                                                         {
  if (!ctx || !ctx->initialized || !peer_new_public_key) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  if (!ctx->rekey_in_progress || !ctx->has_temp_key) {
    SET_ERRNO(ERROR_CRYPTO, "No rekey in progress");
    return CRYPTO_ERROR_REKEY_FAILED;
  }
 
  // Compute new shared secret: DH(our_new_private_key, peer_new_public_key)
  // Use crypto_scalarmult to produce raw 32-byte shared secret for crypto_secretbox
  if (crypto_scalarmult(ctx->temp_shared_key, ctx->temp_private_key, peer_new_public_key) != 0) {
    SET_ERRNO(ERROR_CRYPTO, "Failed to compute rekey shared secret");
    crypto_rekey_abort(ctx);
    return CRYPTO_ERROR_KEY_GENERATION;
  }
 
  log_debug("Rekey response processed (initiator side), new shared secret computed");
 
  return CRYPTO_OK;
}

References CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_ERROR_KEY_GENERATION, CRYPTO_ERROR_REKEY_FAILED, CRYPTO_OK, crypto_rekey_abort(), ERROR_CRYPTO, ERROR_INVALID_PARAM, crypto_context_t::has_temp_key, crypto_context_t::initialized, log_debug, crypto_context_t::rekey_in_progress, SET_ERRNO, crypto_context_t::temp_private_key, and crypto_context_t::temp_shared_key.

Referenced by crypto_rekey_session_receive().

crypto_result_to_string()

const char * crypto_result_to_string

(

crypto_result_t

result

)

#include <include/ascii-chat/crypto/crypto.h>

Convert crypto result to human-readable string.

Parameters

result

Crypto result code

Returns

Human-readable error string (never NULL)

Returns a descriptive string for each crypto_result_t value. Useful for logging and error reporting.

Definition at line 606 of file lib/crypto/crypto.c.

                                                            {
  int idx = -result; // CRYPTO_OK=0, errors are negative
  if (idx >= 0 && (size_t)idx < CRYPTO_RESULT_STRING_COUNT) {
    return g_crypto_result_strings[idx];
  }
  return "Unknown error";
}

References CRYPTO_RESULT_STRING_COUNT.

Referenced by crypto_handshake_client_auth_response(), crypto_handshake_client_key_exchange(), crypto_handshake_init(), crypto_handshake_init_with_password(), crypto_handshake_server_auth_challenge(), and crypto_handshake_server_complete().

crypto_secure_compare()

bool crypto_secure_compare	(	const uint8_t *	lhs,
		const uint8_t *	rhs,
		size_t	len )

#include <include/ascii-chat/crypto/crypto.h>

Secure constant-time comparison of byte arrays.

Parameters

lhs	First byte array
rhs	Second byte array
len	Length of arrays to compare

Returns

true if arrays are equal, false otherwise

Uses constant-time comparison (sodium_memcmp) to prevent timing attacks. Always compares all bytes, regardless of where difference is found.

Note

Use this for comparing sensitive data: keys, MACs, HMACs, signatures. Do NOT use regular memcmp() for cryptographic comparisons.

Warning

Returns false if either pointer is NULL.

Definition at line 632 of file lib/crypto/crypto.c.

                                                                               {
  if (!lhs || !rhs) {
    return false;
  }
  return sodium_memcmp(lhs, rhs, len) == 0;
}

crypto_set_peer_public_key()

crypto_result_t crypto_set_peer_public_key	(	crypto_context_t *	ctx,
		const uint8_t *	peer_public_key )

#include <include/ascii-chat/crypto/crypto.h>

Set peer's public key and compute shared secret (step 2 of handshake).

Parameters

ctx	Crypto context
peer_public_key	Peer's ephemeral public key (CRYPTO_PUBLIC_KEY_SIZE bytes)

Returns

CRYPTO_OK on success, error code on failure

Receives peer's public key and computes the shared secret using X25519. After this call, crypto_is_ready() will return true.

Note

This function computes the shared secret immediately. The shared secret is used for encryption/decryption after key exchange is complete.

Definition at line 254 of file lib/crypto/crypto.c.

                                                                                                  {
  if (!ctx || !ctx->initialized || !peer_public_key) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters (ctx=%p, initialized=%d, peer_public_key=%p)", ctx,
              ctx ? ctx->initialized : 0, peer_public_key);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  // Store peer's public key
  // Bounds check to prevent buffer overflow
  size_t copy_size = (ctx->public_key_size <= X25519_KEY_SIZE) ? ctx->public_key_size : X25519_KEY_SIZE;
  SAFE_MEMCPY(ctx->peer_public_key, copy_size, peer_public_key, copy_size);
  ctx->peer_key_received = true;
 
  // Compute shared secret using X25519 and crypto_scalarmult (compatible with secretbox)
  // This produces a raw 32-byte shared secret suitable for crypto_secretbox
  if (crypto_scalarmult(ctx->shared_key, ctx->private_key, peer_public_key) != 0) {
    SET_ERRNO(ERROR_CRYPTO, "Failed to compute shared secret from peer public key");
    return CRYPTO_ERROR_KEY_GENERATION;
  }
 
  ctx->key_exchange_complete = true;
 
  log_debug("Key exchange complete");
  return CRYPTO_OK;
}

References CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_ERROR_KEY_GENERATION, CRYPTO_OK, ERROR_CRYPTO, ERROR_INVALID_PARAM, crypto_context_t::initialized, crypto_context_t::key_exchange_complete, log_debug, crypto_context_t::peer_key_received, crypto_context_t::peer_public_key, crypto_context_t::private_key, crypto_context_t::public_key_size, SAFE_MEMCPY, SET_ERRNO, crypto_context_t::shared_key, and X25519_KEY_SIZE.

Referenced by crypto_handshake_client_key_exchange(), crypto_handshake_server_auth_challenge(), and crypto_process_public_key_packet().

crypto_should_rekey()

bool crypto_should_rekey

(

const crypto_context_t *

ctx

)

#include <include/ascii-chat/crypto/crypto.h>

Check if rekeying should be triggered based on time or packet count thresholds.

Parameters

ctx	Crypto context

Returns

true if rekey should be initiated, false otherwise

Checks if rekeying should be triggered based on:

• Time since last rekey >= rekey_time_threshold
• Packet count since last rekey >= rekey_packet_threshold
• Minimum interval since last rekey request (DDoS protection)

Note

Should be called after each packet encryption.

Test environment: Automatically uses test thresholds if CRITERION_TEST or TESTING env var is set.

DDoS protection: Requires at least REKEY_MIN_REQUEST_INTERVAL seconds between requests.

Definition at line 1160 of file lib/crypto/crypto.c.

                                                      {
  if (!ctx || !ctx->initialized) {
    return false;
  }
 
  // Don't trigger rekey if one is already in progress
  if (ctx->rekey_in_progress) {
    return false;
  }
 
  // Don't trigger rekey if handshake isn't complete yet
  if (!ctx->handshake_complete) {
    return false;
  }
 
  // Check packet count threshold
  if (ctx->rekey_packet_count >= ctx->rekey_packet_threshold) {
    log_debug("Rekey triggered: packet count (%llu) >= threshold (%llu)", (unsigned long long)ctx->rekey_packet_count,
              (unsigned long long)ctx->rekey_packet_threshold);
    return true;
  }
 
  // Check time threshold
  time_t now = time(NULL);
  time_t elapsed = now - ctx->rekey_last_time;
  if (elapsed >= ctx->rekey_time_threshold) {
    log_debug("Rekey triggered: time elapsed (%ld sec) >= threshold (%ld sec)", (long)elapsed,
              (long)ctx->rekey_time_threshold);
    return true;
  }
 
  return false;
}

References crypto_context_t::handshake_complete, crypto_context_t::initialized, log_debug, crypto_context_t::rekey_in_progress, crypto_context_t::rekey_last_time, crypto_context_t::rekey_packet_count, crypto_context_t::rekey_packet_threshold, and crypto_context_t::rekey_time_threshold.

crypto_sign_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 )

#include <include/ascii-chat/crypto/crypto.h>

Sign ephemeral key with private key.

Parameters

private_key	Ed25519 private key for signing (64 bytes)
ephemeral_key	Ephemeral public key to sign (variable size)
ephemeral_key_size	Size of ephemeral key (typically 32 bytes for X25519)
signature_out	Output buffer for Ed25519 signature (64 bytes)

Returns

ASCIICHAT_OK on success, error code on failure

Signs ephemeral public key with Ed25519 identity key. Used during authenticated key exchange to prove server identity.

Note

Signature is over the ephemeral public key itself. Allows verification without revealing the identity key.

Used in authenticated key exchange format (ephemeral + identity + signature).

Definition at line 1108 of file lib/crypto/crypto.c.

                                                                                               {
  if (!private_key || !ephemeral_key || !signature_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: private_key=%p, ephemeral_key=%p, signature_out=%p",
                     private_key, ephemeral_key, signature_out);
  }
 
  if (ephemeral_key_size == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid ephemeral key size: %zu", ephemeral_key_size);
    return ERROR_INVALID_PARAM;
  }
 
  // Sign the ephemeral key with our Ed25519 private key
  if (private_key->type == KEY_TYPE_ED25519) {
    if (crypto_sign_detached(signature_out, NULL, ephemeral_key, ephemeral_key_size, private_key->key.ed25519) != 0) {
      return SET_ERRNO(ERROR_CRYPTO, "Failed to sign ephemeral key");
    }
  } else {
    return SET_ERRNO(ERROR_CRYPTO, "Unsupported private key type for signing");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, private_key_t::ed25519, ERROR_CRYPTO, ERROR_INVALID_PARAM, private_key_t::key, KEY_TYPE_ED25519, SET_ERRNO, and private_key_t::type.

crypto_validate_password()

crypto_result_t crypto_validate_password

(

const char *

password

)

#include <include/ascii-chat/crypto/crypto.h>

Validate password length requirements.

Parameters

password

Password to validate

Returns

CRYPTO_OK if valid, CRYPTO_ERROR_INVALID_PARAMS if too short/long

Validates that password meets length requirements (MIN_PASSWORD_LENGTH to MAX_PASSWORD_LENGTH characters).

Note

Password must be between MIN_PASSWORD_LENGTH (8) and MAX_PASSWORD_LENGTH (256) characters.

Definition at line 293 of file lib/crypto/crypto.c.

                                                               {
  if (!password) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Password is NULL");
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  size_t password_len = strlen(password);
 
  if (password_len < MIN_PASSWORD_LENGTH) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Password too short (minimum %d characters, got %zu)", MIN_PASSWORD_LENGTH,
              password_len);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  if (password_len > MAX_PASSWORD_LENGTH) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Password too long (maximum %d characters, got %zu)", MAX_PASSWORD_LENGTH,
              password_len);
    return CRYPTO_ERROR_INVALID_PARAMS;
  }
 
  return CRYPTO_OK;
}

References CRYPTO_ERROR_INVALID_PARAMS, CRYPTO_OK, ERROR_INVALID_PARAM, MAX_PASSWORD_LENGTH, MIN_PASSWORD_LENGTH, and SET_ERRNO.

Referenced by crypto_derive_password_encryption_key(), and crypto_derive_password_key().

crypto_verify_auth_response()

bool crypto_verify_auth_response	(	const crypto_context_t *	ctx,
		const uint8_t	nonce[32],
		const uint8_t	expected_hmac[32] )

#include <include/ascii-chat/crypto/crypto.h>

Verify authentication response HMAC bound to DH shared_secret.

Parameters

ctx	Crypto context with keys (must have completed key exchange)
nonce	Challenge nonce that was sent (32 bytes)
expected_hmac	Expected HMAC to verify (32 bytes)

Returns

true if HMAC is valid, false otherwise

Verifies: HMAC(auth_key, nonce || shared_secret)

Note

Key selection: Uses password_key if available, otherwise uses shared_key. Must match the key used by crypto_compute_auth_response() on the peer side.

Key exchange requirement: ctx->key_exchange_complete must be true. Returns false if key exchange is not complete.

Warning

Always check return value. False indicates authentication failure or wrong key.

References AUTH_CHALLENGE_SIZE, and HMAC_SHA256_SIZE.

crypto_verify_hmac()

bool crypto_verify_hmac	(	const uint8_t	key[32],
		const uint8_t	data[32],
		const uint8_t	expected_hmac[32] )

#include <include/ascii-chat/crypto/crypto.h>

Verify HMAC-SHA256 for fixed 32-byte data.

Parameters

key	HMAC key (32 bytes)
data	Data that was authenticated (32 bytes)
expected_hmac	Expected HMAC to verify (32 bytes)

Returns

true if HMAC is valid, false otherwise

Verifies HMAC-SHA256 using constant-time comparison. Prevents timing attacks during verification.

Note

Returns false if any parameter is NULL.

References AUTH_CHALLENGE_SIZE, HMAC_SHA256_KEY_SIZE, and HMAC_SHA256_SIZE.

crypto_verify_hmac_ex()

bool crypto_verify_hmac_ex	(	const uint8_t	key[32],
		const uint8_t *	data,
		size_t	data_len,
		const uint8_t	expected_hmac[32] )

#include <include/ascii-chat/crypto/crypto.h>

Verify HMAC-SHA256 for variable-length data.

Parameters

key	HMAC key (32 bytes)
data	Data that was authenticated (variable length)
data_len	Length of data (must be > 0)
expected_hmac	Expected HMAC to verify (32 bytes)

Returns

true if HMAC is valid, false otherwise

Verifies HMAC-SHA256 using constant-time comparison. Prevents timing attacks during verification.

Note

Returns false if any parameter is NULL or data_len is 0.

References HMAC_SHA256_KEY_SIZE, and HMAC_SHA256_SIZE.

crypto_verify_password()

bool crypto_verify_password	(	const crypto_context_t *	ctx,
		const char *	password )

#include <include/ascii-chat/crypto/crypto.h>

Verify password matches stored salt/key.

Parameters

ctx	Crypto context (must be initialized and have password)
password	Password to verify

Returns

true if password matches, false otherwise

Verifies that the provided password, when derived with the stored salt, produces the same key as stored in the context.

Note

Uses constant-time comparison to prevent timing attacks.

Salt: Uses same deterministic salt as crypto_derive_password_key().

Definition at line 354 of file lib/crypto/crypto.c.

                                                                               {
  if (!ctx || !ctx->initialized || !ctx->has_password || !password) {
    return false;
  }
 
  uint8_t test_key[SECRETBOX_KEY_SIZE]; // Use maximum size for buffer
 
  // Use the same deterministic salt for verification
  // Salt must be exactly ARGON2ID_SALT_SIZE (32) bytes
  const char *deterministic_salt = "ascii-chat-password-salt-v1";
  uint8_t salt[ARGON2ID_SALT_SIZE]; // Use maximum size for buffer
  size_t salt_str_len = strlen(deterministic_salt);
 
  // Zero-initialize the salt buffer first
  memset(salt, 0, ARGON2ID_SALT_SIZE);
 
  // Copy the salt string (will be padded with zeros to ctx->salt_size)
  memcpy(salt, deterministic_salt, (salt_str_len < ctx->salt_size) ? salt_str_len : ctx->salt_size);
 
  // Derive key with same salt
  if (crypto_pwhash(test_key, ctx->encryption_key_size, password, strlen(password), salt,
                    crypto_pwhash_OPSLIMIT_INTERACTIVE, crypto_pwhash_MEMLIMIT_INTERACTIVE,
                    crypto_pwhash_ALG_DEFAULT) != 0) {
    secure_memzero(test_key, sizeof(test_key));
    return false;
  }
 
  // Constant-time comparison
  bool match = (sodium_memcmp(test_key, ctx->password_key, ctx->encryption_key_size) == 0);
 
  secure_memzero(test_key, sizeof(test_key));
  return match;
}

References ARGON2ID_SALT_SIZE, crypto_context_t::encryption_key_size, crypto_context_t::has_password, crypto_context_t::initialized, crypto_context_t::password_key, crypto_context_t::salt_size, and SECRETBOX_KEY_SIZE.

crypto_verify_peer_signature()

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 )

#include <include/ascii-chat/crypto/crypto.h>

Verify peer's signature on ephemeral key.

Parameters

peer_public_key	Peer's Ed25519 public key (32 bytes)
ephemeral_key	Ephemeral public key that was signed (variable size)
ephemeral_key_size	Size of ephemeral key (typically 32 bytes for X25519)
signature	Ed25519 signature (64 bytes)

Returns

ASCIICHAT_OK if signature is valid, error code on failure

Verifies Ed25519 signature on ephemeral public key using peer's identity key. Used during authenticated key exchange to verify server identity.

Note

Signature is over the ephemeral public key itself, proving ownership of the identity key without revealing it.

Used in authenticated key exchange format (ephemeral + identity + signature).

Definition at line 1089 of file lib/crypto/crypto.c.

                                                                                                    {
  if (!peer_public_key || !ephemeral_key || !signature) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: peer_public_key=%p, ephemeral_key=%p, signature=%p",
                     peer_public_key, ephemeral_key, signature);
  }
 
  if (ephemeral_key_size == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid ephemeral key size: %zu", ephemeral_key_size);
  }
 
  // Verify the signature using Ed25519
  if (crypto_sign_verify_detached(signature, ephemeral_key, ephemeral_key_size, peer_public_key) != 0) {
    return SET_ERRNO(ERROR_CRYPTO, "Peer signature verification failed");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO, ERROR_INVALID_PARAM, and SET_ERRNO.

display_mitm_warning()

bool display_mitm_warning	(	const char *	server_ip,
		uint16_t	port,
		const uint8_t	expected_key[32],
		const uint8_t	received_key[32] )

#include <include/ascii-chat/crypto/known_hosts.h>

Display MITM warning with key comparison and prompt user for confirmation.

Parameters

server_ip	Server IP address (IPv4 or IPv6, must not be NULL)
port	Server port number
expected_key	First stored server key (32 bytes), or NULL if no stored public identity is available
received_key	Received server key from connection (32 bytes, must not be NULL)

Returns

true if user accepts the risk and wants to continue, false otherwise

Displays man-in-the-middle warning with key comparison and prompts user for confirmation. Shows both expected and received keys in hex format for comparison.

Note

Warning display: Shows formatted warning message with:

• Server IP:port
• Expected key fingerprint (SHA256)
• Received key fingerprint (SHA256)
• Prompt for user confirmation

Key fingerprints: Displays SHA256 fingerprints of both keys for easy comparison. Fingerprints are displayed in hex format (64 hex chars).

User prompt: Prompts user to accept risk (continue) or abort connection. Returns true if user accepts, false if user aborts.

Non-interactive mode: If not connected to TTY (snapshot mode), automatically accepts the connection (returns true). This allows automated connections.

Security: Key mismatch indicates potential MITM attack or key rotation. User should verify keys before accepting.

Warning

Always check return value. If false, connection should be aborted.

MITM risk: Key mismatch may indicate man-in-the-middle attack. User should verify keys before accepting connection.

References ED25519_PUBLIC_KEY_SIZE.

free_ta_contents()

void free_ta_contents

(

br_x509_trust_anchor *

ta

)

#include <include/ascii-chat/crypto/pem.h>

Free the contents of a trust anchor.

Parameters

ta	Pointer to trust anchor to free (must not be NULL)

Releases all dynamically allocated memory within a trust anchor structure, but does not free the structure itself. Call this for each trust anchor before freeing the anchor_list buffer.

Note

Memory cleanup: Frees certificate data, public key, and other dynamically allocated fields within trust anchor structure.

Structure preservation: Does not free the trust anchor structure itself. Only frees dynamically allocated fields within the structure.

Usage: Must be called for each trust anchor in anchor_list.buf before freeing anchor_list.buf. Loop through anchors and call for each one.

Warning

Memory leak: Must call this for each trust anchor before freeing anchor_list.buf. Failing to do so will leak memory.

Definition at line 436 of file pem.c.

                                                {
  if (!ta) {
    return;
  }
  xfree(ta->dn.data);
  switch (ta->pkey.key_type) {
  case BR_KEYTYPE_RSA:
    xfree((void *)ta->pkey.key.rsa.n);
    xfree((void *)ta->pkey.key.rsa.e);
    break;
  case BR_KEYTYPE_EC:
    xfree((void *)ta->pkey.key.ec.q);
    break;
  default:
    SET_ERRNO(ERROR_CRYPTO, "Unknown public key type in CA");
    break;
  }
}

References ERROR_CRYPTO, and SET_ERRNO.

Referenced by read_trust_anchors_from_memory().

get_known_hosts_path()

const char * get_known_hosts_path

(

void

)

#include <lib/crypto/known_hosts.c>

Get the path to the known_hosts file.

Get known_hosts file path.

Returns the path to the known_hosts file, using the same directory as all other ascii-chat configuration files (get_config_dir()).

PATH RESOLUTION:

• Unix: $XDG_CONFIG_HOME/ascii-chat/known_hosts or ~/.config/ascii-chat/known_hosts
• Windows: APPDATA%\ascii-chat\known_hosts

Returns

Pointer to cached known_hosts path (do not free), or NULL on failure

Note

The returned pointer is valid for the lifetime of the program

Returns

Path to known_hosts file (never NULL, cached)

Returns path to known_hosts file, expanding user directory if needed. Path is cached after first call.

Note

File location: Returns ~/.ascii-chat/known_hosts (or equivalent on Windows). Uses expand_path() to resolve user directory.

Path caching: Path is cached after first call to avoid repeated expansion. Cache is freed by known_hosts_destroy().

Platform-specific paths (same directory as config.toml):

• Unix: $XDG_CONFIG_HOME/ascii-chat/known_hosts if set, otherwise ~/.ascii-chat/known_hosts
• Windows: APPDATA%\ascii-chat\known_hosts if set, otherwise ~\.ascii-chat\known_hosts

Warning

Path may not exist: Function returns path even if file doesn't exist. File will be created when first entry is added.

Definition at line 57 of file known_hosts.c.

                                       {
  // Return cached path if already determined
  if (!g_known_hosts_path_cache) {
    char *config_dir = get_config_dir();
    if (!config_dir) {
      log_error("Failed to determine configuration directory for known_hosts");
      return NULL;
    }
    defer(SAFE_FREE(config_dir));
 
    // Build path: config_dir + "known_hosts"
    size_t config_len = strlen(config_dir);
    size_t total_len = config_len + strlen("known_hosts") + 1;
    char *path = SAFE_MALLOC(total_len, char *);
    if (!path) {
      log_error("Failed to allocate memory for known_hosts path");
      return NULL;
    }
 
    safe_snprintf(path, total_len, "%sknown_hosts", config_dir);
    g_known_hosts_path_cache = path;
    log_debug("KNOWN_HOSTS: Using path %s", g_known_hosts_path_cache);
  }
  return g_known_hosts_path_cache;
}

References get_config_dir(), log_debug, log_error, SAFE_FREE, SAFE_MALLOC, and safe_snprintf().

Referenced by add_known_host(), check_known_host_no_identity(), crypto_handshake_client_key_exchange(), display_mitm_warning(), prompt_unknown_host(), and remove_known_host().

gpg_agent_connect()

int gpg_agent_connect

(

void

)

#include <include/ascii-chat/crypto/gpg/agent.h>

Connect to gpg-agent.

Returns

Socket/pipe handle on success, -1 on error

Establishes connection to GPG agent using Assuan protocol. Connects to agent socket/pipe and performs initial handshake.

Note

Connection method:

• Unix: Connects to Unix domain socket (~/.gnupg/S.gpg-agent or GPG_AGENT_INFO)
• Windows: Connects to named pipe (\.\pipe\gpg-agent or from GPG_AGENT_INFO)

Socket location:

• Unix: $GPG_AGENT_INFO or ~/.gnupg/S.gpg-agent
• Windows: Named pipe from GPG_AGENT_INFO or default pipe

Assuan protocol: After connection, sends initial commands:

• Receives "OK Pleased to meet you" greeting
• No additional initialization needed for signing operations

Connection ownership: Caller must call gpg_agent_disconnect() when done. Failing to disconnect will leak socket handles.

Warning

Agent requirement: GPG agent must be running and accessible. Returns -1 if agent is not available (not running, wrong path, etc.).

Socket cleanup: Must call gpg_agent_disconnect() to close socket. Failing to do so will leak file descriptors/handles.

Definition at line 103 of file agent.c.

                            {
  char agent_path[PLATFORM_MAX_PATH_LENGTH];
  if (platform_get_gpg_agent_socket(agent_path, sizeof(agent_path)) != 0) {
    log_error("Failed to get GPG agent path");
    return -1;
  }
 
  log_debug("Connecting to GPG agent at: %s", agent_path);
 
  // Use platform abstraction for pipe/socket connection
  pipe_t pipe = platform_pipe_connect(agent_path);
  if (!platform_pipe_is_valid(pipe)) {
    log_error("Failed to connect to GPG agent");
    return -1;
  }
 
  // Read initial greeting
  char response[GPG_AGENT_MAX_RESPONSE];
  if (read_agent_line(pipe, response, sizeof(response), NULL) != 0) {
    log_error("Failed to read GPG agent greeting");
    platform_pipe_close(pipe);
    return -1;
  }
 
  if (!is_ok_response(response)) {
    log_error("Unexpected GPG agent greeting: %s", response);
    platform_pipe_close(pipe);
    return -1;
  }
 
  log_debug("Connected to GPG agent successfully");
 
  // Set loopback pinentry mode to avoid interactive prompts
  // This allows GPG agent to work in non-interactive environments
  if (send_agent_command(pipe, "OPTION pinentry-mode=loopback") != 0) {
    log_warn("Failed to set loopback pinentry mode (continuing anyway)");
  } else {
    // Read response for OPTION command
    if (read_agent_line(pipe, response, sizeof(response), NULL) != 0) {
      log_warn("Failed to read OPTION command response (continuing anyway)");
    } else if (is_ok_response(response)) {
      log_debug("Loopback pinentry mode enabled");
    } else {
      log_warn("Failed to enable loopback pinentry mode: %s (continuing anyway)", response);
    }
  }
 
  return (int)(intptr_t)pipe;
}

References GPG_AGENT_MAX_RESPONSE, log_debug, log_error, log_warn, PLATFORM_MAX_PATH_LENGTH, platform_pipe_close(), platform_pipe_connect(), and platform_pipe_is_valid().

Referenced by ed25519_sign_message(), gpg_agent_is_available(), and gpg_get_public_key().

gpg_agent_disconnect()

void gpg_agent_disconnect

(

int

sock

)

#include <include/ascii-chat/crypto/gpg/agent.h>

Disconnect from gpg-agent.

Parameters

sock	Socket/pipe handle from gpg_agent_connect()

Closes connection to GPG agent and releases socket resources. Safe to call with invalid socket (does nothing if sock < 0).

Note

Socket closure: Closes socket handle using platform-specific close function. On Unix, uses close(). On Windows, uses CloseHandle().

Assuan protocol: No goodbye message needed - just closes socket. GPG agent handles disconnections gracefully.

Safe disconnect: Function validates socket handle before closing. Safe to call with -1 or invalid handles.

Warning

Always call this after gpg_agent_connect() to avoid resource leaks.

Definition at line 153 of file agent.c.

                                             {
  if (handle_as_int >= 0) {
    pipe_t pipe = (pipe_t)(intptr_t)handle_as_int;
    send_agent_command(pipe, "BYE");
    platform_pipe_close(pipe);
  }
}

References platform_pipe_close().

Referenced by ed25519_sign_message(), gpg_agent_is_available(), and gpg_get_public_key().

gpg_agent_is_available()

bool gpg_agent_is_available

(

void

)

#include <include/ascii-chat/crypto/gpg/agent.h>

Check if GPG agent is available.

Returns

true if gpg-agent is running and accessible, false otherwise

Checks if GPG agent is running by attempting to connect and immediately disconnecting. Uses gpg_agent_connect() internally.

Note

Agent detection: Attempts actual connection to verify agent is running. Returns false if connection fails for any reason.

Platform differences:

• Unix: Checks for socket existence and accessibility (~/.gnupg/S.gpg-agent)
• Windows: Attempts to connect to named pipe

Connection test: Creates temporary connection and closes it immediately. Does not leave connection open.

Performance: Involves actual socket connection - may be slow if agent is not running. Consider caching result if calling frequently.

Warning

Agent may not be running: Function returns false if agent is not running, socket/pipe doesn't exist, or permissions prevent access.

Definition at line 344 of file agent.c.

                                  {
  int sock = gpg_agent_connect();
  if (sock < 0) {
    return false;
  }
  gpg_agent_disconnect(sock);
  return true;
}

References gpg_agent_connect(), and gpg_agent_disconnect().

gpg_agent_sign()

int gpg_agent_sign	(	int	sock,
		const char *	keygrip,
		const uint8_t *	message,
		size_t	message_len,
		uint8_t *	signature_out,
		size_t *	signature_len_out )

#include <include/ascii-chat/crypto/gpg/agent.h>

Sign a message using GPG agent.

Parameters

sock	Socket/pipe handle from gpg_agent_connect() (must be valid)
keygrip	GPG keygrip (40-char hex string, must not be NULL)
message	Message to sign (must not be NULL)
message_len	Message length (must be > 0)
signature_out	Output buffer for signature (must be >= 64 bytes for Ed25519)
signature_len_out	Output parameter for signature length (must not be NULL)

Returns

0 on success, -1 on error

Signs message using GPG agent Assuan protocol PKSIGN command. Key stays in GPG agent - private key never enters application memory.

Note

Assuan protocol commands:

1. RESET - Clear any previous state
2. SIGKEY <keygrip> - Select key to use for signing
3. SETHASH –hash=sha256 <hex_hash> - Set message hash (SHA-256 of message)
4. PKSIGN - Perform signature operation

Key selection: Uses keygrip to identify key in agent. Keygrip is 40-char hex string computed from public key material.

Hash algorithm: Uses SHA-256 hash of message for signing. GPG agent expects hex-encoded hash, not raw message.

Signature format: Returns raw Ed25519 signature (64 bytes). Format: R || S (32 bytes each) for Ed25519.

Error handling: Returns -1 on any error:

• Agent connection lost
• Key not found in agent (wrong keygrip)
• Signature operation failed
• Protocol error (malformed response)

Connection requirement: Requires active connection from gpg_agent_connect(). Does not create or close connection - caller manages connection lifecycle.

Warning

Agent connection: Requires valid socket from gpg_agent_connect(). Returns -1 if socket is invalid or connection is closed.

Key availability: Key must be in GPG agent and identified by keygrip. Returns -1 if key not found or keygrip is invalid.

Buffer size: signature_out must be at least 64 bytes for Ed25519. Function writes up to 64 bytes and sets signature_len_out accordingly.

Definition at line 161 of file agent.c.

                                                                      {
  if (handle_as_int < 0 || !keygrip || !message || !signature_out || !signature_len_out) {
    log_error("Invalid arguments");
    return -1;
  }
 
  pipe_t handle = (pipe_t)(intptr_t)handle_as_int;
  char response[GPG_AGENT_MAX_RESPONSE];
 
  // 1. Set the key to use (SIGKEY command)
  char sigkey_cmd[CRYPTO_GPG_AGENT_SIGKEY_CMD_BUFFER_SIZE];
  safe_snprintf(sigkey_cmd, sizeof(sigkey_cmd), "SIGKEY %s", keygrip);
  if (send_agent_command(handle, sigkey_cmd) != 0) {
    log_error("Failed to send SIGKEY command");
    return -1;
  }
 
  if (read_agent_line(handle, response, sizeof(response), NULL) != 0) {
    log_error("Failed to read SIGKEY response");
    return -1;
  }
 
  if (!is_ok_response(response)) {
    log_error("SIGKEY failed: %s", response);
    return -1;
  }
 
  // 2. For EdDSA/Ed25519, GPG agent requires SETHASH with a hash algorithm
  // GPG agent doesn't support --inquire for SETHASH - the command syntax is:
  //   SETHASH (--hash=<name>)|(<algonumber>) <hexstring>
  // For Ed25519, we hash the message with SHA512 (algo 10) first
 
  // Hash the message with SHA512 using libsodium
  uint8_t hash[crypto_hash_sha512_BYTES];
  crypto_hash_sha512(hash, message, message_len);
 
  // Build SETHASH command with SHA512 hash (algo 10)
  // Format: "SETHASH 10 <128 hex chars for 64-byte SHA512 hash>"
  char sethash_cmd[CRYPTO_GPG_AGENT_SETHASH_CMD_BUFFER_SIZE];
  int offset = safe_snprintf(sethash_cmd, sizeof(sethash_cmd), "SETHASH 10 ");
  for (size_t i = 0; i < crypto_hash_sha512_BYTES; i++) {
    offset += safe_snprintf(sethash_cmd + offset, sizeof(sethash_cmd) - (size_t)offset, "%02X", hash[i]);
  }
 
  log_debug("Sending SETHASH command with SHA512 hash");
  if (send_agent_command(handle, sethash_cmd) != 0) {
    log_error("Failed to send SETHASH command");
    return -1;
  }
 
  // Read SETHASH response
  if (read_agent_line(handle, response, sizeof(response), NULL) != 0) {
    log_error("Failed to read SETHASH response");
    return -1;
  }
 
  if (!is_ok_response(response)) {
    log_error("SETHASH failed: %s", response);
    return -1;
  }
 
  // 3. Request signature using PKSIGN
  if (send_agent_command(handle, "PKSIGN") != 0) {
    log_error("Failed to send PKSIGN command");
    return -1;
  }
 
  // Read response - skip status/error lines and wait for data line (D ...)
  // GPG agent sends informational ERR lines that are not fatal (e.g., "Not implemented")
  // Keep reading until we get the actual signature data
  bool found_data = false;
  size_t response_len = 0;
  for (int attempts = 0; attempts < 20; attempts++) {
    if (read_agent_line(handle, response, sizeof(response), &response_len) != 0) {
      log_error("Failed to read PKSIGN response");
      return -1;
    }
 
    log_debug("PKSIGN response line %d (%zu bytes)", attempts + 1, response_len);
 
    // Skip status lines (S INQUIRE_MAXLEN, etc)
    if (response[0] == 'S' && response[1] == ' ') {
      log_debug("Skipping PKSIGN status line: %s", response);
      continue;
    }
 
    // Skip informational ERR lines (GPG agent sends these even on success)
    // Common ERR codes: 67109141 (IPC cancelled), 67108933 (Not implemented)
    if (strncmp(response, "ERR", 3) == 0) {
      log_debug("Skipping PKSIGN error line (informational): %s", response);
      continue;
    }
 
    // Check if it's a data line (D followed by space)
    if (response[0] == 'D' && response[1] == ' ') {
      log_debug("Found signature data line");
      found_data = true;
      break;
    }
 
    // Check for OK (success without data would be unexpected)
    if (strncmp(response, "OK", 2) == 0) {
      log_warn("PKSIGN returned OK without data line");
      continue; // Keep trying in case D line follows
    }
 
    // Check if GPG agent is sending another INQUIRE (shouldn't happen)
    if (strncmp(response, "INQUIRE", 7) == 0) {
      log_error("Unexpected INQUIRE after PKSIGN: %s", response);
      return -1;
    }
 
    // Unknown response type
    log_warn("Unexpected PKSIGN response (attempt %d): %s", attempts + 1, response);
  }
 
  if (!found_data) {
    log_error("Expected D line from PKSIGN after %d attempts", 20);
    return -1;
  }
 
  // Assuan escapes binary bytes as %HH. Decode before reading canonical S-expression fields.
  uint8_t decoded[GPG_AGENT_MAX_RESPONSE];
  size_t decoded_len = 0;
  for (size_t input = 2; input < response_len; ++input) {
    if (decoded_len == sizeof(decoded)) {
      log_error("GPG agent signature response exceeds buffer");
      return -1;
    }
    if (response[input] == '%') {
      if (response_len - input < 3 || !isxdigit((unsigned char)response[input + 1]) ||
          !isxdigit((unsigned char)response[input + 2])) {
        log_error("Invalid percent escape in GPG agent signature");
        return -1;
      }
      char hex[3] = {response[input + 1], response[input + 2], 0};
      decoded[decoded_len++] = (uint8_t)strtoul(hex, NULL, 16);
      input += 2;
    } else {
      decoded[decoded_len++] = (uint8_t)response[input];
    }
  }
  static const char prefix[] = "(7:sig-val(5:eddsa(1:r32:";
  static const char separator[] = ")(1:s32:";
  static const char suffix[] = ")))";
  const size_t prefix_len = sizeof(prefix) - 1;
  const size_t separator_len = sizeof(separator) - 1;
  const size_t expected_len = prefix_len + 32 + separator_len + 32 + sizeof(suffix) - 1;
  if (decoded_len != expected_len || memcmp(decoded, prefix, prefix_len) != 0 ||
      memcmp(decoded + prefix_len + 32, separator, separator_len) != 0 ||
      memcmp(decoded + expected_len - (sizeof(suffix) - 1), suffix, sizeof(suffix) - 1) != 0) {
    log_error("Invalid Ed25519 signature S-expression from GPG agent");
    return -1;
  }
  memcpy(signature_out, decoded + prefix_len, ED25519_SIGNATURE_PART_SIZE);
  memcpy(signature_out + ED25519_SIGNATURE_PART_SIZE, decoded + prefix_len + 32 + separator_len,
         ED25519_SIGNATURE_PART_SIZE);
  *signature_len_out = 64;
 
  // DEBUG: Print signature in hex
  char sig_hex[HEX_STRING_SIZE_64];
  for (int i = 0; i < 64; i++) {
    safe_snprintf(sig_hex + i * 2, 3, "%02x", (unsigned char)signature_out[i]);
  }
  sig_hex[128] = '\0';
  log_debug("Extracted signature (64 bytes): %s", sig_hex);
 
  // Read final OK
  if (read_agent_line(handle, response, sizeof(response), &response_len) != 0) {
    log_error("Failed to read final PKSIGN response");
    return -1;
  }
 
  if (!is_ok_response(response)) {
    log_error("PKSIGN final response not OK: %s", response);
    return -1;
  }
 
  log_debug("Successfully signed message with GPG agent");
  return 0;
}

References CRYPTO_GPG_AGENT_SETHASH_CMD_BUFFER_SIZE, CRYPTO_GPG_AGENT_SIGKEY_CMD_BUFFER_SIZE, ED25519_SIGNATURE_PART_SIZE, GPG_AGENT_MAX_RESPONSE, HEX_STRING_SIZE_64, log_debug, log_error, log_warn, and safe_snprintf().

Referenced by ed25519_sign_message().

gpg_get_public_key()

int gpg_get_public_key	(	const char *	key_id,
		uint8_t *	public_key_out,
		char *	keygrip_out )

#include <include/ascii-chat/crypto/gpg/export.h>

Get public key from GPG keyring by key ID.

Parameters

key_id	GPG key ID (8/16/40-char hex string, must not be NULL)
public_key_out	Output buffer for 32-byte Ed25519 public key (must not be NULL)
keygrip_out	Output buffer for 40-char keygrip + null terminator (can be NULL if not needed)

Returns

0 on success, -1 on error

Retrieves Ed25519 public key from GPG keyring using gpg --export command. Parses OpenPGP packet format to extract raw 32-byte Ed25519 public key.

Note

Key ID format: Accepts short (8-char), long (16-char), or full (40-char) hex key IDs. Prefix "0x" is optional and will be added automatically if missing. Examples: "7FE90A79F2E80ED3", "0x7FE90A79F2E80ED3", "EDDAE1DA7360D7F4"

Export method: Uses gpg --export 0x<KEY_ID> to export public key. Output is in binary OpenPGP packet format, which is then parsed.

OpenPGP parsing: Parses OpenPGP packet structure to locate Ed25519 public key packet. Extracts 32-byte Ed25519 public key material from packet (algorithm ID 22). Skips 0x40 prefix byte if present (standard OpenPGP MPI format).

Keygrip extraction: If keygrip_out is not NULL, extracts keygrip using gpg --with-keygrip --list-keys. Keygrip is 40-char hex string that identifies key in GPG agent. Useful for subsequent gpg_agent_sign() operations.

Key validation: Validates that key is Ed25519 (algorithm 22 in OpenPGP). Returns error if key is RSA, ECDSA, or other unsupported algorithm.

Buffer requirements:

• public_key_out: Must be at least 32 bytes
• keygrip_out: Must be at least 41 bytes (40 hex chars + null terminator) if provided

Error conditions: Returns -1 if:

• Key ID not found in keyring
• Key is not Ed25519 (RSA/ECDSA not supported)
• gpg binary not found in PATH
• OpenPGP packet parsing fails
• Key export produces empty output

Warning

GPG binary required: Requires gpg binary in PATH. Returns -1 if GPG is not installed or not accessible.

Ed25519 only: Only Ed25519 keys are supported (OpenPGP algorithm 22). RSA/ECDSA keys will return error.

Key ID must exist: Key must exist in local GPG keyring. Returns -1 if key is not found (check with gpg --list-keys <KEY_ID>).

Definition at line 249 of file export.c.

                                                                                       {
  if (!key_id || !public_key_out) {
    log_error("Invalid arguments");
    return -1;
  }
 
  // SECURITY: Validate key_id to prevent command injection
  // GPG key IDs should be hexadecimal (0-9, a-f, A-F)
  if (!validate_shell_safe(key_id, NULL)) {
    log_error("Invalid GPG key ID format - contains unsafe characters: %s", key_id);
    return -1;
  }
 
  // Additional validation: ensure key_id is hex alphanumeric
  for (size_t i = 0; key_id[i] != '\0'; i++) {
    if (!isxdigit((unsigned char)key_id[i])) {
      log_error("Invalid GPG key ID format - must be hexadecimal: %s", key_id);
      return -1;
    }
  }
 
  // Escape key_id for safe use in shell command (single quotes)
  char escaped_key_id[BUFFER_SIZE_MEDIUM];
  if (!escape_shell_single_quotes(key_id, escaped_key_id, sizeof(escaped_key_id))) {
    log_error("Failed to escape GPG key ID for shell command");
    return -1;
  }
 
  // Use gpg to list the key and get the keygrip
  char cmd[BUFFER_SIZE_LARGE];
  safe_snprintf(cmd, sizeof(cmd), "gpg --list-keys --with-keygrip --with-colons 0x%s " PLATFORM_SHELL_NULL_REDIRECT,
                escaped_key_id);
 
  FILE *fp = NULL;
  if (platform_popen("gpg_export", cmd, "r", &fp) != ASCIICHAT_OK || !fp) {
    log_error("Failed to run gpg command - GPG may not be installed");
#ifdef _WIN32
    log_error("To install GPG on Windows, download Gpg4win from:");
    log_error("  https://www.gpg4win.org/download.html");
#elif defined(__APPLE__)
    log_error("To install GPG on macOS, use Homebrew:");
    log_error("  brew install gnupg");
#else
    log_error("To install GPG on Linux:");
    log_error("  Debian/Ubuntu: sudo apt-get install gnupg");
    log_error("  Fedora/RHEL:   sudo dnf install gnupg2");
    log_error("  Arch Linux:    sudo pacman -S gnupg");
    log_error("  Alpine Linux:  sudo apk add gnupg");
#endif
    return -1;
  }
 
  char line[BUFFER_SIZE_XLARGE];
  char found_keygrip[CRYPTO_GPG_EXPORT_FOUND_KEYGRIP_BUFFER_SIZE] = {0};
  bool found_key = false;
 
  // Parse gpg output
  // Format: pub:..., grp:::::::::<keygrip>:
  while (fgets(line, sizeof(line), fp)) {
    if (strncmp(line, "pub:", 4) == 0) {
      // Found the public key line
      found_key = true;
    } else if (found_key && strncmp(line, "grp:", 4) == 0) {
      // Extract keygrip using PCRE2 regex
      // Format: grp:::::::::D52FF935FBA59609EE65E1685287828242A1EA1A:
      char *keygrip_extracted = NULL;
 
      if (crypto_regex_extract_gpg_keygrip(line, &keygrip_extracted)) {
        // Successfully extracted keygrip
        SAFE_STRNCPY(found_keygrip, keygrip_extracted, sizeof(found_keygrip));
        if (keygrip_out) {
          SAFE_STRNCPY(keygrip_out, found_keygrip, 41);
        }
        SAFE_FREE(keygrip_extracted);
      } else {
        // Fallback to manual parsing if regex fails
        const char *grp_start = line + 4;
        int colon_count = 0;
        while (*grp_start && colon_count < 8) {
          if (*grp_start == ':') {
            colon_count++;
          }
          grp_start++;
        }
 
        if (colon_count == 8) {
          const char *grp_end = strchr(grp_start, ':');
          if (grp_end) {
            size_t grp_len = grp_end - grp_start;
            if (grp_len < sizeof(found_keygrip)) {
              memcpy(found_keygrip, grp_start, grp_len);
              found_keygrip[grp_len] = '\0';
 
              if (keygrip_out) {
                SAFE_STRNCPY(keygrip_out, found_keygrip, 41);
              }
            }
          }
        }
      }
      break;
    }
  }
 
  platform_pclose(&fp);
 
  if (!found_key || strlen(found_keygrip) == 0) {
    log_error("Could not find GPG key with ID: %s", key_id);
    return -1;
  }
 
  log_debug("Found keygrip for key %s: %s", key_id, found_keygrip);
 
  // Try to use GPG agent API to read the public key directly via READKEY command
  int agent_sock = gpg_agent_connect();
  if (agent_sock < 0) {
    log_debug("GPG agent not available, falling back to gpg --export for public key extraction");
    // Fallback: Use gpg --export to get the public key
    int export_result = gpg_export_public_key(key_id, public_key_out);
    if (export_result == 0) {
      log_debug("Successfully extracted public key using fallback method");
    } else {
      log_error("Fallback public key extraction failed for key ID: %s", key_id);
    }
    return export_result;
  }
 
  // Send READKEY command with keygrip to get the public key S-expression
  char readkey_cmd[BUFFER_SIZE_SMALL];
  safe_snprintf(readkey_cmd, sizeof(readkey_cmd), "READKEY %s\n", found_keygrip);
 
  // Cast agent_sock back to pipe_t (gpg_agent_connect returns pipe_t cast to int for portability)
  pipe_t agent_pipe = (pipe_t)(intptr_t)agent_sock;
  ssize_t bytes_written = platform_pipe_write(agent_pipe, (const unsigned char *)readkey_cmd, strlen(readkey_cmd));
  if (bytes_written != (ssize_t)strlen(readkey_cmd)) {
    log_error("Failed to send READKEY command to GPG agent");
    gpg_agent_disconnect(agent_sock);
    return -1;
  }
 
  // Read the response (public key S-expression)
  char response[BUFFER_SIZE_XXXLARGE];
  memset(response, 0, sizeof(response));
  ssize_t bytes_read = platform_pipe_read(agent_pipe, (unsigned char *)response, sizeof(response) - 1);
 
  gpg_agent_disconnect(agent_sock);
 
  if (bytes_read <= 0) {
    log_error("Failed to read READKEY response from GPG agent");
    return -1;
  }
 
  // Assuan data lines escape %, CR and LF, including bytes inside the S-expression.
  size_t decoded = 0;
  for (size_t i = 0; i < (size_t)bytes_read; ++i) {
    if (response[i] == '%' && i + 2 < (size_t)bytes_read && isxdigit((unsigned char)response[i + 1]) &&
        isxdigit((unsigned char)response[i + 2])) {
      unsigned char high = (unsigned char)tolower((unsigned char)response[i + 1]);
      unsigned char low = (unsigned char)tolower((unsigned char)response[i + 2]);
      high = high <= '9' ? high - '0' : high - 'a' + 10;
      low = low <= '9' ? low - '0' : low - 'a' + 10;
      response[decoded++] = (char)((high << 4) | low);
      i += 2;
    } else {
      response[decoded++] = response[i];
    }
  }
  response[decoded] = '\0';
 
  // Parse the S-expression to extract Ed25519 public key (q value)
  // GPG agent returns binary S-expressions in format: (1:q<length>:<binary-data>)
  // Example: (1:q33:<33-bytes>) where first byte is 0x40 (Ed25519 prefix), then 32-byte key
  const char *q_marker = strstr(response, "(1:q");
  if (!q_marker) {
    log_warn("Failed to find public key (1:q) in GPG agent READKEY response, trying gpg --export fallback");
    log_debug("Response was: %.*s", (int)(bytes_read < 200 ? bytes_read : 200), response);
    gpg_agent_disconnect(agent_sock);
 
    // Fallback: Use gpg --export for public-only keys
    int export_result = gpg_export_public_key(key_id, public_key_out);
    if (export_result == 0) {
      log_debug("Successfully extracted public key using gpg --export fallback");
    } else {
      log_error("Fallback public key extraction failed for key ID: %s", key_id);
    }
    return export_result;
  }
 
  // Skip "(1:q" to get to the length field
  const char *len_start = q_marker + 4;
 
  // Parse the length (e.g., "33:")
  char *colon = strchr(len_start, ':');
  if (!colon) {
    log_error("Malformed S-expression: missing colon after length");
    return -1;
  }
 
  size_t key_len = strtoul(len_start, NULL, 10);
  if (key_len != 33) {
    log_error("Unexpected Ed25519 public key length: %zu bytes (expected 33)", key_len);
    return -1;
  }
 
  // Skip the colon to get to the binary data
  const unsigned char *binary_start = (const unsigned char *)(colon + 1);
  if ((size_t)(binary_start - (const unsigned char *)response) + key_len > decoded) {
    log_error("Truncated Ed25519 public key in GPG agent response");
    return -1;
  }
 
  // Ed25519 public keys in GPG format have a 0x40 prefix byte, then 32 bytes of actual key
  if (binary_start[0] != 0x40) {
    log_error("Invalid Ed25519 public key prefix: 0x%02x (expected 0x40)", binary_start[0]);
    return -1;
  }
 
  // Copy the 32-byte public key (skip the 0x40 prefix)
  memcpy(public_key_out, binary_start + 1, ED25519_PUBLIC_KEY_SIZE);
 
  log_debug("Extracted Ed25519 public key from GPG agent via READKEY command");
  return 0;
}

References ASCIICHAT_OK, BUFFER_SIZE_LARGE, BUFFER_SIZE_MEDIUM, BUFFER_SIZE_SMALL, BUFFER_SIZE_XLARGE, BUFFER_SIZE_XXXLARGE, bytes_written, CRYPTO_GPG_EXPORT_FOUND_KEYGRIP_BUFFER_SIZE, crypto_regex_extract_gpg_keygrip(), ED25519_PUBLIC_KEY_SIZE, escape_shell_single_quotes(), gpg_agent_connect(), gpg_agent_disconnect(), log_debug, log_error, log_warn, platform_pclose(), platform_pipe_read(), platform_pipe_write(), platform_popen(), SAFE_FREE, safe_snprintf(), and SAFE_STRNCPY.

Referenced by extract_ed25519_from_gpg(), and parse_private_key().

gpg_sign_detached_ed25519()

int gpg_sign_detached_ed25519	(	const char *	key_id,
		const uint8_t *	message,
		size_t	message_len,
		uint8_t	signature_out[ED25519_SIGNATURE_SIZE] )

#include <include/ascii-chat/crypto/gpg/signing.h>

Sign message with GPG and extract raw Ed25519 signature.

Parameters

key_id	GPG key ID (8/16/40-char hex string, must not be NULL)
message	Message to sign (must not be NULL)
message_len	Message length in bytes (must be > 0)
signature_out	Output buffer for 64-byte Ed25519 signature (must not be NULL)

Returns

0 on success, -1 on error

Signs message using gpg --detach-sign, then extracts raw 64-byte Ed25519 signature from OpenPGP packet format. Returns signature in libsodium-compatible format (R||S).

Note

Key ID format: Accepts short (8-char), long (16-char), or full (40-char) hex key IDs. Prefix "0x" is optional and will be added automatically if missing.

Signing method: Uses gpg --detach-sign --local-user 0x<KEY_ID> command. Then parses OpenPGP output to extract raw signature bytes.

OpenPGP parsing: Parses binary OpenPGP signature packet to locate signature data. Extracts raw Ed25519 signature (R||S format, 64 bytes total). Skips packet headers and metadata to get pure signature bytes.

Output format: Returns raw Ed25519 signature in libsodium format. Format: R || S (32 bytes R + 32 bytes S = 64 bytes total). Compatible with crypto_sign_verify_detached() from libsodium.

Fixed length: Ed25519 signatures are always exactly 64 bytes. No length parameter needed - signature_out is always fully written.

Use case: Prefer this over gpg_sign_with_key() when you need raw signature. Useful for protocol implementations that expect raw Ed25519 signatures rather than OpenPGP-wrapped signatures.

Comparison with gpg_sign_with_key():

• gpg_sign_with_key(): Returns full OpenPGP packet (~150-200 bytes)
• gpg_sign_detached_ed25519(): Returns raw Ed25519 signature (64 bytes)

Key passphrase handling:

• If key is encrypted, GPG may prompt for passphrase interactively
• Use gpg-agent for password-free signing (recommended)
• Or set $ASCII_CHAT_KEY_PASSWORD environment variable

Buffer requirements:

• signature_out: Must be exactly 64 bytes (Ed25519 signature size)

Error conditions: Returns -1 if:

• Key ID not found in keyring
• Key is not Ed25519 (RSA/ECDSA not supported)
• gpg binary not found in PATH
• Signing operation fails (wrong passphrase, key expired, etc.)
• OpenPGP packet parsing fails
• Signature extraction fails (unexpected packet format)

Warning

GPG binary required: Requires gpg binary in PATH. Returns -1 if GPG is not installed or not accessible.

Ed25519 only: Only Ed25519 keys are supported (OpenPGP algorithm 22). RSA/ECDSA keys will return error.

Buffer size: signature_out must be exactly 64 bytes. Function always writes exactly 64 bytes on success.

Key must exist: Key must exist in local GPG keyring. Returns -1 if key is not found (check with gpg --list-keys <KEY_ID>).

Definition at line 145 of file signing.c.

                                                                             {
  log_debug("Signing with key ID %s (fallback mode)", key_id);
 
  // Get OpenPGP signature packet from gpg --detach-sign
  uint8_t openpgp_signature[GPG_SIGNATURE_PACKET_CAPACITY];
  size_t openpgp_len = 0;
 
  int result = gpg_sign_with_key(key_id, message, message_len, openpgp_signature, &openpgp_len);
  if (result != 0) {
    log_error("GPG detached signing failed for key %s", key_id);
    return -1;
  }
 
  log_debug("gpg_sign_with_key returned %zu bytes", openpgp_len);
 
  if (openpgp_len < 10) {
    log_error("GPG signature too short: %zu bytes", openpgp_len);
    return -1;
  }
 
  log_debug("Parsing OpenPGP signature packet (%zu bytes) to extract Ed25519 signature", openpgp_len);
 
  // Parse OpenPGP signature packet format
  // Reference: RFC 4880 Section 5.2 (Signature Packet)
  // Format: [header][version][type][algo][hash-algo][...][signature-data]
  size_t offset = 0;
 
  // Parse packet header
  uint8_t tag = openpgp_signature[offset++];
  size_t packet_len = 0;
 
  if ((tag & 0x40) == 0) {
    // Old format packet
    uint8_t length_type = tag & 0x03;
    if (length_type == 0) {
      packet_len = openpgp_signature[offset++];
    } else if (length_type == 1) {
      packet_len = (openpgp_signature[offset] << 8) | openpgp_signature[offset + 1];
      offset += 2;
    } else if (length_type == 2) {
      packet_len = (openpgp_signature[offset] << 24) | (openpgp_signature[offset + 1] << 16) |
                   (openpgp_signature[offset + 2] << 8) | openpgp_signature[offset + 3];
      offset += 4;
    } else {
      log_error("Unsupported old-format packet length type: %d", length_type);
      return -1;
    }
  } else {
    // New format packet
    uint8_t length_byte = openpgp_signature[offset++];
    if (length_byte < 192) {
      packet_len = length_byte;
    } else if (length_byte < 224) {
      packet_len = ((length_byte - 192) << 8) + openpgp_signature[offset++] + 192;
    } else if (length_byte == 255) {
      packet_len = (openpgp_signature[offset] << 24) | (openpgp_signature[offset + 1] << 16) |
                   (openpgp_signature[offset + 2] << 8) | openpgp_signature[offset + 3];
      offset += 4;
    } else {
      log_error("Unsupported new-format packet length encoding: %d", length_byte);
      return -1;
    }
  }
 
  if (offset + packet_len > openpgp_len) {
    log_error("Packet length exceeds signature size: %zu + %zu > %zu", offset, packet_len, openpgp_len);
    return -1;
  }
 
  log_debug("Signature packet: offset=%zu, length=%zu", offset, packet_len);
 
  // Parse signature packet body
  // Skip: version (1), sig_type (1), pub_algo (1), hash_algo (1)
  if (offset + 4 > openpgp_len) {
    log_error("Signature packet too short for header");
    return -1;
  }
 
  uint8_t version = openpgp_signature[offset++];
  uint8_t sig_type = openpgp_signature[offset++];
  uint8_t pub_algo = openpgp_signature[offset++];
  uint8_t hash_algo = openpgp_signature[offset++];
 
  log_debug("Signature: version=%d, type=%d, algo=%d, hash=%d", version, sig_type, pub_algo, hash_algo);
 
  // Verify algorithm is Ed25519 (22 = EdDSA)
  if (pub_algo != 22) {
    log_error("Expected EdDSA algorithm (22), got %d", pub_algo);
    return -1;
  }
 
  // For v4 signatures: skip hashed subpackets
  if (version == 4) {
    if (offset + 2 > openpgp_len) {
      log_error("Cannot read hashed subpacket length");
      return -1;
    }
    uint16_t hashed_len = (openpgp_signature[offset] << 8) | openpgp_signature[offset + 1];
    offset += 2;
    offset += hashed_len; // Skip hashed subpackets
 
    if (offset + 2 > openpgp_len) {
      log_error("Cannot read unhashed subpacket length");
      return -1;
    }
    uint16_t unhashed_len = (openpgp_signature[offset] << 8) | openpgp_signature[offset + 1];
    offset += 2;
    offset += unhashed_len; // Skip unhashed subpackets
 
    // Skip left 16 bits of signed hash value
    if (offset + 2 > openpgp_len) {
      log_error("Cannot read hash left bits");
      return -1;
    }
    offset += 2;
  }
 
  // Now we're at the signature data (MPI format for Ed25519)
  // Ed25519 signature is: r (32 bytes) || s (32 bytes) = 64 bytes total
  // In OpenPGP, each MPI is encoded as: [2-byte bit count][data]
 
  if (offset + 2 > openpgp_len) {
    log_error("Cannot read MPI bit count for R");
    return -1;
  }
 
  uint16_t r_bits = (openpgp_signature[offset] << 8) | openpgp_signature[offset + 1];
  offset += 2;
  size_t r_bytes = (r_bits + 7) / 8;
 
  log_debug("R: %d bits (%zu bytes)", r_bits, r_bytes);
 
  if (r_bytes == 0 || r_bytes > 32) {
    log_error("Expected a 1-32 byte R value, got %zu bytes", r_bytes);
    return -1;
  }
 
  if (offset + r_bytes > openpgp_len) {
    log_error("R value exceeds packet size");
    return -1;
  }
 
  // OpenPGP MPIs omit leading zero bytes; raw signatures retain fixed-width components.
  memset(signature_out, 0, ED25519_SIGNATURE_SIZE);
  memcpy(signature_out + 32 - r_bytes, &openpgp_signature[offset], r_bytes);
  offset += r_bytes;
 
  // Read S value
  if (offset + 2 > openpgp_len) {
    log_error("Cannot read MPI bit count for S");
    return -1;
  }
 
  uint16_t s_bits = (openpgp_signature[offset] << 8) | openpgp_signature[offset + 1];
  offset += 2;
  size_t s_bytes = (s_bits + 7) / 8;
 
  log_debug("S: %d bits (%zu bytes)", s_bits, s_bytes);
 
  if (s_bytes == 0 || s_bytes > 32) {
    log_error("Expected a 1-32 byte S value, got %zu bytes", s_bytes);
    return -1;
  }
 
  if (offset + s_bytes > openpgp_len) {
    log_error("S value exceeds packet size");
    return -1;
  }
 
  memcpy(signature_out + 64 - s_bytes, &openpgp_signature[offset], s_bytes);
 
  log_debug("Successfully extracted 64-byte Ed25519 signature from OpenPGP packet");
 
  // Debug: Log signature components
  char hex_r[HEX_STRING_SIZE_32], hex_s[CRYPTO_GPG_SIGNING_HEX_S_BUFFER_SIZE];
  for (int i = 0; i < 32; i++) {
    safe_snprintf(hex_r + i * 2, 3, "%02x", signature_out[i]);
    safe_snprintf(hex_s + i * 2, 3, "%02x", signature_out[i + 32]);
  }
  hex_r[64] = hex_s[64] = '\0';
  log_debug("Signature R (first 32 bytes): %s", hex_r);
  log_debug("Signature S (last 32 bytes): %s", hex_s);
 
  return 0;
}

References CRYPTO_GPG_SIGNING_HEX_S_BUFFER_SIZE, ED25519_SIGNATURE_SIZE, gpg_sign_with_key(), GPG_SIGNATURE_PACKET_CAPACITY, HEX_STRING_SIZE_32, log_debug, log_error, and safe_snprintf().

Referenced by ed25519_sign_message().

gpg_sign_with_key()

int gpg_sign_with_key	(	const char *	key_id,
		const uint8_t *	message,
		size_t	message_len,
		uint8_t *	signature_out,
		size_t *	signature_len_out )

#include <include/ascii-chat/crypto/gpg/signing.h>

Sign a message using GPG key and return OpenPGP signature.

Parameters

key_id	GPG key ID (8/16/40-char hex string, must not be NULL)
message	Message to sign (must not be NULL)
message_len	Message length in bytes (must be > 0)
signature_out	Output buffer for OpenPGP signature (must be >= 512 bytes)
signature_len_out	Output parameter for actual signature length (must not be NULL)

Returns

0 on success, -1 on error

Signs message using gpg --detach-sign and returns full OpenPGP signature packet. Signature is in binary OpenPGP format and includes packet headers.

Note

Key ID format: Accepts short (8-char), long (16-char), or full (40-char) hex key IDs. Prefix "0x" is optional and will be added automatically if missing. Examples: "7FE90A79F2E80ED3", "0x7FE90A79F2E80ED3", "EDDAE1DA7360D7F4"

Signing method: Uses gpg --detach-sign --local-user 0x<KEY_ID> command. Creates detached signature (signature separate from message).

Output format: Returns binary OpenPGP signature packet (RFC 4880). Signature includes packet headers and metadata beyond raw signature data. Typical size: 150-200 bytes for Ed25519 signatures.

Variable length: OpenPGP format means signature length varies. Always check signature_len_out to know actual signature length. Buffer must be at least 512 bytes to accommodate various key types.

GPG interaction: Executes gpg as subprocess and reads output. Signature is read from GPG's stdout in binary format.

Key passphrase handling:

• If key is encrypted, GPG may prompt for passphrase interactively
• Use gpg-agent for password-free signing (recommended)
• Or set $ASCII_CHAT_KEY_PASSWORD environment variable

Buffer requirements:

• signature_out: Must be at least 512 bytes
• signature_len_out: Will be set to actual signature length (typically 150-200 bytes)

Error conditions: Returns -1 if:

• Key ID not found in keyring
• Key is not Ed25519 (RSA/ECDSA not supported)
• gpg binary not found in PATH
• Signing operation fails (wrong passphrase, key expired, etc.)
• Output buffer too small (< 512 bytes)

Warning

GPG binary required: Requires gpg binary in PATH. Returns -1 if GPG is not installed or not accessible.

Ed25519 only: Only Ed25519 keys are supported (OpenPGP algorithm 22). RSA/ECDSA keys will return error.

Buffer size: signature_out must be at least 512 bytes. Smaller buffers may cause buffer overflow or signature truncation.

Key must exist: Key must exist in local GPG keyring. Returns -1 if key is not found (check with gpg --list-keys <KEY_ID>).

Sign a message using GPG key and return OpenPGP signature.

This function uses gpg --detach-sign which internally uses gpg-agent, so no passphrase prompt if the key is cached in the agent.

Parameters

key_id	GPG key ID (e.g., "7FE90A79F2E80ED3")
message	Message to sign
message_len	Message length
signature_out	Output buffer for signature (caller must provide at least 512 bytes)
signature_len_out	Actual signature length written

Returns

0 on success, -1 on error

Definition at line 46 of file signing.c.

                                                 {
  if (!key_id || !message || message_len == 0 || !signature_out || !signature_len_out) {
    log_error("Invalid parameters");
    return -1;
  }
 
  char msg_path[PLATFORM_MAX_PATH_LENGTH];
  char sig_path[PLATFORM_MAX_PATH_LENGTH];
  int msg_fd = -1;
  int sig_fd = -1;
  int result = -1;
 
  // Create temp files using platform abstraction
  if (platform_create_temp_file(msg_path, sizeof(msg_path), "asciichat_msg", &msg_fd) != 0) {
    log_error("Failed to create temp message file");
    return -1;
  }
 
  if (platform_create_temp_file(sig_path, sizeof(sig_path), "asciichat_sig", &sig_fd) != 0) {
    log_error("Failed to create temp signature file");
    platform_delete_temp_file(msg_path);
    return -1;
  }
 
  // Close signature file descriptor (will be created by gpg)
  if (sig_fd >= 0) {
    close(sig_fd);
  }
  platform_delete_temp_file(sig_path); // Remove it so gpg can create it fresh
 
  // Write message to temp file
  ssize_t written = write(msg_fd, message, message_len);
  close(msg_fd);
  msg_fd = -1;
 
  if (written != (ssize_t)message_len) {
    log_error("Failed to write message to temp file");
    goto cleanup;
  }
 
  // Escape key ID for shell command (prevent injection)
  char escaped_key_id[CRYPTO_GPG_SIGNING_ESCAPED_KEY_ID_BUFFER_SIZE];
  if (!escape_path_for_shell(key_id, escaped_key_id, sizeof(escaped_key_id))) {
    log_error("Failed to escape GPG key ID for shell command");
    goto cleanup;
  }
 
  // Call gpg --detach-sign
  // Use gpg with --detach-sign and --output for safe subprocess execution
  const char *argv[] = {"gpg", "--local-user", escaped_key_id, "--detach-sign", "--output", sig_path, msg_path, NULL};
 
  // Note: Don't log the full command as it may contain sensitive key material
  log_debug("Signing with GPG key 0x%s", escaped_key_id);
  int status = 0;
  LOG_IO("gpg", { status = platform_execute_subprocess("gpg", argv, NULL, 0, NULL, NULL); });
  if (status != 0) {
    log_error("GPG signing failed (exit code %d)", status);
    goto cleanup;
  }
 
  // Read signature file
  FILE *sig_fp = platform_fopen("file_stream", sig_path, "rb");
  if (!sig_fp) {
    log_error("Failed to open signature file: %s", SAFE_STRERROR(errno));
    goto cleanup;
  }
 
  fseek(sig_fp, 0, SEEK_END);
  long sig_size = ftell(sig_fp);
  fseek(sig_fp, 0, SEEK_SET);
 
  if (sig_size <= 0 || sig_size > 512) {
    log_error("Invalid signature size: %ld bytes", sig_size);
    fclose(sig_fp);
    goto cleanup;
  }
 
  size_t bytes_read = fread(signature_out, 1, sig_size, sig_fp);
  fclose(sig_fp);
 
  if (bytes_read != (size_t)sig_size) {
    log_error("Failed to read signature file");
    goto cleanup;
  }
 
  *signature_len_out = sig_size;
  log_debug("GPG signature created successfully (%zu bytes)", *signature_len_out);
  result = 0;
 
cleanup:
  if (msg_fd >= 0) {
    close(msg_fd);
  }
  platform_delete_temp_file(msg_path);
  platform_delete_temp_file(sig_path);
  return result;
}

References CRYPTO_GPG_SIGNING_ESCAPED_KEY_ID_BUFFER_SIZE, errno, escape_path_for_shell(), log_debug, log_error, LOG_IO, platform_execute_subprocess(), PLATFORM_MAX_PATH_LENGTH, and SAFE_STRERROR.

Referenced by gpg_sign_detached_ed25519(), and gpg_verify_detached_ed25519().

gpg_verify_detached_ed25519()

int gpg_verify_detached_ed25519	(	const char *	key_id,
		const uint8_t *	message,
		size_t	message_len,
		const uint8_t	signature[ED25519_SIGNATURE_SIZE] )

#include <include/ascii-chat/crypto/gpg/verification.h>

Verify Ed25519 signature using GPG binary.

Parameters

key_id	GPG key ID to use for verification (8/16/40-char hex, must not be NULL)
message	Message that was signed (must not be NULL)
message_len	Message length in bytes (must be > 0)
signature	64-byte Ed25519 signature (must not be NULL)

Returns

0 on success (valid signature), -1 on error (invalid signature or error)

Verifies raw Ed25519 signature using gpg --verify command. Converts raw signature to OpenPGP format, then uses GPG binary for verification.

Note

Key ID format: Accepts short (8-char), long (16-char), or full (40-char) hex key IDs. Prefix "0x" is optional and will be added automatically if missing. Examples: "7FE90A79F2E80ED3", "0x7FE90A79F2E80ED3", "EDDAE1DA7360D7F4"

Verification method: Uses gpg --verify command on converted OpenPGP signature. Checks both cryptographic validity and key trust status.

Signature format: Input must be raw 64-byte Ed25519 signature (R||S). Function internally converts to OpenPGP format for GPG binary. Not compatible with OpenPGP-wrapped signatures (use gpg_verify_signature_with_binary()).

Key trust checking: GPG binary checks key trust and expiry. Verification fails if key is expired, revoked, or untrusted.

Public key requirement: Key must be in GPG keyring for verification. Import public key first with gpg --import <public_key_file>.

Return value interpretation:

• 0: Signature is cryptographically valid and key is trusted
• -1: Signature invalid, key not found, key untrusted, or other error

Error conditions: Returns -1 if:

• Signature cryptographically invalid
• Key ID not found in keyring
• Key is expired or revoked
• Key is not trusted (not in web of trust)
• gpg binary not found in PATH
• OpenPGP conversion fails

Warning

GPG binary required: Requires gpg binary in PATH. Returns -1 if GPG is not installed or not accessible.

Ed25519 only: Only Ed25519 signatures are supported (OpenPGP algorithm 22). RSA/ECDSA signatures will return error.

Key must be imported: Public key must exist in GPG keyring. Returns -1 if key is not found (import with gpg --import).

Trust required: GPG checks key trust status. Verification may fail if key is not in web of trust.

Definition at line 37 of file verification.c.

                                                                                 {
  // Note: We don't use the raw signature parameter directly.
  // Instead, we regenerate the OpenPGP signature using GPG (Ed25519 is deterministic).
  (void)signature;
 
  log_debug("Verifying signature with key ID %s using gpg --verify", key_id);
 
  // To verify with GPG, we need to:
  // 1. Reconstruct the OpenPGP signature packet from the raw R||S signature
  // 2. Write message and signature to temp files
  // 3. Call gpg --verify
 
  // First, reconstruct OpenPGP signature by signing the same message
  // Since Ed25519 is deterministic, we should get the same OpenPGP packet
  uint8_t openpgp_signature[GPG_SIGNATURE_PACKET_CAPACITY];
  size_t openpgp_len = 0;
 
  int sign_result = gpg_sign_with_key(key_id, message, message_len, openpgp_signature, &openpgp_len);
  if (sign_result != 0) {
    log_error("Failed to create reference signature for verification");
    return -1;
  }
 
  // Now verify using gpg --verify
  char msg_path[PLATFORM_MAX_PATH_LENGTH];
  char sig_path[PLATFORM_MAX_PATH_LENGTH];
  int msg_fd = -1;
  int sig_fd = -1;
 
  if (platform_create_temp_file(msg_path, sizeof(msg_path), "gpg_verify_msg", &msg_fd) != 0) {
    log_error("Failed to create temporary message file");
    return -1;
  }
 
  if (platform_create_temp_file(sig_path, sizeof(sig_path), "gpg_verify_sig", &sig_fd) != 0) {
    platform_delete_temp_file(msg_path);
    log_error("Failed to create temporary signature file");
    return -1;
  }
 
  // Write message
  if (write(msg_fd, message, message_len) != (ssize_t)message_len) {
    log_error("Failed to write message to temp file");
    close(msg_fd);
    close(sig_fd);
    platform_delete_temp_file(msg_path);
    platform_delete_temp_file(sig_path);
    return -1;
  }
  close(msg_fd);
 
  // Write OpenPGP signature
  if (write(sig_fd, openpgp_signature, openpgp_len) != (ssize_t)openpgp_len) {
    log_error("Failed to write signature to temp file");
    close(sig_fd);
    platform_delete_temp_file(msg_path);
    platform_delete_temp_file(sig_path);
    return -1;
  }
  close(sig_fd);
 
  // Call gpg --verify
  char cmd[CRYPTO_GPG_VERIFICATION_CMD_BUFFER_SIZE];
  safe_snprintf(cmd, sizeof(cmd), "gpg --verify '%s' '%s' 2>&1", sig_path, msg_path);
  log_debug("Running: %s", cmd);
 
  FILE *fp;
  platform_popen("gpg_verify", cmd, "r", &fp);
  if (!fp) {
    log_error("Failed to run gpg --verify");
    platform_unlink(msg_path);
    platform_unlink(sig_path);
    return -1;
  }
 
  char output[CRYPTO_GPG_VERIFICATION_OUTPUT_BUFFER_SIZE] = {0};
  size_t output_len = fread(output, 1, sizeof(output) - 1, fp);
  int exit_code = platform_pclose(&fp);
 
  // Cleanup temp files
  platform_delete_temp_file(msg_path);
  platform_delete_temp_file(sig_path);
 
  if (exit_code == 0) {
    log_debug("GPG signature verification PASSED");
    return 0;
  } else {
    log_error("GPG signature verification FAILED (exit code %d)", exit_code);
    if (output_len > 0) {
      log_debug("GPG output: %s", output);
    }
    return -1;
  }
}

References CRYPTO_GPG_VERIFICATION_CMD_BUFFER_SIZE, CRYPTO_GPG_VERIFICATION_OUTPUT_BUFFER_SIZE, ED25519_SIGNATURE_SIZE, gpg_sign_with_key(), GPG_SIGNATURE_PACKET_CAPACITY, log_debug, log_error, PLATFORM_MAX_PATH_LENGTH, platform_pclose(), platform_popen(), and safe_snprintf().

Referenced by ed25519_verify_signature().

gpg_verify_signature()

int gpg_verify_signature	(	const uint8_t *	public_key,
		const uint8_t *	message,
		size_t	message_len,
		const uint8_t *	signature )

#include <include/ascii-chat/crypto/gpg/verification.h>

Verify Ed25519 signature using libgcrypt (no GPG binary required).

Parameters

public_key	32-byte Ed25519 public key (must not be NULL)
message	Message that was signed (must not be NULL)
message_len	Message length in bytes (must be > 0)
signature	64-byte Ed25519 signature (must not be NULL)

Returns

0 on success (valid signature), -1 on error (invalid signature or error)

Verifies Ed25519 signature directly using libgcrypt cryptographic library. Does not require GPG binary - performs pure cryptographic verification.

Note

Verification method: Uses libgcrypt's gcry_pk_verify() for Ed25519. Pure cryptographic verification - no key trust or expiry checking.

No GPG required: Works without GPG binary installed. Only requires libgcrypt library (linked during build).

Public key format: Accepts raw 32-byte Ed25519 public key. Can be extracted from GPG keyring using gpg_get_public_key().

Signature format: Input must be raw 64-byte Ed25519 signature (R||S). Compatible with signatures from gpg_sign_detached_ed25519(). Not compatible with OpenPGP-wrapped signatures.

No trust checking: Only verifies cryptographic signature validity. Does not check key expiry, revocation, or trust status. Use gpg_verify_detached_ed25519() if trust checking is needed.

Performance: Faster than GPG binary verification (no subprocess spawning). Suitable for high-frequency verification operations.

Use case: Prefer this when:

• You have raw public key (not just key ID)
• You don't need key trust/expiry checking
• You want faster verification (no subprocess)
• GPG binary may not be installed

Return value interpretation:

• 0: Signature is cryptographically valid for given public key
• -1: Signature invalid or verification error

Buffer requirements:

• public_key: Must be exactly 32 bytes (Ed25519 public key)
• signature: Must be exactly 64 bytes (Ed25519 signature)

Error conditions: Returns -1 if:

• Signature cryptographically invalid
• libgcrypt initialization fails
• Public key format invalid
• Signature format invalid

Warning

Ed25519 only: Only Ed25519 signatures are supported. Other key types will cause libgcrypt errors.

No trust checking: Does not verify key trust, expiry, or revocation. Only checks cryptographic signature validity.

Buffer sizes: public_key must be 32 bytes, signature must be 64 bytes. Other sizes will cause verification to fail.

Definition at line 133 of file verification.c.

                                                   {
#ifdef HAVE_LIBGCRYPT
  gcry_error_t err;
  gcry_sexp_t s_pubkey = NULL;
  gcry_sexp_t s_sig = NULL;
  gcry_sexp_t s_data = NULL;
 
  // Initialize libgcrypt if not already done
  if (!gcry_control(GCRYCTL_INITIALIZATION_FINISHED_P)) {
    gcry_check_version(NULL);
    gcry_control(GCRYCTL_DISABLE_SECMEM, 0);
    gcry_control(GCRYCTL_INITIALIZATION_FINISHED, 0);
  }
 
  // Build public key S-expression: (public-key (ecc (curve Ed25519) (flags eddsa) (q %b)))
  // Must include (flags eddsa) to match libgcrypt's Ed25519 test suite.
  // See libgcrypt/tests/t-ed25519.c line 246-251.
  err = gcry_sexp_build(&s_pubkey, NULL, "(public-key (ecc (curve Ed25519) (flags eddsa) (q %b)))", 32, public_key);
  if (err) {
    log_error("Failed to build public key S-expression: %s", gcry_strerror(err));
    return -1;
  }
 
  // Build signature S-expression: (sig-val (eddsa (r %b) (s %b)))
  // Signature is 64 bytes: first 32 bytes are R, last 32 bytes are S
  err = gcry_sexp_build(&s_sig, NULL, "(sig-val (eddsa (r %b) (s %b)))", 32, signature, 32, signature + 32);
  if (err) {
    log_error("Failed to build signature S-expression: %s", gcry_strerror(err));
    gcry_sexp_release(s_pubkey);
    return -1;
  }
 
  // Build data S-expression with raw message
  // According to libgcrypt's test suite (t-ed25519.c line 273),
  // Ed25519 data should be: (data (value %b)) with no flags.
  // The (flags eddsa) belongs in the key S-expression above, not in the data.
  // GPG agent's internal format is different - this is the correct libgcrypt API usage.
  err = gcry_sexp_build(&s_data, NULL, "(data (value %b))", message_len, message);
  if (err) {
    log_error("Failed to build data S-expression: %s", gcry_strerror(err));
    gcry_sexp_release(s_pubkey);
    gcry_sexp_release(s_sig);
    return -1;
  }
 
  // Debug logging
  char pubkey_hex[HEX_STRING_SIZE_32];
  char r_hex[HEX_STRING_SIZE_32];
  char s_hex[HEX_STRING_SIZE_32];
  char msg_hex[CRYPTO_GPG_VERIFICATION_MSG_HEX_BUFFER_SIZE];
 
  for (int i = 0; i < 32; i++) {
    safe_snprintf(pubkey_hex + i * 2, 3, "%02x", public_key[i]);
    safe_snprintf(r_hex + i * 2, 3, "%02x", signature[i]);
    safe_snprintf(s_hex + i * 2, 3, "%02x", signature[32 + i]);
  }
  for (size_t i = 0; i < (message_len < 32 ? message_len : 32); i++) {
    safe_snprintf(msg_hex + i * 2, 3, "%02x", message[i]);
  }
 
  log_debug("pubkey=%s", pubkey_hex);
  log_debug("R=%s", r_hex);
  log_debug("S=%s", s_hex);
  log_debug("msg=%s (len=%zu)", msg_hex, message_len);
 
  // Verify the signature
  err = gcry_pk_verify(s_sig, s_data, s_pubkey);
 
  // Clean up S-expressions
  gcry_sexp_release(s_pubkey);
  gcry_sexp_release(s_sig);
  gcry_sexp_release(s_data);
 
  if (err) {
    log_debug("Signature verification failed: %s", gcry_strerror(err));
    return -1;
  }
 
  log_debug("Signature verified successfully");
  return 0;
#else
  // Explicitly mark parameters as unused when libgcrypt is not available
  (void)public_key;
  (void)message;
  (void)message_len;
  (void)signature;
  log_error("libgcrypt not available");
  return -1;
#endif
}

References CRYPTO_GPG_VERIFICATION_MSG_HEX_BUFFER_SIZE, HEX_STRING_SIZE_32, log_debug, log_error, and safe_snprintf().

gpg_verify_signature_with_binary()

int gpg_verify_signature_with_binary	(	const uint8_t *	signature,
		size_t	signature_len,
		const uint8_t *	message,
		size_t	message_len,
		const char *	expected_key_id )

#include <include/ascii-chat/crypto/gpg/verification.h>

Verify OpenPGP signature using GPG binary.

Parameters

signature	GPG signature in OpenPGP packet format (must not be NULL)
signature_len	Signature length in bytes (must be > 0)
message	Message that was signed (must not be NULL)
message_len	Message length in bytes (must be > 0)
expected_key_id	Expected GPG key ID for signature (optional, can be NULL)

Returns

0 on success (valid signature), -1 on error (invalid signature or error)

Verifies OpenPGP-formatted signature using gpg --verify command. Accepts full OpenPGP signature packets from gpg_sign_with_key().

Note

Verification method: Uses gpg --verify on OpenPGP signature packet. Checks both cryptographic validity and key trust status.

Signature format: Input must be OpenPGP signature packet (binary format). Compatible with output from gpg_sign_with_key(). Not compatible with raw 64-byte Ed25519 signatures (use gpg_verify_detached_ed25519()).

OpenPGP parsing: GPG binary parses signature packet to extract:

• Signature algorithm (must be Ed25519/algorithm 22)
• Signing key ID
• Signature data

Key ID checking: If expected_key_id is provided, verifies signature was made by that key. Returns -1 if signature is from different key (prevents key substitution attacks).

Optional key verification: If expected_key_id is NULL, accepts signature from any key. Useful when you don't know signer's key ID in advance.

Public key requirement: Signing key must be in GPG keyring for verification. Import public key first with gpg --import <public_key_file>.

Key trust checking: GPG binary checks key trust and expiry. Verification fails if key is expired, revoked, or untrusted.

Variable length: OpenPGP signatures are variable length (typically 150-200 bytes). Must pass actual signature length in signature_len parameter.

Use case: Prefer this when:

• You have OpenPGP-formatted signature (from gpg_sign_with_key())
• You need key trust/expiry checking
• You want to verify signer identity (via expected_key_id)

Return value interpretation:

• 0: Signature valid, from expected key (if specified), and key trusted
• -1: Signature invalid, wrong key, key untrusted, or other error

Error conditions: Returns -1 if:

• Signature cryptographically invalid
• Signature from unexpected key (if expected_key_id specified)
• Signing key not found in keyring
• Key is expired or revoked
• Key is not trusted
• gpg binary not found in PATH
• OpenPGP packet parsing fails

Warning

GPG binary required: Requires gpg binary in PATH. Returns -1 if GPG is not installed or not accessible.

Ed25519 only: Only Ed25519 signatures are supported (OpenPGP algorithm 22). RSA/ECDSA signatures will return error.

Key must be imported: Signing public key must exist in GPG keyring. Returns -1 if key is not found (import with gpg --import).

Trust required: GPG checks key trust status. Verification may fail if key is not in web of trust.

Key ID mismatch: If expected_key_id is provided and signature is from different key, verification fails even if signature is cryptographically valid.

Definition at line 225 of file verification.c.

                                                                                      {
  // Validate inputs
  if (!signature || signature_len == 0 || signature_len > 512) {
    log_error("Invalid signature (expected 1-512 bytes, got %zu)", signature_len);
    return -1;
  }
  if (!message || message_len == 0) {
    log_error("Invalid message");
    return -1;
  }
 
  // Create temporary files for signature and message
  char sig_path[PLATFORM_MAX_PATH_LENGTH];
  char msg_path[PLATFORM_MAX_PATH_LENGTH];
  int sig_fd = -1;
  int msg_fd = -1;
  int result = -1;
 
  // Create temp files using platform abstraction
  if (platform_create_temp_file(sig_path, sizeof(sig_path), "asciichat_sig", &sig_fd) != 0) {
    log_error("Failed to create signature temp file");
    return -1;
  }
 
  if (platform_create_temp_file(msg_path, sizeof(msg_path), "asciichat_msg", &msg_fd) != 0) {
    log_error("Failed to create message temp file");
    platform_delete_temp_file(sig_path);
    return -1;
  }
 
#ifdef _WIN32
  // Windows: Write to already-created files using CreateFileA
  HANDLE sig_handle = CreateFileA(sig_path, GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_TEMPORARY, NULL);
  if (sig_handle == INVALID_HANDLE_VALUE) {
    log_error("Failed to open signature temp file: %lu", GetLastError());
    platform_delete_temp_file(sig_path);
    platform_delete_temp_file(msg_path);
    return -1;
  }
 
  DWORD bytes_written;
  if (!WriteFile(sig_handle, signature, (DWORD)signature_len, &bytes_written, NULL) || bytes_written != signature_len) {
    log_error("Failed to write signature to temp file: %lu", GetLastError());
    CloseHandle(sig_handle);
    platform_delete_temp_file(sig_path);
    platform_delete_temp_file(msg_path);
    return -1;
  }
  CloseHandle(sig_handle);
 
  HANDLE msg_handle = CreateFileA(msg_path, GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_TEMPORARY, NULL);
  if (msg_handle == INVALID_HANDLE_VALUE) {
    log_error("Failed to open message temp file: %lu", GetLastError());
    platform_delete_temp_file(sig_path);
    platform_delete_temp_file(msg_path);
    return -1;
  }
 
  if (!WriteFile(msg_handle, message, (DWORD)message_len, &bytes_written, NULL) || bytes_written != message_len) {
    log_error("Failed to write message to temp file: %lu", GetLastError());
    CloseHandle(msg_handle);
    platform_delete_temp_file(sig_path);
    platform_delete_temp_file(msg_path);
    return -1;
  }
  CloseHandle(msg_handle);
 
#else
  // Unix: Write to open file descriptors returned by platform_create_temp_file
  ssize_t sig_written = write(sig_fd, signature, signature_len);
  if (sig_written != (ssize_t)signature_len) {
    log_error("Failed to write signature to temp file: %s", SAFE_STRERROR(errno));
    close(sig_fd);
    close(msg_fd);
    platform_delete_temp_file(sig_path);
    platform_delete_temp_file(msg_path);
    return -1;
  }
  close(sig_fd);
 
  ssize_t msg_written = write(msg_fd, message, message_len);
  if (msg_written != (ssize_t)message_len) {
    log_error("Failed to write message to temp file: %s", SAFE_STRERROR(errno));
    close(msg_fd);
    platform_delete_temp_file(sig_path);
    platform_delete_temp_file(msg_path);
    return -1;
  }
  close(msg_fd);
#endif
 
  // Build gpg --verify command
  char cmd[BUFFER_SIZE_LARGE];
#ifdef _WIN32
  safe_snprintf(cmd, sizeof(cmd), "gpg --verify \"%s\" \"%s\" 2>&1", sig_path, msg_path);
#else
  safe_snprintf(cmd, sizeof(cmd), "gpg --verify '%s' '%s' 2>&1", sig_path, msg_path);
#endif
 
  log_debug("Running GPG verify command: %s", cmd);
 
  // Execute gpg --verify command
  FILE *fp;
  platform_popen("gpg_verify", cmd, "r", &fp);
  if (!fp) {
    log_error("Failed to execute gpg --verify command");
    goto cleanup;
  }
 
  // Parse output for "Good signature" and verify key ID
  char line[BUFFER_SIZE_MEDIUM];
  bool found_good_sig = false;
  bool found_key_id = false;
 
  while (fgets(line, sizeof(line), fp)) {
    log_debug("GPG output: %s", line);
 
    // Check for "Good signature"
    if (strstr(line, "Good signature")) {
      found_good_sig = true;
    }
 
    // Check if this line contains the expected key ID (GPG outputs key ID on separate line)
    if (expected_key_id && strlen(expected_key_id) > 0) {
      if (strstr(line, expected_key_id)) {
        found_key_id = true;
        log_debug("Found expected key ID in GPG output: %s", expected_key_id);
      }
    }
 
    // Check for signature errors
    if (strstr(line, "BAD signature")) {
      log_error("GPG reports BAD signature");
      platform_pclose(&fp);
      fp = NULL;
      goto cleanup;
    }
  }
 
  // Check exit code
  int status = platform_pclose(&fp);
  fp = NULL;
 
#ifdef _WIN32
  int exit_code = status;
#else
  int exit_code = WEXITSTATUS(status);
#endif
 
  if (exit_code != 0) {
    log_error("GPG verify failed with exit code: %d", exit_code);
    goto cleanup;
  }
 
  if (!found_good_sig) {
    log_error("GPG verify did not report 'Good signature'");
    goto cleanup;
  }
 
  // If expected_key_id was provided, verify we found it in the output
  if (expected_key_id && strlen(expected_key_id) > 0) {
    if (!found_key_id) {
      log_error("GPG signature key ID does not match expected key ID: %s", expected_key_id);
      goto cleanup;
    }
  }
 
  log_debug("GPG signature verified successfully via gpg --verify binary");
  result = 0;
 
cleanup:
  // Clean up temp files
  platform_delete_temp_file(sig_path);
  platform_delete_temp_file(msg_path);
 
  if (fp) {
    platform_pclose(&fp);
  }
 
  return result;
}

References BUFFER_SIZE_LARGE, BUFFER_SIZE_MEDIUM, bytes_written, errno, log_debug, log_error, PLATFORM_MAX_PATH_LENGTH, platform_pclose(), platform_popen(), safe_snprintf(), and SAFE_STRERROR.

known_hosts_destroy()

void known_hosts_destroy

(

void

)

#include <include/ascii-chat/crypto/known_hosts.h>

Cleanup function to free cached known_hosts path.

Frees cached known_hosts file path. Should be called at program shutdown to clean up resources.

Note

Path caching: Path is cached after first call to get_known_hosts_path(). This function frees the cached path.

Safe to call multiple times: Function checks if cache exists before freeing. Safe to call even if cache was never allocated.

Definition at line 819 of file known_hosts.c.

                               {
  if (g_known_hosts_path_cache) {
    SAFE_FREE(g_known_hosts_path_cache);
    g_known_hosts_path_cache = NULL;
  }
}

References SAFE_FREE.

Referenced by asciichat_shared_destroy().

openpgp_base64_decode()

asciichat_error_t openpgp_base64_decode	(	const char *	base64,
		size_t	base64_len,
		uint8_t **	binary_out,
		size_t *	binary_len )

#include <include/ascii-chat/crypto/gpg/openpgp.h>

Decode PGP armored base64 data.

Parameters

base64	Base64-encoded string
base64_len	Length of base64 string
binary_out	Output buffer for decoded binary data (allocated by function)
binary_len	Output parameter for decoded data length

Returns

ASCIICHAT_OK on success, error code on failure

Decodes base64 data from PGP armored format:

• Removes whitespace (newlines, spaces, tabs)
• Decodes using libsodium's base64 decoder
• Allocates output buffer (caller must free)

Note

Caller must free *binary_out using SAFE_FREE()

Definition at line 40 of file openpgp.c.

                                                            {
  if (!base64 || !binary_out || !binary_len) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for base64 decode");
  }
 
  // Remove whitespace from base64 input (PGP armor has newlines)
  SAFE_MALLOC_DEFER_FREE(clean_base64, base64_len + 1, char *);
  char *clean_ptr = clean_base64;
  for (size_t i = 0; i < base64_len; i++) {
    if (base64[i] != '\n' && base64[i] != '\r' && base64[i] != ' ' && base64[i] != '\t') {
      *clean_ptr++ = base64[i];
    }
  }
  *clean_ptr = '\0';
  size_t clean_len = (size_t)(clean_ptr - clean_base64);
 
  // Allocate max possible output size
  *binary_out = SAFE_MALLOC(clean_len, uint8_t *);
 
  const char *end;
  int result = sodium_base642bin(*binary_out, clean_len, clean_base64, clean_len, NULL, binary_len, &end,
                                 sodium_base64_VARIANT_ORIGINAL);
 
  if (result != 0) {
    SAFE_FREE(*binary_out);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to decode base64 PGP armored data");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, SAFE_FREE, SAFE_MALLOC, SAFE_MALLOC_DEFER_FREE, and SET_ERRNO.

Referenced by openpgp_parse_armored_pubkey(), and openpgp_parse_armored_seckey().

openpgp_extract_ed25519_from_mpi()

asciichat_error_t openpgp_extract_ed25519_from_mpi	(	const uint8_t *	mpi,
		size_t	mpi_len,
		uint8_t	ed25519_pk[32] )

#include <include/ascii-chat/crypto/gpg/openpgp.h>

Extract Ed25519 public key from MPI-encoded data.

Parameters

mpi	MPI-encoded public key data
mpi_len	Length of MPI data
ed25519_pk	Output buffer for Ed25519 public key (32 bytes)

Returns

ASCIICHAT_OK on success, error code on failure

Extracts Ed25519 public key from OpenPGP MPI (Multi-Precision Integer) format:

• 2 bytes: bit count (should be ~263 bits for Ed25519 with prefix)
• 1 byte: 0x40 prefix byte (Ed25519 marker)
• 32 bytes: Ed25519 public key

RFC 4880 Section 3.2: Multiprecision Integers

References ED25519_PUBLIC_KEY_SIZE.

openpgp_parse_armored_pubkey()

asciichat_error_t openpgp_parse_armored_pubkey	(	const char *	armored_text,
		uint8_t	ed25519_pk[32] )

#include <include/ascii-chat/crypto/gpg/openpgp.h>

Parse PGP armored key block and extract Ed25519 public key.

Parameters

armored_text	PGP armored text (--—BEGIN PGP PUBLIC KEY BLOCK--—)
ed25519_pk	Output buffer for Ed25519 public key (32 bytes)

Returns

ASCIICHAT_OK on success, error code on failure

Parses a complete PGP armored key block:

1. Extracts base64 data between BEGIN/END markers
2. Decodes base64 to binary OpenPGP packets
3. Parses packet headers to find public key packet (tag 6)
4. Extracts Ed25519 public key from packet body

Note

Only supports Ed25519 keys (algorithm 22)

Ignores signatures, user IDs, and other packet types

Does not verify checksums or signatures

Example armored format:

-----BEGIN PGP PUBLIC KEY BLOCK-----
 
mDMEaWxCORYJKwYBBAHaRw8BAQdAOaykIMyaQi8CBTNiF9o/Nbm6L5DwR9h1maS3
yqG5PFO0MmFzY2lpLWNoYXQgRGlzY292ZXJ5IFNlcnZpY2UgPGFjZHNAYXNjaWkt
...
=+ncm
-----END PGP PUBLIC KEY BLOCK-----

References ED25519_PUBLIC_KEY_SIZE.

openpgp_parse_armored_seckey()

asciichat_error_t openpgp_parse_armored_seckey	(	const char *	armored_text,
		uint8_t	ed25519_pk[32],
		uint8_t	ed25519_sk[32] )

#include <include/ascii-chat/crypto/gpg/openpgp.h>

Parse PGP armored secret key block and extract Ed25519 keypair.

Parameters

armored_text	PGP armored text (--—BEGIN PGP PRIVATE KEY BLOCK--—)
ed25519_pk	Output buffer for Ed25519 public key (32 bytes)
ed25519_sk	Output buffer for Ed25519 secret key (32 bytes)

Returns

ASCIICHAT_OK on success, error code on failure

Parses a complete PGP armored secret key block:

1. Extracts base64 data between BEGIN/END markers
2. Decodes base64 to binary OpenPGP packets
3. Parses packet headers to find secret key packet (tag 5)
4. Extracts Ed25519 public and secret keys from packet body

Note

Only supports Ed25519 keys (algorithm 22)

Only supports unencrypted secret keys (S2K usage = 0)

Ignores signatures, user IDs, and other packet types

Does not verify checksums or signatures

Example armored format:

-----BEGIN PGP PRIVATE KEY BLOCK-----
 
lIYEaWxCORYJKwYBBAHaRw8BAQdAOaykIMyaQi8CBTNiF9o/Nbm6L5DwR9h1maS3
yqG5PFMAAQDm8...
=abcd
-----END PGP PRIVATE KEY BLOCK-----

References ED25519_PUBLIC_KEY_SIZE, and ED25519_SEED_SIZE.

openpgp_parse_binary_pubkey()

asciichat_error_t openpgp_parse_binary_pubkey	(	const uint8_t *	data,
		size_t	data_len,
		uint8_t	ed25519_pk[32] )

#include <include/ascii-chat/crypto/gpg/openpgp.h>

Parse a binary OpenPGP public-key packet stream and extract its Ed25519 key.

References ED25519_PUBLIC_KEY_SIZE.

openpgp_parse_binary_seckey()

asciichat_error_t openpgp_parse_binary_seckey	(	const uint8_t *	data,
		size_t	data_len,
		uint8_t	ed25519_pk[32],
		uint8_t	ed25519_sk[32] )

#include <include/ascii-chat/crypto/gpg/openpgp.h>

Parse an unencrypted binary OpenPGP secret-key packet stream.

References ED25519_PUBLIC_KEY_SIZE, and ED25519_SEED_SIZE.

openpgp_parse_packet_header()

asciichat_error_t openpgp_parse_packet_header	(	const uint8_t *	data,
		size_t	data_len,
		openpgp_packet_header_t *	header )

#include <include/ascii-chat/crypto/gpg/openpgp.h>

Parse OpenPGP packet header.

Parameters

data	Packet data (starts with packet header byte)
data_len	Length of packet data
header	Output parameter for parsed header

Returns

ASCIICHAT_OK on success, error code on failure

Parses OpenPGP packet header (old or new format):

• Old format: bit 7 = 1, bit 6 = 0, bits 5-2 = tag, bits 1-0 = length type
• New format: bit 7 = 1, bit 6 = 1, bits 5-0 = tag

RFC 4880 Section 4.2: Packet Headers

Definition at line 76 of file openpgp.c.

                                                                                                                     {
  if (!data || !header || data_len == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for packet header parsing");
  }
 
  memset(header, 0, sizeof(openpgp_packet_header_t));
 
  uint8_t ctb = data[0]; // Cipher Type Byte
 
  // Check if bit 7 is set (all packets must have bit 7 = 1)
  if ((ctb & 0x80) == 0) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid OpenPGP packet: bit 7 not set in CTB");
  }
 
  // Check if new format (bit 6 = 1) or old format (bit 6 = 0)
  if (ctb & 0x40) {
    // New format: bits 5-0 = tag
    header->new_format = true;
    header->tag = ctb & 0x3F;
 
    if (data_len < 2) {
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Insufficient data for new format packet header");
    }
 
    uint8_t len_byte = data[1];
 
    if (len_byte < 192) {
      // One-octet length
      header->length = len_byte;
      header->header_len = 2;
    } else if (len_byte < 224) {
      // Two-octet length
      if (data_len < 3) {
        return SET_ERRNO(ERROR_CRYPTO_KEY, "Insufficient data for two-octet length");
      }
      header->length = ((len_byte - 192) << 8) + data[2] + 192;
      header->header_len = 3;
    } else if (len_byte == 255) {
      // Five-octet length
      if (data_len < 6) {
        return SET_ERRNO(ERROR_CRYPTO_KEY, "Insufficient data for five-octet length");
      }
      header->length = ((size_t)data[2] << 24) | ((size_t)data[3] << 16) | ((size_t)data[4] << 8) | data[5];
      header->header_len = 6;
    } else {
      // Partial body length (not supported for our use case)
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Partial body length not supported");
    }
  } else {
    // Old format: bits 5-2 = tag, bits 1-0 = length type
    header->new_format = false;
    header->tag = (ctb >> 2) & 0x0F;
    uint8_t length_type = ctb & 0x03;
 
    switch (length_type) {
    case 0: // One-octet length
      if (data_len < 2) {
        return SET_ERRNO(ERROR_CRYPTO_KEY, "Insufficient data for one-octet length");
      }
      header->length = data[1];
      header->header_len = 2;
      break;
 
    case 1: // Two-octet length
      if (data_len < 3) {
        return SET_ERRNO(ERROR_CRYPTO_KEY, "Insufficient data for two-octet length");
      }
      header->length = ((size_t)data[1] << 8) | data[2];
      header->header_len = 3;
      break;
 
    case 2: // Four-octet length
      if (data_len < 5) {
        return SET_ERRNO(ERROR_CRYPTO_KEY, "Insufficient data for four-octet length");
      }
      header->length = ((size_t)data[1] << 24) | ((size_t)data[2] << 16) | ((size_t)data[3] << 8) | data[4];
      header->header_len = 5;
      break;
 
    case 3: // Indeterminate length (not supported)
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Indeterminate length not supported");
 
    default:
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid length type: %u", length_type);
    }
  }
 
  log_debug("OpenPGP packet: tag=%u, length=%zu, header_len=%zu, new_format=%d", header->tag, header->length,
            header->header_len, header->new_format);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, log_debug, and SET_ERRNO.

Referenced by openpgp_parse_armored_seckey(), openpgp_parse_binary_pubkey(), and openpgp_parse_binary_seckey().

openpgp_parse_public_key_packet()

asciichat_error_t openpgp_parse_public_key_packet	(	const uint8_t *	packet_body,
		size_t	body_len,
		openpgp_public_key_t *	pubkey )

#include <include/ascii-chat/crypto/gpg/openpgp.h>

Parse OpenPGP Public Key Packet (tag 6).

Parameters

packet_body	Packet body data (after header)
body_len	Length of packet body
pubkey	Output parameter for parsed public key

Returns

ASCIICHAT_OK on success, error code on failure

Parses Public Key Packet (tag 6) body:

• Version (1 byte, must be 4)
• Creation time (4 bytes, Unix timestamp)
• Algorithm (1 byte, 22 = EdDSA)
• Public key material (MPI format for Ed25519)

RFC 4880 Section 5.5.2: Public-Key Packet Formats

Note

Only supports version 4 packets

Only supports EdDSA (algorithm 22)

Definition at line 207 of file openpgp.c.

                                                                                {
  if (!packet_body || !pubkey || body_len < 6) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for public key packet parsing");
  }
 
  memset(pubkey, 0, sizeof(openpgp_public_key_t));
 
  size_t offset = 0;
 
  // Version (1 byte, must be 4)
  pubkey->version = packet_body[offset++];
  if (pubkey->version != 4) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Unsupported OpenPGP public key version: %u (only version 4 supported)",
                     pubkey->version);
  }
 
  // Creation time (4 bytes, big-endian Unix timestamp)
  pubkey->created = ((uint32_t)packet_body[offset] << 24) | ((uint32_t)packet_body[offset + 1] << 16) |
                    ((uint32_t)packet_body[offset + 2] << 8) | packet_body[offset + 3];
  offset += 4;
 
  // Algorithm (1 byte)
  pubkey->algorithm = packet_body[offset++];
 
  log_debug("Public key packet: version=%u, created=%u, algorithm=%u", pubkey->version, pubkey->created,
            pubkey->algorithm);
 
  // Only support EdDSA (algorithm 22)
  if (pubkey->algorithm != OPENPGP_ALGO_EDDSA) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Unsupported public key algorithm: %u (only EdDSA/22 supported)",
                     pubkey->algorithm);
  }
 
  // EdDSA (Ed25519) keys have a special encoding:
  // - OID for the curve (variable length)
  // - 0x40 prefix byte
  // - 32 bytes of Ed25519 public key
  //
  // We search for the 0x40 prefix and extract the following 32 bytes
 
  // Search for 0x40 prefix byte in the remaining packet data
  bool found_prefix = false;
  size_t key_offset = 0;
 
  for (size_t i = offset; i < body_len - 32; i++) {
    if (packet_body[i] == 0x40) {
      key_offset = i + 1; // Point to first byte after 0x40
      found_prefix = true;
      log_debug("Found Ed25519 key prefix 0x40 at offset %zu", i);
      break;
    }
  }
 
  if (!found_prefix) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Ed25519 public key prefix (0x40) not found in packet");
  }
 
  if (key_offset + 32 > body_len) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Insufficient data for Ed25519 public key (need 32 bytes after 0x40 prefix)");
  }
 
  // Extract the 32-byte Ed25519 public key
  memcpy(pubkey->pubkey, packet_body + key_offset, ED25519_PUBLIC_KEY_SIZE);
 
  // Calculate Key ID (last 8 bytes of SHA-1 fingerprint)
  // For now, we'll skip fingerprint calculation and just extract from packet if available
  // The keyid is typically at a fixed offset for Ed25519 keys
  // We'll compute it properly by hashing the public key material
 
  // For version 4 keys, fingerprint = SHA-1(0x99 || length || packet_body)
  // Key ID = last 8 bytes of fingerprint
  // For simplicity, we'll set keyid to 0 for now (not critical for our use case)
  pubkey->keyid = 0;
 
  return ASCIICHAT_OK;
}

References openpgp_public_key_t::algorithm, ASCIICHAT_OK, openpgp_public_key_t::created, ED25519_PUBLIC_KEY_SIZE, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, openpgp_public_key_t::keyid, log_debug, OPENPGP_ALGO_EDDSA, openpgp_public_key_t::pubkey, SET_ERRNO, and openpgp_public_key_t::version.

Referenced by openpgp_parse_binary_pubkey().

openpgp_parse_secret_key_packet()

asciichat_error_t openpgp_parse_secret_key_packet	(	const uint8_t *	packet_body,
		size_t	body_len,
		openpgp_secret_key_t *	seckey )

#include <include/ascii-chat/crypto/gpg/openpgp.h>

Parse OpenPGP Secret Key Packet (tag 5).

Parameters

packet_body	Packet body data (after header)
body_len	Length of packet body
seckey	Output parameter for parsed secret key

Returns

ASCIICHAT_OK on success, error code on failure

Parses Secret Key Packet (tag 5) body:

• Version (1 byte, must be 4)
• Creation time (4 bytes, Unix timestamp)
• Algorithm (1 byte, 22 = EdDSA)
• Public key material (MPI format for Ed25519)
• S2K usage (1 byte, must be 0 for unencrypted)
• Secret key material (32 bytes for Ed25519)

RFC 4880 Section 5.5.3: Secret-Key Packet Formats

Note

Only supports version 4 packets

Only supports EdDSA (algorithm 22)

Only supports unencrypted secret keys (S2K usage = 0)

Definition at line 378 of file openpgp.c.

                                                                                {
  if (!packet_body || !seckey || body_len < 6) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for secret key packet parsing");
  }
 
  memset(seckey, 0, sizeof(openpgp_secret_key_t));
 
  size_t offset = 0;
 
  // Parse public key portion (same as public key packet)
  // Version (1 byte, must be 4)
  seckey->version = packet_body[offset++];
  if (seckey->version != 4) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Unsupported OpenPGP secret key version: %u (only version 4 supported)",
                     seckey->version);
  }
 
  // Creation time (4 bytes, big-endian Unix timestamp)
  seckey->created = ((uint32_t)packet_body[offset] << 24) | ((uint32_t)packet_body[offset + 1] << 16) |
                    ((uint32_t)packet_body[offset + 2] << 8) | packet_body[offset + 3];
  offset += 4;
 
  // Algorithm (1 byte)
  seckey->algorithm = packet_body[offset++];
 
  log_debug("Secret key packet: version=%u, created=%u, algorithm=%u", seckey->version, seckey->created,
            seckey->algorithm);
 
  // Only support EdDSA (algorithm 22)
  if (seckey->algorithm != OPENPGP_ALGO_EDDSA) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Unsupported secret key algorithm: %u (only EdDSA/22 supported)",
                     seckey->algorithm);
  }
 
  // EdDSA public key: OID + 0x40 prefix + 32 bytes of Ed25519 public key
  // Search for 0x40 prefix byte
  bool found_prefix = false;
  size_t pubkey_offset = 0;
 
  for (size_t i = offset; i < body_len - 32; i++) {
    if (packet_body[i] == 0x40) {
      pubkey_offset = i + 1;
      found_prefix = true;
      log_debug("Found Ed25519 public key prefix 0x40 at offset %zu", i);
      break;
    }
  }
 
  if (!found_prefix) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Ed25519 public key prefix (0x40) not found in secret key packet");
  }
 
  if (pubkey_offset + 32 > body_len) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Insufficient data for Ed25519 public key (need 32 bytes after 0x40 prefix)");
  }
 
  // Extract the 32-byte Ed25519 public key
  memcpy(seckey->pubkey, packet_body + pubkey_offset, ED25519_PUBLIC_KEY_SIZE);
 
  // Move offset past public key material
  offset = pubkey_offset + 32;
 
  // S2K usage byte (1 byte)
  // 0x00 = secret key is not encrypted
  // 0xFE or 0xFF = secret key is encrypted with S2K
  if (offset >= body_len) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Missing S2K usage byte in secret key packet");
  }
 
  uint8_t s2k_usage = packet_body[offset++];
  log_debug("S2K usage byte: 0x%02x", s2k_usage);
 
  if (s2k_usage != 0x00) {
    seckey->is_encrypted = true;
    log_debug("Detected encrypted secret key (S2K usage = 0x%02x)", s2k_usage);
    // Don't parse encrypted key material here - caller will need to decrypt with gpg
    return ASCIICHAT_OK;
  }
 
  seckey->is_encrypted = false;
 
  // The Ed25519 secret scalar is encoded as an OpenPGP MPI (bit count followed by bytes).
  if (offset + 2 > body_len) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Missing Ed25519 secret-key MPI length");
  }
  uint16_t secret_bits = (uint16_t)(((uint16_t)packet_body[offset] << 8) | packet_body[offset + 1]);
  size_t secret_bytes = (secret_bits + 7u) / 8u;
  offset += 2;
  if (secret_bits == 0 || secret_bits > 256 || secret_bytes > sizeof(seckey->seckey) ||
      offset + secret_bytes + 2 > body_len) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid Ed25519 secret-key MPI length: %u bits", secret_bits);
  }
 
  // Ed25519 private material is 32 bytes; left-pad shorter MPIs as specified by OpenPGP.
  memcpy(seckey->seckey + sizeof(seckey->seckey) - secret_bytes, packet_body + offset, secret_bytes);
 
  log_debug("Extracted Ed25519 secret key");
 
  return ASCIICHAT_OK;
}

References openpgp_secret_key_t::algorithm, ASCIICHAT_OK, openpgp_secret_key_t::created, ED25519_PUBLIC_KEY_SIZE, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, openpgp_secret_key_t::is_encrypted, log_debug, OPENPGP_ALGO_EDDSA, openpgp_secret_key_t::pubkey, openpgp_secret_key_t::seckey, SET_ERRNO, and openpgp_secret_key_t::version.

Referenced by openpgp_parse_armored_seckey(), and openpgp_parse_binary_seckey().

prompt_unknown_host()

bool prompt_unknown_host	(	const char *	server_ip,
		uint16_t	port,
		const uint8_t	server_key[32] )

#include <include/ascii-chat/crypto/known_hosts.h>

Interactive prompt for unknown host - returns true if user wants to add, false to abort.

Parameters

server_ip	Server IP address (IPv4 or IPv6, must not be NULL)
port	Server port number
server_key	Server's Ed25519 public key (32 bytes, must not be NULL)

Returns

true if user wants to add to known_hosts, false to abort

Prompts user to add unknown host to known_hosts. Displays server information and key fingerprint for user verification.

Note

Prompt display: Shows server IP:port and key fingerprint (SHA256). Prompts user to accept (add to known_hosts) or reject (abort connection).

Key fingerprint: Displays SHA256 fingerprint of server key for verification. Fingerprint is displayed in hex format (64 hex chars).

Non-interactive mode: If not connected to TTY (snapshot mode), automatically adds host to known_hosts (returns true). This allows automated connections.

Security: User should verify key fingerprint before accepting. Only add host if key fingerprint matches expected value.

Warning

Always check return value. If false, connection should be aborted.

References ED25519_PUBLIC_KEY_SIZE.

prompt_unknown_host_no_identity()

bool prompt_unknown_host_no_identity	(	const char *	server_ip,
		uint16_t	port )

#include <include/ascii-chat/crypto/known_hosts.h>

Interactive prompt for unknown host without identity key - returns true if user wants to continue, false to abort.

Parameters

server_ip	Server IP address (IPv4 or IPv6, must not be NULL)
port	Server port number

Returns

true if user wants to continue (accepts no-identity connection), false to abort

Prompts user to accept unknown host without identity key. Displays server information and warns that identity cannot be verified.

Note

Prompt display: Shows server IP:port and warning that identity cannot be verified. Prompts user to accept (continue connection) or reject (abort connection).

Security warning: Warns that server identity cannot be verified (no identity key). Connection is vulnerable to MITM attacks without identity verification.

Non-interactive mode: If not connected to TTY (snapshot mode), automatically accepts connection (returns true). This allows automated connections.

No-identity entries: If user accepts, adds "no-identity" entry to known_hosts. This tracks that user previously accepted this server without identity verification.

Warning

Security limitation: Cannot verify server identity (no keys to compare). Connection is vulnerable to MITM attacks.

Always check return value. If false, connection should be aborted.

Definition at line 761 of file known_hosts.c.

                                                                           {
  // Format IP:port with proper bracket notation for IPv6
  char ip_with_port[BUFFER_SIZE_MEDIUM];
  if (format_ip_with_port(server_ip, port, ip_with_port, sizeof(ip_with_port)) != ASCIICHAT_OK) {
    // Fallback to basic format if error
    safe_snprintf(ip_with_port, sizeof(ip_with_port), "%s:%u", server_ip, port);
  }
 
  // LOCALHOST OPTIMIZATION: Skip authentication prompt for localhost addresses
  // Localhost is inherently trusted (same machine, no network exposure)
  // This matches SSH behavior (ssh-keyscan doesn't prompt for localhost)
  if (is_localhost_address(server_ip)) {
    log_debug(
        "SECURITY: Localhost address %s detected - skipping unknown host prompt (localhost is inherently trusted)",
        ip_with_port);
    return true; // Silently trust localhost
  }
 
  // Check if running in automated/non-interactive environment
  // In debug builds, Claude Code automation can't interact with prompts
  if (is_automated_mode()) {
    SET_ERRNO(ERROR_CRYPTO, "SECURITY: Cannot verify server without identity key in non-interactive/automated mode");
    NOTICE(DANGER, "SERVER IDENTITY MISSING",
           "ERROR: Cannot verify server without identity key in non-interactive/automated mode.\n"
           "ERROR: This connection is vulnerable to man-in-the-middle attacks!\n"
           "\n"
           "To connect to this host:\n"
           "  1. Run the client interactively (from a terminal with TTY)\n"
           "  2. Verify you trust this server despite no identity key\n"
           "  3. Accept the risk when prompted\n"
           "  OR better: Ask server admin to use --key for proper authentication\n"
           "\n"
           "Connection aborted for security.\n"
           "\n");
    return false;
  }
 
  char question[CRYPTO_KNOWN_HOSTS_QUESTION_BUFFER_SIZE];
  safe_snprintf(question, sizeof(question),
                "Host '%s' has no identity key.\n"
                "This connection is vulnerable to man-in-the-middle attacks.\n"
                "Anyone intercepting it could read your data.\n\n"
                "Use --key on the server and --server-key on the client to verify identity.\n\n"
                "Are you sure you want to continue connecting",
                ip_with_port);
  if (ui_notice_confirm_kind(UI_PROMPT_UNVERIFIED_HOST, UI_NOTICE_DANGER, question, 120)) {
    NOTICE(DANGER, "UNVERIFIED CONNECTION",
           "Warning: Proceeding with unverified connection.\n"
           "Your data may be intercepted by attackers!\n"
           "\n");
    return true;
  }
 
  log_plain("Connection aborted by user.");
  return false;
}

References ASCIICHAT_OK, BUFFER_SIZE_MEDIUM, CRYPTO_KNOWN_HOSTS_QUESTION_BUFFER_SIZE, ERROR_CRYPTO, format_ip_with_port(), log_debug, log_plain, NOTICE, safe_snprintf(), SET_ERRNO, ui_notice_confirm_kind(), and UI_NOTICE_DANGER.

Referenced by crypto_handshake_client_key_exchange().

read_trust_anchors_from_memory()

size_t read_trust_anchors_from_memory	(	anchor_list *	dst,
		const unsigned char *	pem_data,
		size_t	pem_len )

#include <include/ascii-chat/crypto/pem.h>

Read trust anchors from PEM-encoded data in memory.

Parameters

dst	Pointer to anchor_list to append trust anchors to (must not be NULL)
pem_data	Pointer to PEM-encoded certificate data (must not be NULL)
pem_len	Length of PEM data in bytes (must be > 0)

Returns

Number of trust anchors successfully decoded and added, or 0 on error

Parses PEM-encoded CA certificates from a memory buffer and converts them to BearSSL trust anchors. The trust anchors are appended to the provided anchor_list.

Note

PEM format: Accepts PEM-encoded certificates (--—BEGIN CERTIFICATE--—). Supports multiple certificates in single PEM data (concatenated).

Trust anchor parsing: Parses each certificate in PEM data and creates trust anchor structure. Appends trust anchors to anchor_list.

Memory allocation: Dynamically allocates memory for trust anchors. Resizes anchor_list.buf as needed (realloc).

Error handling: Returns 0 on error (parse error, memory error, etc.). Partially parsed trust anchors are retained (not rolled back).

Warning

Memory management: Trust anchors contain dynamically allocated memory. Must call free_ta_contents() for each anchor and free anchor_list.buf.

PEM data format: PEM data must be valid PEM-encoded certificates. Invalid PEM data may cause parse errors or crashes.

Definition at line 457 of file pem.c.

                                                                                                       {
  br_x509_certificate *xcs;
  anchor_list tas = VEC_INIT;
  size_t u, num;
 
  xcs = read_certificates_from_memory(pem_data, pem_len, &num);
  if (xcs == NULL) {
    return 0;
  }
 
  for (u = 0; u < num; u++) {
    br_x509_trust_anchor ta;
 
    if (certificate_to_trust_anchor_inner(&ta, &xcs[u]) != ASCIICHAT_OK) {
      VEC_CLEAREXT(tas, free_ta_contents);
      free_certificates(xcs, num);
      return 0;
    }
    VEC_ADD(tas, ta);
  }
 
  VEC_ADDMANY(*dst, &VEC_ELT(tas, 0), num);
  VEC_CLEAR(tas);
  free_certificates(xcs, num);
  return num;
}

References ASCIICHAT_OK, free_ta_contents(), VEC_ADD, VEC_ADDMANY, VEC_CLEAR, VEC_CLEAREXT, VEC_ELT, and VEC_INIT.

Referenced by https_get().

remove_known_host()

asciichat_error_t remove_known_host	(	const char *	server_ip,
		uint16_t	port )

#include <include/ascii-chat/crypto/known_hosts.h>

Remove server from known_hosts.

Parameters

server_ip	Server IP address (IPv4 or IPv6, must not be NULL)
port	Server port number

Returns

ASCIICHAT_OK on success, error code on failure

Removes all entries for server IP:port from known_hosts file. Removes both identity key entries and no-identity entries.

Note

Removal: Removes ALL entries matching IP:port (including multiple entries). File is rewritten with all matching entries removed.

File format: Removes entries matching <IP:port> x25519 ... and <IP:port> no-identity .... Uses proper bracket notation for IPv6 addresses.

File preservation: Preserves all other entries and comments. Only removes entries matching the specified IP:port.

Warning

File is rewritten: Function reads entire file, removes matching entries, and rewrites. Original file is preserved as backup if possible.

Definition at line 474 of file known_hosts.c.

                                                                          {
  // Validate parameters first
  if (!server_ip) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameter: server_ip=%p", server_ip);
  }
 
  const char *path = get_known_hosts_path();
  int fd = platform_open("known_hosts_file", path, PLATFORM_O_RDONLY, FILE_PERM_PRIVATE);
  if (fd < 0) {
    // File doesn't exist - nothing to remove, return success
    return ASCIICHAT_OK;
  }
  FILE *f = platform_fdopen("known_hosts_stream", fd, "r");
  defer(SAFE_FCLOSE(f));
  if (!f) {
    platform_close(fd);
    SET_ERRNO_SYS(ERROR_CONFIG, "Failed to open known hosts file: %s", path);
    return ERROR_CONFIG;
  }
 
  // Format IP:port with proper bracket notation for IPv6
  char ip_with_port[BUFFER_SIZE_MEDIUM];
  if (format_ip_with_port(server_ip, port, ip_with_port, sizeof(ip_with_port)) != ASCIICHAT_OK) {
 
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IP format: %s", server_ip);
  }
 
  // Read all lines into memory
  char **lines = NULL;
  size_t num_lines = 0;
  defer({
    if (lines) {
      for (size_t i = 0; i < num_lines; i++) {
        SAFE_FREE(lines[i]);
      }
    }
    SAFE_FREE(lines);
  });
  char line[BUFFER_SIZE_XLARGE];
 
  char expected_prefix[BUFFER_SIZE_MEDIUM];
  safe_snprintf(expected_prefix, sizeof(expected_prefix), "%s ", ip_with_port);
 
  while (fgets(line, sizeof(line), f)) {
    // Skip lines that match this IP:port
    if (strncmp(line, expected_prefix, strlen(expected_prefix)) != 0) {
      // Keep this line
      char **new_lines = SAFE_REALLOC((void *)lines, (num_lines + 1) * sizeof(char *), char **);
      if (new_lines) {
        lines = new_lines;
        lines[num_lines] = platform_strdup(line);
        if (lines[num_lines] == NULL) {
          return SET_ERRNO(ERROR_MEMORY, "Failed to duplicate line from known_hosts file");
        }
        num_lines++;
      }
    }
  }
  // Close first file before opening for write
  if (f) {
    fclose(f);
    f = NULL; // Prevent double-close by defer
  }
 
  // Write back the filtered lines
  fd = platform_open("known_hosts_file_write", path, PLATFORM_O_WRONLY | PLATFORM_O_CREAT | PLATFORM_O_TRUNC,
                     FILE_PERM_PRIVATE);
  f = platform_fdopen("known_hosts_write_stream", fd, "w");
  if (!f) {
    // Cleanup on error - fdopen failed, so fd is still open but f is NULL
    // Individual line strings will be freed by defer cleanup
    platform_close(fd); // Close fd directly since fdopen failed
    return SET_ERRNO_SYS(ERROR_CONFIG, "Failed to open known hosts file: %s", path);
  }
 
  for (size_t i = 0; i < num_lines; i++) {
    (void)fputs(lines[i], f);
  }
  // All cleanup (lines, individual strings, file handle) handled by defer statements
 
  log_debug("KNOWN_HOSTS: Successfully removed host from known_hosts file: %s", path);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, BUFFER_SIZE_MEDIUM, BUFFER_SIZE_XLARGE, ERROR_CONFIG, ERROR_INVALID_PARAM, ERROR_MEMORY, format_ip_with_port(), get_known_hosts_path(), log_debug, SAFE_FCLOSE, SAFE_FREE, SAFE_REALLOC, safe_snprintf(), SET_ERRNO, and SET_ERRNO_SYS.

ssh_agent_add_key()

asciichat_error_t ssh_agent_add_key	(	const private_key_t *	private_key,
		const char *	key_path )

#include <include/ascii-chat/crypto/ssh/ssh_agent.h>

Add a private key to ssh-agent.

Parameters

private_key	Private key to add (must not be NULL)
key_path	Original key file path (for reference, can be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Adds private key to SSH agent using the SSH agent protocol.

Message format: uint32: message length byte: SSH2_AGENTC_ADD_IDENTITY (17) string: key type ("ssh-ed25519") string: public key (32 bytes) string: private key (64 bytes) string: comment (key path or empty)

Note

Agent requirement: SSH agent must be running and accessible. Function returns error if agent is not available.

Key format: Only Ed25519 keys are supported. Returns error if key type is not KEY_TYPE_ED25519.

Key addition: Uses SSH agent protocol directly via lib/platform/pipe.h abstraction:

• Connects to agent via Unix domain socket (POSIX) or named pipe (Windows)
• Sends SSH2_AGENTC_ADD_IDENTITY (17) message with key material
• Receives SSH_AGENT_SUCCESS (6) response on success
• No temporary files or external commands required

Platform abstraction: Uses lib/platform/pipe.h for cross-platform communication:

• POSIX: Unix domain socket via SSH_AUTH_SOCK environment variable
• Windows: Named pipe via SSH_AUTH_SOCK or default \\.\pipe\openssh-ssh-agent

Idempotent: SSH agent protocol is idempotent - adding same key multiple times is safe. Key is not duplicated in agent.

Key path: key_path is only used for logging/reference in agent comment field. No temporary files are created.

Warning

Agent requirement: SSH agent must be running and accessible. Returns error if agent connection fails (agent not running, wrong path, etc.).

Key format: Only Ed25519 keys are supported. Other key types will return error.

Definition at line 149 of file ssh_agent.c.

                                                                                            {
  if (private_key == NULL) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Cannot add key to ssh-agent: private_key is NULL");
  }
  if (private_key->type != KEY_TYPE_ED25519) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Cannot add key to ssh-agent: only Ed25519 keys supported");
  }
 
  log_debug("Adding key to ssh-agent: %s", key_path ? key_path : "(memory)");
 
  // Open the pipe/socket for this operation (works on both Windows and Unix)
  pipe_t pipe = ssh_agent_open_pipe();
  if (pipe == INVALID_PIPE_VALUE) {
    return SET_ERRNO(ERROR_CRYPTO, "Failed to connect to ssh-agent");
  }
 
  // Build SSH agent protocol message: SSH2_AGENTC_ADD_IDENTITY (17)
  // Message format:
  //   uint32: message length
  //   byte:   SSH2_AGENTC_ADD_IDENTITY (17)
  //   string: key type ("ssh-ed25519")
  //   string: public key (32 bytes)
  //   string: private key (64 bytes)
  //   string: comment (key path or empty)
 
  unsigned char buf[BUFFER_SIZE_XXLARGE];
  size_t pos = 4; // Reserve space for length prefix
 
  // Message type: SSH2_AGENTC_ADD_IDENTITY
  buf[pos++] = 17;
 
  // Key type: "ssh-ed25519" (11 bytes)
  uint32_t len = 11;
  write_u32_be(buf + pos, len);
  pos += 4;
  // Binary protocol: intentionally not null-terminated
  // NOLINTNEXTLINE(bugprone-not-null-terminated-result) - binary data
  memcpy(buf + pos, "ssh-ed25519", 11);
  pos += 11;
 
  // Public key (32 bytes) - last 32 bytes of the 64-byte ed25519 key
  len = 32;
  write_u32_be(buf + pos, len);
  pos += 4;
  memcpy(buf + pos, private_key->key.ed25519 + ED25519_SEED_SIZE, ED25519_PUBLIC_KEY_SIZE); // Public key is second half
  pos += 32;
 
  // Private key (64 bytes - full ed25519 key: 32-byte seed + 32-byte public)
  len = 64;
  write_u32_be(buf + pos, len);
  pos += 4;
  memcpy(buf + pos, private_key->key.ed25519, ED25519_PRIVATE_KEY_SIZE);
  pos += 64;
 
  // Comment (key path)
  len = key_path ? strlen(key_path) : 0;
 
  // SECURITY: Validate key path length to prevent buffer overflow
  // Buffer is BUFFER_SIZE_XXLARGE (4096), pos is ~128 at this point, need 4 bytes for length prefix
  size_t max_key_path_len = sizeof(buf) - pos - 4;
  if (len > max_key_path_len) {
    platform_pipe_close(pipe);
    sodium_memzero(buf, sizeof(buf));
    return SET_ERRNO(ERROR_BUFFER_OVERFLOW, "SSH key path too long: %u bytes (max %zu)", len, max_key_path_len);
  }
 
  write_u32_be(buf + pos, len);
  pos += 4;
  if (len > 0) {
    memcpy(buf + pos, key_path, len);
    pos += len;
  }
 
  // Write message length at start (excluding the 4-byte length field itself)
  uint32_t msg_len = pos - 4;
  write_u32_be(buf, msg_len);
 
  // Send message to agent
  ssize_t bytes_written = platform_pipe_write(pipe, buf, pos);
  if (bytes_written != (ssize_t)pos) {
    platform_pipe_close(pipe);
    sodium_memzero(buf, sizeof(buf));
    return SET_ERRNO_SYS(ERROR_CRYPTO, "Failed to write to ssh-agent pipe");
  }
 
  // Read response
  unsigned char response[BUFFER_SIZE_SMALL];
  ssize_t bytes_read = platform_pipe_read(pipe, response, sizeof(response));
  if (bytes_read < 5) {
    platform_pipe_close(pipe);
    sodium_memzero(buf, sizeof(buf));
    return SET_ERRNO_SYS(ERROR_CRYPTO, "Failed to read from ssh-agent pipe");
  }
 
  // Done with the pipe - close it
  platform_pipe_close(pipe);
  sodium_memzero(buf, sizeof(buf));
 
  // Check response: should be SSH_AGENT_SUCCESS (6)
  // Response format: uint32 length, byte message_type
  uint8_t response_type = response[4];
  if (response_type == 6) {
    log_debug("Successfully added key to ssh-agent");
    return ASCIICHAT_OK;
  } else if (response_type == 5) {
    return SET_ERRNO(ERROR_CRYPTO, "ssh-agent rejected key (SSH_AGENT_FAILURE)");
  } else {
    return SET_ERRNO(ERROR_CRYPTO, "ssh-agent returned unexpected response: %d", response_type);
  }
}

References ASCIICHAT_OK, BUFFER_SIZE_SMALL, BUFFER_SIZE_XXLARGE, bytes_written, private_key_t::ed25519, ED25519_PRIVATE_KEY_SIZE, ED25519_PUBLIC_KEY_SIZE, ED25519_SEED_SIZE, ERROR_BUFFER_OVERFLOW, ERROR_CRYPTO, ERROR_INVALID_PARAM, INVALID_PIPE_VALUE, private_key_t::key, KEY_TYPE_ED25519, log_debug, platform_pipe_close(), platform_pipe_read(), platform_pipe_write(), SET_ERRNO, SET_ERRNO_SYS, and private_key_t::type.

ssh_agent_get_key()

asciichat_error_t ssh_agent_get_key	(	const public_key_t *	public_key,
		private_key_t *	key_out )

#include <include/ascii-chat/crypto/ssh/ssh_agent.h>

Retrieve a private key from ssh-agent by matching public key.

Parameters

public_key	Public key to match (must not be NULL)
key_out	Output private key structure (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Retrieves private key from SSH agent by sending SSH2_AGENTC_SIGN_REQUEST. This doesn't actually retrieve the private key material - instead it proves the key exists in the agent by attempting a signature operation.

Note

Agent requirement: SSH agent must be running and accessible. Returns error if agent is not available.

Key format: Only Ed25519 keys are supported.

Security: Private key never leaves ssh-agent. This function only verifies the key exists by matching the public key.

References ED25519_SIGNATURE_SIZE.

ssh_agent_has_key()

bool ssh_agent_has_key

(

const public_key_t *

public_key

)

#include <include/ascii-chat/crypto/ssh/ssh_agent.h>

Check if a public key is already in ssh-agent.

Parameters

public_key

Public key to check (must not be NULL)

Returns

true if key is in agent, false otherwise

Checks if public key is already in SSH agent by listing agent keys using SSH agent protocol.

Note

Agent requirement: SSH agent must be running and accessible. Returns false if agent is not available.

Key listing: Uses SSH agent protocol directly via lib/platform/pipe.h abstraction:

• Connects to agent via Unix domain socket (POSIX) or named pipe (Windows)
• Sends SSH2_AGENTC_REQUEST_IDENTITIES (11) message
• Receives SSH2_AGENT_IDENTITIES_ANSWER (12) response with key list
• Parses response to find matching Ed25519 public key (32-byte comparison)

Key matching: Compares raw Ed25519 public keys (32 bytes) directly. No fingerprint computation required - direct byte comparison.

Platform abstraction: Uses lib/platform/pipe.h for cross-platform communication:

• POSIX: Unix domain socket via SSH_AUTH_SOCK environment variable
• Windows: Named pipe via SSH_AUTH_SOCK or default \\.\pipe\openssh-ssh-agent

Warning

Agent requirement: SSH agent must be running and accessible. Returns false if agent connection fails (agent not running, wrong path, etc.).

Definition at line 54 of file ssh_agent.c.

                                                       {
  if (public_key == NULL) {
    log_warn("NULL is not a valid public key");
    return false;
  }
 
  // Use SSH agent protocol to list keys (works on both Windows and Unix)
  pipe_t pipe = ssh_agent_open_pipe();
  if (pipe == INVALID_PIPE_VALUE) {
    return false;
  }
 
  // Build SSH2_AGENTC_REQUEST_IDENTITIES message (type 11)
  unsigned char request[5];
  request[0] = 0; // length: 1 (4-byte big-endian)
  request[1] = 0;
  request[2] = 0;
  request[3] = 1;
  request[4] = 11; // SSH2_AGENTC_REQUEST_IDENTITIES
 
  // Send request
  ssize_t bytes_written = platform_pipe_write(pipe, request, 5);
  if (bytes_written != 5) {
    platform_pipe_close(pipe);
    return false;
  }
 
  // Read response
  unsigned char response[BUFFER_SIZE_XXXLARGE];
  ssize_t bytes_read = platform_pipe_read(pipe, response, sizeof(response));
  if (bytes_read < 9) {
    platform_pipe_close(pipe);
    return false;
  }
 
  platform_pipe_close(pipe);
 
  // Parse response: type should be SSH2_AGENT_IDENTITIES_ANSWER (12)
  uint8_t resp_type = response[4];
  if (resp_type != 12) {
    return false;
  }
 
  // Number of keys at bytes 5-8
  uint32_t num_keys = read_u32_be(response + 5);
 
  // Parse keys and check if our public key matches
  size_t pos = 9;
  for (uint32_t i = 0; i < num_keys && pos + 4 < (size_t)bytes_read; i++) {
    // Read key blob length
    uint32_t blob_len = read_u32_be(response + pos);
    pos += 4;
 
    if (pos + blob_len > (size_t)bytes_read)
      break;
 
    // Parse the blob to extract the Ed25519 public key
    size_t blob_pos = pos;
    // Skip key type string
    if (blob_pos + 4 > pos + blob_len) {
      pos += blob_len;
      continue;
    }
    uint32_t type_len = read_u32_be(response + blob_pos);
    blob_pos += 4 + type_len;
 
    // Read public key data
    if (blob_pos + 4 > pos + blob_len) {
      pos += blob_len;
      continue;
    }
    uint32_t pubkey_len = read_u32_be(response + blob_pos);
    blob_pos += 4;
 
    // Compare public key (should be 32 bytes for Ed25519)
    // Use constant-time comparison to prevent timing side channels
    if (pubkey_len == 32 && blob_pos + 32 <= pos + blob_len) {
      if (sodium_memcmp(response + blob_pos, public_key->key, 32) == 0) {
        log_debug("Found matching key in ssh-agent");
        return true;
      }
    }
 
    pos += blob_len;
 
    // Skip comment string length + comment
    if (pos + 4 > (size_t)bytes_read)
      break;
    uint32_t comment_len = read_u32_be(response + pos);
    pos += 4 + comment_len;
  }
 
  return false;
}

References BUFFER_SIZE_XXXLARGE, bytes_written, INVALID_PIPE_VALUE, public_key_t::key, log_debug, log_warn, platform_pipe_close(), platform_pipe_read(), and platform_pipe_write().

ssh_agent_is_available()

bool ssh_agent_is_available

(

void

)

#include <include/ascii-chat/crypto/ssh/ssh_agent.h>

Check if ssh-agent is running and available.

Returns

true if ssh-agent is available, false otherwise

Checks if SSH agent is running and accessible by verifying SSH_AUTH_SOCK environment variable.

Note

Agent detection:

• Checks SSH_AUTH_SOCK environment variable is set
• On Unix: Verifies socket exists and is accessible (access() with W_OK)
• On Windows: Only checks environment variable (named pipe accessibility checked at connection time)

Platform differences:

• Unix: Uses Unix domain socket (AF_UNIX) - can verify socket exists
• Windows: Uses named pipe - can't use access() on named pipes

Agent location:

• Unix: SSH_AUTH_SOCK points to Unix domain socket (e.g., /tmp/ssh-XXXXXXXX/agent.XXXXXX)
• Windows: SSH_AUTH_SOCK points to named pipe (e.g., \\.\pipe\openssh-ssh-agent)

Warning

Agent may not be running: Function checks environment variable but doesn't verify agent is actually running. Connection may fail later if agent is not running.

Windows limitation: Cannot verify named pipe accessibility without attempting connection. Function may return true even if agent is not running (connection will fail later).

Definition at line 42 of file ssh_agent.c.

                                  {
  /* Try to open the SSH agent connection */
  pipe_t pipe = ssh_agent_open_pipe();
  if (pipe != INVALID_PIPE_VALUE) {
    platform_pipe_close(pipe);
    log_dev("ssh-agent is available");
    return true;
  }
  log_dev("ssh-agent not available");
  return false;
}

References INVALID_PIPE_VALUE, log_dev, and platform_pipe_close().

ssh_agent_sign()

asciichat_error_t ssh_agent_sign	(	const public_key_t *	public_key,
		const uint8_t *	message,
		size_t	message_len,
		uint8_t	signature[64] )

#include <include/ascii-chat/crypto/ssh/ssh_agent.h>

Sign data using SSH agent with the specified public key.

Parameters

public_key	Public key to use for signing (must not be NULL)
message	Data to sign (must not be NULL)
message_len	Length of data to sign
signature	Output buffer for signature (must be 64 bytes for Ed25519)

Returns

ASCIICHAT_OK on success, error code on failure

Signs message data using SSH agent protocol SSH2_AGENTC_SIGN_REQUEST (message type 13).

Note

Agent requirement: SSH agent must be running and accessible, and must have the private key corresponding to public_key.

Only Ed25519 signatures are supported (64 bytes).

The public key must already be in the ssh-agent (check with ssh_agent_has_key first).

Definition at line 260 of file ssh_agent.c.

                                                                            {
  if (!public_key || !message || !signature) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: public_key=%p, message=%p, signature=%p", public_key,
                     message, signature);
  }
 
  if (public_key->type != KEY_TYPE_ED25519) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Only Ed25519 keys are supported for SSH agent signing");
  }
 
  // SSH agent protocol limits message size (typical OpenSSH agent limit is around 1MB)
  // Large messages can cause agent memory exhaustion or timeout
  if (message_len > 1024 * 1024) {
    return SET_ERRNO(ERROR_CRYPTO, "Message too large for SSH agent (max 1MB)");
  }
 
  // Connect to SSH agent
  pipe_t pipe = ssh_agent_open_pipe();
  if (pipe == INVALID_PIPE_VALUE) {
    return SET_ERRNO(ERROR_CRYPTO, "Cannot connect to ssh-agent");
  }
 
  // Build SSH2_AGENTC_SIGN_REQUEST message (type 13)
  // Format: uint32 length, byte type, string key_blob, string data, uint32 flags
  // For Ed25519, key_blob is: string "ssh-ed25519", string public_key(32 bytes)
 
  const char *key_type = "ssh-ed25519";
  uint32_t key_type_len = (uint32_t)strlen(key_type);
 
  // Calculate total message length
  // 1 (type) + 4 (key_blob_len) + key_blob_size + 4 (data_len) + data_size + 4 (flags)
  uint32_t key_blob_size = 4 + key_type_len + 4 + 32; // string(key_type) + string(pubkey)
  uint32_t total_len = 1 + 4 + key_blob_size + 4 + message_len + 4;
 
  uint8_t *buf = SAFE_MALLOC(total_len + 4, uint8_t *); // +4 for length prefix
  if (!buf) {
    platform_pipe_close(pipe);
    return SET_ERRNO(ERROR_CRYPTO, "Out of memory for SSH agent sign request");
  }
 
  uint32_t offset = 0;
 
  // Write total message length (excluding this 4-byte length field)
  write_u32_be(buf + offset, total_len);
  offset += 4;
 
  // Write message type (13 = SSH2_AGENTC_SIGN_REQUEST)
  buf[offset++] = 13;
 
  // Write key_blob length
  write_u32_be(buf + offset, key_blob_size);
  offset += 4;
 
  // Write key_blob: string(key_type)
  write_u32_be(buf + offset, key_type_len);
  offset += 4;
  // NOLINTNEXTLINE(bugprone-not-null-terminated-result) - binary data
  memcpy(buf + offset, key_type, key_type_len);
  offset += key_type_len;
 
  // Write key_blob: string(public_key)
  write_u32_be(buf + offset, 32);
  offset += 4;
  memcpy(buf + offset, public_key->key, ED25519_PUBLIC_KEY_SIZE);
  offset += 32;
 
  // Write data to sign
  write_u32_be(buf + offset, (uint32_t)message_len);
  offset += 4;
  memcpy(buf + offset, message, message_len);
  offset += (uint32_t)message_len;
 
  // Write flags (0 = default)
  write_u32_be(buf + offset, 0);
  offset += 4;
 
  // Send request
  ssize_t written = platform_pipe_write(pipe, buf, total_len + 4);
  sodium_memzero(buf, total_len + 4);
  SAFE_FREE(buf);
 
  if (written < 0 || (size_t)written != total_len + 4) {
    platform_pipe_close(pipe);
    return SET_ERRNO(ERROR_CRYPTO, "Failed to write SSH agent sign request");
  }
 
  // Read response
  uint8_t response[BUFFER_SIZE_XXLARGE];
  ssize_t read_bytes = platform_pipe_read(pipe, response, sizeof(response));
  platform_pipe_close(pipe);
 
  if (read_bytes < 5) {
    return SET_ERRNO(ERROR_CRYPTO, "Failed to read SSH agent sign response (read %zd bytes)", read_bytes);
  }
 
  // Response format: uint32 length, byte type, data...
  // We validate length implicitly by checking read_bytes and parsing the full response
  (void)read_u32_be(response); // Read but don't need explicit length check
  uint8_t response_type = response[4];
 
  // Check for SSH2_AGENT_SIGN_RESPONSE (14)
  if (response_type != 14) {
    if (response_type == 5) {
      return SET_ERRNO(ERROR_CRYPTO, "ssh-agent refused to sign (SSH_AGENT_FAILURE)");
    }
    return SET_ERRNO(ERROR_CRYPTO, "ssh-agent returned unexpected response type: %d (expected 14)", response_type);
  }
 
  // Parse signature blob
  // Response format: uint32 len, byte type(14), string signature_blob
  if (read_bytes < 9) {
    return SET_ERRNO(ERROR_CRYPTO, "SSH agent response too short (no signature blob length)");
  }
 
  uint32_t sig_blob_len = read_u32_be(response + 5);
  uint32_t expected_total = 4 + 1 + 4 + sig_blob_len;
 
  if ((size_t)read_bytes < expected_total) {
    return SET_ERRNO(ERROR_CRYPTO, "SSH agent response truncated (expected %u bytes, got %zd)", expected_total,
                     read_bytes);
  }
 
  // Signature blob format for Ed25519: string "ssh-ed25519", string signature(64 bytes)
  uint32_t offset_sig = 9;
  uint32_t sig_type_len = read_u32_be(response + offset_sig);
  offset_sig += 4;
 
  if (offset_sig + sig_type_len + 4 > (uint32_t)read_bytes) {
    return SET_ERRNO(ERROR_CRYPTO, "SSH agent signature blob truncated at signature type");
  }
 
  // Verify signature type is "ssh-ed25519"
  if (sig_type_len != 11 || memcmp(response + offset_sig, "ssh-ed25519", 11) != 0) {
    return SET_ERRNO(ERROR_CRYPTO, "SSH agent returned non-Ed25519 signature");
  }
  offset_sig += sig_type_len;
 
  // Read signature bytes
  uint32_t sig_len = read_u32_be(response + offset_sig);
  offset_sig += 4;
 
  if (sig_len != 64) {
    return SET_ERRNO(ERROR_CRYPTO, "SSH agent returned invalid Ed25519 signature length: %u (expected 64)", sig_len);
  }
 
  if (offset_sig + 64 > (uint32_t)read_bytes) {
    return SET_ERRNO(ERROR_CRYPTO, "SSH agent signature blob truncated at signature bytes");
  }
 
  // Copy signature to output
  memcpy(signature, response + offset_sig, ED25519_SIGNATURE_SIZE);
 
  log_debug("SSH agent successfully signed %zu bytes with Ed25519 key", message_len);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, BUFFER_SIZE_XXLARGE, ED25519_PUBLIC_KEY_SIZE, ED25519_SIGNATURE_SIZE, ERROR_CRYPTO, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, INVALID_PIPE_VALUE, public_key_t::key, KEY_TYPE_ED25519, log_debug, platform_pipe_close(), platform_pipe_read(), platform_pipe_write(), SAFE_FREE, SAFE_MALLOC, SET_ERRNO, and public_key_t::type.

Referenced by ed25519_sign_message().

Variable Documentation

buf

br_x509_trust_anchor* anchor_list::buf

Array of trust anchors (dynamically allocated)

Definition at line 80 of file pem.h.

Referenced by https_get().

len

size_t anchor_list::len

Total capacity of array

Definition at line 82 of file pem.h.

ptr

size_t anchor_list::ptr

Current number of trust anchors

Definition at line 81 of file pem.h.

Referenced by https_get().