Keys Module

🔑 SSH key, GPG key, and key validation APIs More...

Data Structures
struct	public_key_t
	Public key structure. More...
struct	private_key_t
	Private key structure (for server –ssh-key) More...

Typedefs
typedef struct crypto_handshake_context_t	crypto_handshake_context_t

Variables
key_type_t	public_key_t::type
uint8_t	public_key_t::key [32]
char	public_key_t::comment [256]
key_type_t	private_key_t::type
uint8_t   private_key_t::ed25519 [64]
uint8_t   private_key_t::x25519 [32]
union {
uint8_t   private_key_t::ed25519 [64]
uint8_t   private_key_t::x25519 [32]
}	private_key_t::key
bool	private_key_t::use_ssh_agent
bool	private_key_t::use_gpg_agent
uint8_t	private_key_t::public_key [32]
char	private_key_t::key_comment [256]
char	private_key_t::gpg_keygrip [64]

Key Type Definitions
enum	key_type_t { KEY_TYPE_UNKNOWN = 0 , KEY_TYPE_ED25519 , KEY_TYPE_X25519 , KEY_TYPE_GPG }
	Key type enumeration. More...

GPG Key Parsing
asciichat_error_t	parse_gpg_key (const char *gpg_key_text, public_key_t *key_out)
	Parse GPG key from armored text format.
asciichat_error_t	parse_gpg_key_binary (const uint8_t *gpg_key_binary, size_t key_size, public_key_t *key_out)
	Parse GPG key from binary format.
asciichat_error_t	validate_gpg_key_format (const char *gpg_key_text)
	Validate GPG key format and structure.
asciichat_error_t	extract_ed25519_from_gpg (const char *gpg_key_text, uint8_t ed25519_pk[32])
	Extract Ed25519 public key from GPG key.
asciichat_error_t	gpg_to_x25519_public (const char *gpg_key_text, uint8_t x25519_pk[32])
	Convert GPG key to X25519 for key exchange.

GPG Key Operations
asciichat_error_t	get_gpg_fingerprint (const char *gpg_key_text, uint8_t fingerprint_out[20])
	Get GPG key fingerprint.
asciichat_error_t	get_gpg_key_id (const char *gpg_key_text, uint8_t key_id_out[8])
	Get GPG key ID (short fingerprint)
asciichat_error_t	check_gpg_key_expiry (const char *gpg_key_text, bool *is_expired)
	Check if GPG key is expired.

GPG Key Formatting
asciichat_error_t	format_gpg_key_display (const char *gpg_key_text, char *output, size_t output_size)
	Format GPG key for display.
asciichat_error_t	extract_gpg_key_comment (const char *gpg_key_text, char *comment_out, size_t comment_size)
	Extract key comment/email from GPG key.

HTTPS Key Fetching
Fetch SSH/GPG keys from GitHub and GitLab using HTTPS (BearSSL). Requires network connectivity and valid usernames.
asciichat_error_t	fetch_github_ssh_keys (const char *username, char ***keys_out, size_t *num_keys)
	Fetch SSH keys from GitHub using HTTPS.
asciichat_error_t	fetch_gitlab_ssh_keys (const char *username, char ***keys_out, size_t *num_keys)
	Fetch SSH keys from GitLab using HTTPS.
asciichat_error_t	fetch_github_gpg_keys (const char *username, char ***keys_out, size_t *num_keys)
	Fetch GPG keys from GitHub using HTTPS.
asciichat_error_t	fetch_gitlab_gpg_keys (const char *username, char ***keys_out, size_t *num_keys)
	Fetch GPG keys from GitLab using HTTPS.

Key Parsing from HTTPS Responses
asciichat_error_t	parse_ssh_keys_from_response (const char *response_text, size_t response_len, char ***keys_out, size_t *num_keys, size_t max_keys)
	Parse SSH keys from HTTPS response text.
asciichat_error_t	parse_gpg_keys_from_response (const char *response_text, size_t response_len, char ***keys_out, size_t *num_keys, size_t max_keys)
	Parse GPG keys from HTTPS response text.

URL Construction
asciichat_error_t	build_github_ssh_url (const char *username, char *url_out, size_t url_size)
	Construct GitHub SSH keys URL.
asciichat_error_t	build_gitlab_ssh_url (const char *username, char *url_out, size_t url_size)
	Construct GitLab SSH keys URL.
asciichat_error_t	build_github_gpg_url (const char *username, char *url_out, size_t url_size)
	Construct GitHub GPG keys URL.
asciichat_error_t	build_gitlab_gpg_url (const char *username, char *url_out, size_t url_size)
	Construct GitLab GPG keys URL.

Public Key Parsing
asciichat_error_t	parse_public_key (const char *input, public_key_t *key_out)
	Parse SSH/GPG public key from any format (returns first key only)
asciichat_error_t	parse_public_keys (const char *input, public_key_t *keys_out, size_t *num_keys, size_t max_keys)
	Parse all SSH/GPG public keys from any format (returns all keys)

Private Key Parsing
asciichat_error_t	parse_private_key (const char *path, private_key_t *key_out)
	Parse SSH private key from file.

Key Conversion
asciichat_error_t	public_key_to_x25519 (const public_key_t *key, uint8_t x25519_pk[32])
	Convert public key to X25519 for Diffie-Hellman key exchange.
asciichat_error_t	private_key_to_x25519 (const private_key_t *key, uint8_t x25519_sk[32])
	Convert private key to X25519 for Diffie-Hellman key exchange.

Ed25519 Signing and Verification
asciichat_error_t	ed25519_sign_message (const private_key_t *key, const uint8_t *message, size_t message_len, uint8_t signature[64])
	Sign a message with Ed25519 (uses SSH agent if available, otherwise in-memory key)
asciichat_error_t	ed25519_verify_signature (const uint8_t public_key[32], const uint8_t *message, size_t message_len, const uint8_t signature[64], const char *gpg_key_id)
	Verify an Ed25519 signature.

Key Fetching (GitHub/GitLab)
Fetch SSH/GPG keys from GitHub and GitLab using HTTPS (BearSSL). Requires network connectivity and valid usernames.
asciichat_error_t	fetch_github_keys (const char *username, char ***keys_out, size_t *num_keys, bool use_gpg)
	Fetch SSH/GPG keys from GitHub using BearSSL.
asciichat_error_t	fetch_gitlab_keys (const char *username, char ***keys_out, size_t *num_keys, bool use_gpg)
	Fetch SSH/GPG keys from GitLab using BearSSL.

Key Parsing
asciichat_error_t	parse_keys_from_file (const char *path, public_key_t *keys, size_t *num_keys, size_t max_keys)
	Parse SSH keys from file (supports authorized_keys and known_hosts formats)

Key Formatting and Utilities
void	format_public_key (const public_key_t *key, char *output, size_t output_size)
	Convert public key to display format (ssh-ed25519 or x25519 hex)
asciichat_error_t	hex_decode (const char *hex, uint8_t *output, size_t output_len)
	Decode hex string to binary (utility function for testing)
asciichat_error_t	validate_ssh_key_file (const char *key_path)
	Validate SSH key file before parsing.

Key Validation
asciichat_error_t	validate_public_key (const public_key_t *key)
	Validate a public key structure.
asciichat_error_t	validate_private_key (const private_key_t *key)
	Validate a private key structure.
asciichat_error_t	check_key_expiry (const public_key_t *key, bool *is_expired)
	Check if a key is expired.
asciichat_error_t	validate_key_security (const char *key_path)
	Validate key permissions and security.

Key Format Validation
asciichat_error_t	validate_ssh_key_format (const char *key_text)
	Validate SSH key format.
asciichat_error_t	validate_x25519_key_format (const char *key_hex)
	Validate X25519 key format.

Key Security Checks
asciichat_error_t	check_key_strength (const public_key_t *key, bool *is_weak)
	Check if key has weak parameters.
asciichat_error_t	validate_key_permissions (const char *key_path)
	Validate key file permissions.
asciichat_error_t	check_key_patterns (const public_key_t *key, bool *has_weak_patterns)
	Check for key reuse or weak patterns.

Key Comparison and Matching
asciichat_error_t	compare_public_keys (const public_key_t *key1, const public_key_t *key2, bool *are_equal)
	Compare two public keys for equality.
asciichat_error_t	check_key_fingerprint (const public_key_t *key, const uint8_t *fingerprint, size_t fingerprint_len, bool *matches)
	Check if key matches a fingerprint.
asciichat_error_t	generate_key_fingerprint (const public_key_t *key, uint8_t *fingerprint_out, size_t fingerprint_size)
	Generate key fingerprint.

SSH Key Parsing
asciichat_error_t	parse_ssh_ed25519_line (const char *line, uint8_t ed25519_pk[32])
	Parse SSH Ed25519 public key from "ssh-ed25519 AAAAC3..." format.
asciichat_error_t	parse_ssh_private_key (const char *key_path, private_key_t *key_out)
	Parse SSH Ed25519 private key from file.

Key Conversion
asciichat_error_t	ed25519_to_x25519_public (const uint8_t ed25519_pk[32], uint8_t x25519_pk[32])
	Convert Ed25519 public key to X25519 for key exchange.
asciichat_error_t	ed25519_to_x25519_private (const uint8_t ed25519_sk[64], uint8_t x25519_sk[32])
	Convert Ed25519 private key to X25519 for key exchange.

Detailed Description

🔑 SSH key, GPG key, and key validation APIs

SSH key, GPG key, and key validation APIs.

This module handles GPG key parsing, validation, and conversion to X25519 for key exchange operations.

Warning

GPG SUPPORT IS CURRENTLY DISABLED: This code exists but many functions are not fully implemented. GPG key parsing may not work until GPG support is re-enabled and functions are completed.

Note

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

Key conversion: GPG Ed25519 keys are extracted and converted to X25519 for key exchange using libsodium's conversion functions.

OpenPGP format: Functions parse OpenPGP packet structure to extract Ed25519 public keys from GPG keys.

Author

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

Date

October 2025

This module handles fetching SSH and GPG keys from GitHub and GitLab using HTTPS requests with BearSSL for secure communication.

Note

Network operations: Requires network connectivity and valid usernames. May fail if network is unavailable or usernames don't exist.

TLS security: Uses BearSSL for HTTPS connections with system CA certificates. Validates server certificates against system trust store.

Key format: Only Ed25519 SSH keys are parsed from responses. Other key types (RSA, ECDSA) are skipped.

GPG support: GPG key fetching code exists but GPG parsing may not work until GPG support is re-enabled.

Author

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

Date

October 2025

This header contains the core key type definitions that can be shared between the main keys.h and the specialized key modules without circular dependencies.

All keys in this system are 32 bytes - Ed25519, X25519, and GPG-derived keys. This fixed size simplifies protocol design and key management.

Note

Key Type Restriction: Only Ed25519 and X25519 are supported. RSA and ECDSA are NOT supported due to libsodium limitations and protocol design requiring fixed-size keys.

GPG Support: GPG keys are parsed and converted to Ed25519/X25519 format. GPG agent support exists but is currently disabled.

Author

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

Date

October 2025

This header provides a unified interface for parsing SSH, GPG, and X25519 keys from various sources including files, URLs, and raw formats.

Supported input formats:

• SSH Ed25519 keys (ssh-ed25519 format)
• GitHub/GitLab SSH keys (fetched via HTTPS)
• GPG Ed25519 keys (from local keyring via gpg-agent)
• X25519 keys (raw hex or base64)
• File paths (reads first line and parses)

Note

All keys are normalized to 32-byte X25519 format for key exchange.

GPG support: GPG Ed25519 keys are fully supported via gpg-agent (requires gpg binary in PATH).

GitHub/GitLab fetching: Uses BearSSL for HTTPS requests.

Author

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

Date

October 2025

This module provides comprehensive key validation, security checks, and format verification for all supported key types.

Note

Key validation: Validates key structure, format, and security properties. Used before key operations to ensure keys are valid and secure.

Security checks: Includes permission checking, weak key detection, and pattern analysis for security vulnerabilities.

Key format validation: Validates SSH, GPG, and X25519 key formats. Returns error early if format is invalid.

Author

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

Date

October 2025

This module handles SSH Ed25519 key parsing, validation, and conversion to X25519 for key exchange operations.

Note

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

OpenSSH format: Supports OpenSSH private key format (openssh-key-v1). Supports encrypted and unencrypted keys.

Key conversion: Ed25519 keys are converted to X25519 for key exchange using libsodium's conversion functions.

Author

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

Date

October 2025

Key Management README

Overview

The Keys Module module provides comprehensive support for parsing, validating, and managing cryptographic keys from multiple sources and formats. It serves as the foundation for secure authentication and key exchange in ascii-chat.

Implementation: lib/crypto/keys/

Key Features:

• Unified key parsing from multiple sources (SSH, GPG, raw formats)
• Support for multiple key sources (files, GitHub, GitLab, raw hex/base64)
• Automatic key format detection and conversion
• Key validation and security checks
• SSH agent integration for secure signing
• Ed25519 to X25519 conversion for key exchange

Supported Key Formats

SSH Ed25519 Keys

Format: OpenSSH Ed25519 public and private keys

Public Key Format:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... comment

Private Key Format:

-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----

Supported Operations:

• Parse SSH public key from string
• Parse SSH private key from file
• Validate key file permissions
• Support for encrypted private keys (with password prompt)
• Convert Ed25519 to X25519 for key exchange

Example:

// Parse SSH public key from string
public_key_t pubkey;
asciichat_error_t err = parse_public_key(
    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... alice@example.com",
    &pubkey
);
 
// Parse SSH private key from file
private_key_t privkey;
err = parse_private_key("~/.ssh/id_ed25519", &privkey);

GPG Keys

Format: OpenPGP armored format (PEM-style)

Key Format:

-----BEGIN PGP PUBLIC KEY BLOCK-----
...
-----END PGP PUBLIC KEY BLOCK-----

Supported Operations:

• Parse GPG public key from keyring via gpg --list-keys and keygrip
• Extract Ed25519 public key via gpg-agent READKEY command
• Sign challenges using gpg-agent PKSIGN command (Assuan protocol)
• Verify signatures using gpg --verify for deterministic Ed25519
• Convert GPG Ed25519 keys to X25519 for key exchange
• Accept 8, 16, or 40 character key IDs (short, long, full fingerprint)

Requirements:

• Only Ed25519 GPG keys are supported (not RSA/DSA)
• gpg binary must be in PATH
• gpg-agent must be running for signing operations

Example:

// Parse GPG key by key ID
private_key_t privkey;
asciichat_error_t err = parse_private_key(
    "gpg:897607FA43DC66F612710AF97FE90A79F2E80ED3",
    &privkey
);
 
// Parse GPG key for server verification
public_key_t pubkey;
err = parse_public_key(
    "gpg:897607FA43DC66F612710AF97FE90A79F2E80ED3",
    &pubkey
);

Raw X25519 Keys

Format: 64 hex characters or base64-encoded 32-byte key

Supported Formats:

• Hex: 1234567890abcdef... (64 hex chars for 32 bytes)
• Base64: Base64-encoded 32-byte key

Example:

// Parse raw X25519 key from hex
public_key_t pubkey;
asciichat_error_t err = parse_public_key(
    "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    &pubkey
);

Key Sources

Local Files

Keys can be loaded from local files:

Public Keys:

// Load from .pub file (reads first line)
public_key_t pubkey;
asciichat_error_t err = parse_public_key("~/.ssh/id_ed25519.pub", &pubkey);
 
// Or read first line and parse manually
FILE *f = fopen("~/.ssh/id_ed25519.pub", "r");
char line[1024];
fgets(line, sizeof(line), f);
err = parse_public_key(line, &pubkey);
fclose(f);
 
// Load multiple keys from file (one per line)
public_key_t keys[10];
size_t num_keys;
err = parse_keys_from_file("~/.ssh/authorized_keys", keys, &num_keys, 10);
// File can contain multiple keys, one per line:
// ssh-ed25519 AAAAC3... alice@example.com
// ssh-ed25519 AAAAC3... bob@example.com

Private Keys:

// Load private key from file
private_key_t privkey;
asciichat_error_t err = parse_private_key("~/.ssh/id_ed25519", &privkey);
 
// File permissions are validated (warns if overly permissive)
// Encrypted keys prompt for password automatically

GitHub and GitLab Integration

Keys can be fetched directly from GitHub or GitLab using HTTPS:

SSH Keys:

// Fetch SSH keys from GitHub
char **keys;
size_t num_keys;
asciichat_error_t err = fetch_github_ssh_keys("username", &keys, &num_keys);
 
if (err == ASCIICHAT_OK && num_keys > 0) {
    // Parse first Ed25519 key
    public_key_t pubkey;
    parse_public_key(keys[0], &pubkey);
 
    // Free keys array
    for (size_t i = 0; i < num_keys; i++) {
        free(keys[i]);
    }
    free(keys);
}

GPG Keys:

// Fetch GPG keys from GitHub
char **keys;
size_t num_keys;
asciichat_error_t err = fetch_github_gpg_keys("username", &keys, &num_keys);

GitLab Support:

// Fetch SSH keys from GitLab
err = fetch_gitlab_ssh_keys("username", &keys, &num_keys);
 
// Fetch GPG keys from GitLab
err = fetch_gitlab_gpg_keys("username", &keys, &num_keys);

Unified Parsing:

// Parse key from GitHub using unified interface
public_key_t pubkey;
asciichat_error_t err = parse_public_key("github:username", &pubkey);
// Automatically fetches from https://github.com/username.keys
// Uses first Ed25519 key found
 
// Parse GPG key from GitHub
err = parse_public_key("github:username.gpg", &pubkey);
 
// Parse from GitLab
err = parse_public_key("gitlab:username", &pubkey);
err = parse_public_key("gitlab:username.gpg", &pubkey);

Unified Key Parsing

The parse_public_key() function supports multiple input formats automatically:

public_key_t pubkey;
asciichat_error_t err;
 
// SSH Ed25519 format
err = parse_public_key("ssh-ed25519 AAAAC3... comment", &pubkey);
 
// GitHub SSH keys
err = parse_public_key("github:username", &pubkey);
 
// GitLab SSH keys
err = parse_public_key("gitlab:username", &pubkey);
 
// GitHub GPG keys
err = parse_public_key("github:username.gpg", &pubkey);
 
// File path
err = parse_public_key("~/.ssh/id_ed25519.pub", &pubkey);
 
// Raw hex
err = parse_public_key("1234567890abcdef...", &pubkey);

Key Validation

Public Key Validation

All public keys are validated before use:

public_key_t pubkey;
asciichat_error_t err = parse_public_key(input, &pubkey);
 
// Validate key structure
err = validate_public_key(&pubkey);
if (err != ASCIICHAT_OK) {
    log_error("Invalid public key");
    return err;
}

Validation Checks:

• Key type is valid (Ed25519, X25519, or GPG)
• Key data is not all zeros
• Comment length is within limits (< 256 chars)
• Key size matches type (32 bytes for Ed25519/X25519)

Private Key Validation

Private keys are validated similarly:

private_key_t privkey;
asciichat_error_t err = parse_private_key("~/.ssh/id_ed25519", &privkey);
 
// Validate key structure
err = validate_private_key(&privkey);
if (err != ASCIICHAT_OK) {
    log_error("Invalid private key");
    return err;
}

Validation Checks:

• Key type is valid (Ed25519 or X25519)
• Key data is not all zeros
• Key size matches type (32 bytes for X25519, 64 bytes for Ed25519)
• Comment length is within limits

File Permission Validation

Private key files are checked for appropriate permissions:

// Validate SSH key file before parsing
asciichat_error_t err = validate_ssh_key_file("~/.ssh/id_ed25519");
 
// Checks:
// - File exists and is readable
// - File has valid SSH private key header
// - File permissions are appropriate (warns if overly permissive)

Permission Recommendations:

• Private keys should have restrictive permissions (0600 on Unix)
• Function warns if file has world-readable permissions
• Permission checking is Unix-specific (Windows doesn't have Unix-style permissions)

Key Conversion

Ed25519 to X25519 Conversion

Ed25519 keys are converted to X25519 format for Diffie-Hellman key exchange:

Public Key Conversion:

// Parse Ed25519 public key
public_key_t ed25519_pubkey;
parse_public_key("ssh-ed25519 AAAAC3...", &ed25519_pubkey);
 
// Convert to X25519 for key exchange
uint8_t x25519_pk[32];
asciichat_error_t err = public_key_to_x25519(&ed25519_pubkey, x25519_pk);
 
// Use x25519_pk for Diffie-Hellman key exchange

Private Key Conversion:

// Parse Ed25519 private key
private_key_t ed25519_privkey;
parse_private_key("~/.ssh/id_ed25519", &ed25519_privkey);
 
// Convert to X25519 for key exchange
uint8_t x25519_sk[32];
asciichat_error_t err = private_key_to_x25519(&ed25519_privkey, x25519_sk);
 
// Use x25519_sk for Diffie-Hellman key exchange

Conversion Details:

• Uses libsodium's conversion functions (crypto_sign_ed25519_pk_to_curve25519)
• Mathematically safe (same curve, different representation)
• Both Ed25519 and X25519 keys are 32 bytes
• Ed25519 private keys are 64 bytes (seed + public), extracts 32-byte seed for conversion

Direct Conversion Functions

Lower-level conversion functions are also available:

// Direct Ed25519 public key conversion
uint8_t ed25519_pk[32] = {...};
uint8_t x25519_pk[32];
asciichat_error_t err = ed25519_to_x25519_public(ed25519_pk, x25519_pk);
 
// Direct Ed25519 private key conversion
uint8_t ed25519_sk[64] = {...};  // seed + public
uint8_t x25519_sk[32];
asciichat_error_t err = ed25519_to_x25519_private(ed25519_sk, x25519_sk);

Signing and Verification

Signing Messages

Messages can be signed with Ed25519 private keys:

// Load private key
private_key_t privkey;
parse_private_key("~/.ssh/id_ed25519", &privkey);
 
// Sign message
const uint8_t message[] = "Hello, secure world!";
uint8_t signature[64];
asciichat_error_t err = ed25519_sign_message(
    &privkey,
    message,
    sizeof(message) - 1,  // Length without null terminator
    signature
);
 
// Use signature...

SSH Agent Support:

// If SSH agent is available, signing uses agent
// Key stays in agent (not loaded into memory)
// More secure - private key never touches application memory
 
// Configure key to use SSH agent
privkey.use_ssh_agent = true;
 
// Signing now uses SSH agent protocol
ed25519_sign_message(&privkey, message, message_len, signature);

Verifying Signatures

Signatures can be verified with Ed25519 public keys:

// Load public key
public_key_t pubkey;
parse_public_key("ssh-ed25519 AAAAC3...", &pubkey);
 
// Convert to raw Ed25519 public key
uint8_t ed25519_pk[32];
// ... extract from pubkey ...
 
// Verify signature
const uint8_t message[] = "Hello, secure world!";
uint8_t signature[64] = {...};  // From signing
 
asciichat_error_t err = ed25519_verify_signature(
    ed25519_pk,
    message,
    sizeof(message) - 1,
    signature
);
 
if (err == ASCIICHAT_OK) {
    log_info("Signature is valid!");
} else {
    log_error("Signature verification failed");
}

Security Features:

• Constant-time signature verification (prevents timing attacks)
• Automatic validation of signature format (must be 64 bytes)
• Returns error immediately if signature is invalid

Architecture

Module Structure

The key management module is organized into specialized submodules:

Core Modules:

• keys.h: Unified key parsing interface
• types.h: Key type definitions and structures
• validation.h: Key validation and security functions

Format-Specific Modules:

• ssh_keys.h: SSH Ed25519 key parsing
• gpg_keys.h: GPG key parsing (may be disabled)
• https_keys.h: HTTPS key fetching from GitHub/GitLab

Support Modules:

• pem_utils.h: PEM encoding/decoding utilities
• http_client.h: BearSSL HTTPS client for key fetching

Data Structures

Public Key Structure:

typedef struct {
    key_type_t type;        // KEY_TYPE_ED25519, KEY_TYPE_X25519, or KEY_TYPE_GPG
    uint8_t data[32];       // 32-byte public key
    char comment[256];     // Optional comment/label
} public_key_t;

Private Key Structure:

typedef struct {
    key_type_t type;        // KEY_TYPE_ED25519 or KEY_TYPE_X25519
    union {
        uint8_t x25519[32]; // X25519 private key (32 bytes)
        uint8_t ed25519[64]; // Ed25519 private key (seed + public, 64 bytes)
    } key;
    char comment[256];      // Optional comment/label
    bool use_ssh_agent;     // Use SSH agent for signing
    bool use_gpg_agent;     // Use GPG agent for signing (may be disabled)
} private_key_t;

Usage Examples

Basic Key Loading

#include "crypto/keys/keys.h"
 
// Load server public key
public_key_t server_pubkey;
asciichat_error_t err = parse_public_key(
    "github:server-username",
    &server_pubkey
);
if (err != ASCIICHAT_OK) {
    log_error("Failed to load server public key");
    return err;
}
 
// Validate key
err = validate_public_key(&server_pubkey);
if (err != ASCIICHAT_OK) {
    log_error("Invalid server public key");
    return err;
}
 
// Convert to X25519 for key exchange
uint8_t x25519_pk[32];
err = public_key_to_x25519(&server_pubkey, x25519_pk);

Client Authentication

// Load client private key
private_key_t client_privkey;
asciichat_error_t err = parse_private_key("~/.ssh/id_ed25519", &client_privkey);
 
// Try to use SSH agent if available
client_privkey.use_ssh_agent = true;
 
// Sign handshake challenge
uint8_t challenge[] = {...};  // From server
uint8_t signature[64];
err = ed25519_sign_message(
    &client_privkey,
    challenge,
    sizeof(challenge),
    signature
);
 
// Send signature to server
send_signature_to_server(signature);

Server Key Whitelist

Loading from file (recommended):

// Server: Load authorized client keys from file
// File can be authorized_keys format or .pub file with multiple entries (one per line)
public_key_t client_keys[MAX_CLIENTS];
size_t num_authorized = 0;
 
asciichat_error_t err = parse_client_keys(
    "~/.ssh/authorized_keys",  // File with multiple keys, one per line
    client_keys,
    &num_authorized,
    MAX_CLIENTS
);
// File format (one key per line):
// ssh-ed25519 AAAAC3... alice@example.com
// ssh-ed25519 AAAAC3... bob@example.com

Loading from array:

// Server: Load authorized client keys from array
const char *authorized_clients[] = {
    "github:alice",
    "github:bob",
    "ssh-ed25519 AAAAC3... charlie@example.com"
};
 
public_key_t client_keys[MAX_CLIENTS];
size_t num_authorized = 0;
 
for (size_t i = 0; i < sizeof(authorized_clients) / sizeof(authorized_clients[0]); i++) {
    if (parse_public_key(authorized_clients[i], &client_keys[num_authorized]) == ASCIICHAT_OK) {
        if (validate_public_key(&client_keys[num_authorized]) == ASCIICHAT_OK) {
            num_authorized++;
        }
    }
}

// Verify incoming client signatures against whitelist bool is_authorized = false; for (size_t i = 0; i < num_authorized; i++) { if (ed25519_verify_signature( client_keys[i].key, // .key field (32 bytes), not .data challenge, sizeof(challenge), signature ) == ASCIICHAT_OK) { is_authorized = true; break; } }

Security Considerations

File Permissions

Private Keys:

• Should have restrictive permissions (0600 on Unix)
• Function validates and warns if permissions are too permissive
• Never share private keys

Public Keys:

• Can be world-readable (no sensitive data)
• Still validate format before use

Key Storage

In-Memory Keys:

• Private keys in memory should be zeroed after use
• Use sodium_memzero() for secure memory clearing
• Avoid leaving keys in memory longer than necessary

SSH Agent:

• More secure: keys stay in agent process (isolated)
• Private keys never loaded into application memory
• Recommended for production use

GPG Agent:

• Similar security benefits to SSH agent
• Currently may be disabled (check build configuration)

Validation

Always Validate Keys:

• Check return values from parsing functions
• Explicitly validate keys before use
• Reject keys with all-zero data
• Verify key sizes match expected values

Zero Key Detection:

• Validation functions reject all-zero keys
• Zero keys are mathematically invalid
• Protects against accidentally using uninitialized keys

Limitations and Restrictions

Supported Key Types

Currently Supported:

• Ed25519 public and private keys (SSH format)
• X25519 keys (raw hex or base64)
• GPG Ed25519 keys (may be disabled)

Not Supported:

• RSA keys (any size)
• ECDSA keys (any curve)
• GPG RSA/ECDSA keys
• Other key formats

Rationale:

• libsodium only supports Ed25519/X25519
• Protocol assumes fixed-size keys (32 bytes public, 32/64 bytes private)
• RSA/ECDSA would require OpenSSL and protocol changes

GPG Support Status

Current Status:

• GPG key parsing code exists
• GPG support may be disabled in build configuration
• GPG agent support exists but may not be enabled

Workaround:

• Use SSH keys instead of GPG keys
• SSH keys provide equivalent functionality
• SSH agent support is fully functional

API Reference

Unified Key Parsing:

asciichat_error_t parse_public_key(const char *input, public_key_t *key_out);
asciichat_error_t parse_private_key(const char *path, private_key_t *key_out);

Key Validation:

asciichat_error_t validate_public_key(const public_key_t *key);
asciichat_error_t validate_private_key(const private_key_t *key);
asciichat_error_t validate_ssh_key_file(const char *key_path);

Key Conversion:

asciichat_error_t public_key_to_x25519(const public_key_t *key, uint8_t x25519_pk[32]);
asciichat_error_t private_key_to_x25519(const private_key_t *key, uint8_t x25519_sk[32]);
asciichat_error_t ed25519_to_x25519_public(const uint8_t ed25519_pk[32], uint8_t x25519_pk[32]);
asciichat_error_t ed25519_to_x25519_private(const uint8_t ed25519_sk[64], uint8_t x25519_sk[32]);

Signing and Verification:

asciichat_error_t ed25519_sign_message(const private_key_t *key, const uint8_t *message,
                                       size_t message_len, uint8_t signature[64]);
asciichat_error_t ed25519_verify_signature(const uint8_t public_key[32], const uint8_t *message,
                                           size_t message_len, const uint8_t signature[64]);

HTTPS Key Fetching:

asciichat_error_t fetch_github_ssh_keys(const char *username, char ***keys_out, size_t *num_keys);
asciichat_error_t fetch_gitlab_ssh_keys(const char *username, char ***keys_out, size_t *num_keys);
asciichat_error_t fetch_github_gpg_keys(const char *username, char ***keys_out, size_t *num_keys);
asciichat_error_t fetch_gitlab_gpg_keys(const char *username, char ***keys_out, size_t *num_keys);

See also

crypto/keys/keys.h

crypto/keys/types.h

crypto/keys/validation.h

crypto/keys/ssh_keys.h

crypto/keys/gpg_keys.h

crypto/keys/https_keys.h

Typedef Documentation

crypto_handshake_context_t

typedef struct crypto_handshake_context_t crypto_handshake_context_t

#include <keys.h>

Definition at line 526 of file keys.h.

Enumeration Type Documentation

key_type_t

enum key_type_t

#include <key_types.h>

Key type enumeration.

Represents the type of cryptographic key being used. All keys are ultimately converted to X25519 for key exchange.

Note

RSA and ECDSA are NOT supported because:

• libsodium (our crypto library) only supports Ed25519/X25519
• RSA/ECDSA require variable-length keys and signatures
• Protocol assumes fixed 128-byte authenticated handshake (ephemeral:32 + identity:32 + sig:64)
• Adding RSA/ECDSA support would require OpenSSL and protocol changes

Enumerator
KEY_TYPE_UNKNOWN	Unknown or invalid key type
KEY_TYPE_ED25519	SSH Ed25519 key (converts to X25519 for key exchange)
KEY_TYPE_X25519	Native X25519 key (raw hex or base64)
KEY_TYPE_GPG	GPG key (Ed25519 variant, derived to X25519)

Definition at line 50 of file key_types.h.

             {
  KEY_TYPE_UNKNOWN = 0, 
  KEY_TYPE_ED25519,     
  KEY_TYPE_X25519,      
  KEY_TYPE_GPG          
} key_type_t;

Function Documentation

build_github_gpg_url()

asciichat_error_t build_github_gpg_url	(	const char *	username,
		char *	url_out,
		size_t	url_size
	)

#include <https_keys.h>

Construct GitHub GPG keys URL.

Parameters

username	GitHub username (must not be NULL)
url_out	Output buffer for URL (must not be NULL)
url_size	Size of URL buffer (must be >= 64)

Returns

ASCIICHAT_OK on success, error code on failure

Constructs GitHub GPG keys URL: https://github.com/username.gpg

Note

URL format: Uses standard GitHub GPG keys endpoint. Format: "https://github.com/{username}.gpg"

Buffer requirements: URL buffer must be at least 64 bytes (same as build_github_ssh_url).

Warning

URL buffer must be large enough for formatted URL.

Definition at line 116 of file https_keys.c.

                                                                                             {
  if (!username || !url_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: username=%p, url_out=%p", username, url_out);
    return ERROR_INVALID_PARAM;
  }
 
  if (url_size < 64) {
    SET_ERRNO(ERROR_INVALID_PARAM, "URL buffer too small: %zu (minimum 64)", url_size);
    return ERROR_INVALID_PARAM;
  }
 
  // Strip .gpg suffix if user already included it (e.g., "github:zfogg.gpg")
  char clean_username[256];
  SAFE_STRNCPY(clean_username, username, sizeof(clean_username) - 1);
  size_t len = strlen(clean_username);
  if (len > 4 && strcmp(clean_username + len - 4, ".gpg") == 0) {
    clean_username[len - 4] = '\0'; // Remove .gpg suffix
  }
 
  // Construct GitHub GPG keys URL: https://github.com/username.gpg
  int result = safe_snprintf(url_out, url_size, "https://github.com/%s.gpg", clean_username);
  if (result < 0 || result >= (int)url_size) {
    SET_ERRNO(ERROR_STRING, "Failed to construct GitHub GPG URL");
    return ERROR_STRING;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_STRING, safe_snprintf(), SAFE_STRNCPY, and SET_ERRNO.

Referenced by fetch_github_gpg_keys().

build_github_ssh_url()

asciichat_error_t build_github_ssh_url	(	const char *	username,
		char *	url_out,
		size_t	url_size
	)

#include <https_keys.h>

Construct GitHub SSH keys URL.

Parameters

username	GitHub username (must not be NULL)
url_out	Output buffer for URL (must not be NULL)
url_size	Size of URL buffer (must be >= 64)

Returns

ASCIICHAT_OK on success, error code on failure

Constructs GitHub SSH keys URL: https://github.com/username.keys

Note

URL format: Uses standard GitHub SSH keys endpoint. Format: "https://github.com/{username}.keys"

Buffer requirements: URL buffer must be at least 64 bytes. Format: "https://github.com/" (19 chars) + username + ".keys" (6 chars) = 25 + username length

Warning

URL buffer must be large enough for formatted URL. Function validates buffer size but may overflow if buffer is too small.

Definition at line 74 of file https_keys.c.

                                                                                             {
  if (!username || !url_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: username=%p, url_out=%p", username, url_out);
    return ERROR_INVALID_PARAM;
  }
 
  if (url_size < 64) {
    SET_ERRNO(ERROR_INVALID_PARAM, "URL buffer too small: %zu (minimum 64)", url_size);
    return ERROR_INVALID_PARAM;
  }
 
  // Construct GitHub SSH keys URL: https://github.com/username.keys
  int result = safe_snprintf(url_out, url_size, "https://github.com/%s.keys", username);
  if (result < 0 || result >= (int)url_size) {
    SET_ERRNO(ERROR_STRING, "Failed to construct GitHub SSH URL");
    return ERROR_STRING;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_STRING, safe_snprintf(), and SET_ERRNO.

Referenced by fetch_github_ssh_keys().

build_gitlab_gpg_url()

asciichat_error_t build_gitlab_gpg_url	(	const char *	username,
		char *	url_out,
		size_t	url_size
	)

#include <https_keys.h>

Construct GitLab GPG keys URL.

Parameters

username	GitLab username (must not be NULL)
url_out	Output buffer for URL (must not be NULL)
url_size	Size of URL buffer (must be >= 64)

Returns

ASCIICHAT_OK on success, error code on failure

Constructs GitLab GPG keys URL: https://gitlab.com/username.gpg

Note

URL format: Uses standard GitLab GPG keys endpoint. Format: "https://gitlab.com/{username}.gpg"

Buffer requirements: URL buffer must be at least 64 bytes (same as build_gitlab_ssh_url).

Warning

URL buffer must be large enough for formatted URL.

Definition at line 145 of file https_keys.c.

                                                                                             {
  if (!username || !url_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: username=%p, url_out=%p", username, url_out);
    return ERROR_INVALID_PARAM;
  }
 
  if (url_size < 64) {
    SET_ERRNO(ERROR_INVALID_PARAM, "URL buffer too small: %zu (minimum 64)", url_size);
    return ERROR_INVALID_PARAM;
  }
 
  // Strip .gpg suffix if user already included it (e.g., "gitlab:zfogg.gpg")
  char clean_username[256];
  SAFE_STRNCPY(clean_username, username, sizeof(clean_username) - 1);
  size_t len = strlen(clean_username);
  if (len > 4 && strcmp(clean_username + len - 4, ".gpg") == 0) {
    clean_username[len - 4] = '\0'; // Remove .gpg suffix
  }
 
  // Construct GitLab GPG keys URL: https://gitlab.com/username.gpg
  int result = safe_snprintf(url_out, url_size, "https://gitlab.com/%s.gpg", clean_username);
  if (result < 0 || result >= (int)url_size) {
    SET_ERRNO(ERROR_STRING, "Failed to construct GitLab GPG URL");
    return ERROR_STRING;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_STRING, safe_snprintf(), SAFE_STRNCPY, and SET_ERRNO.

Referenced by fetch_gitlab_gpg_keys().

build_gitlab_ssh_url()

asciichat_error_t build_gitlab_ssh_url	(	const char *	username,
		char *	url_out,
		size_t	url_size
	)

#include <https_keys.h>

Construct GitLab SSH keys URL.

Parameters

username	GitLab username (must not be NULL)
url_out	Output buffer for URL (must not be NULL)
url_size	Size of URL buffer (must be >= 64)

Returns

ASCIICHAT_OK on success, error code on failure

Constructs GitLab SSH keys URL: https://gitlab.com/username.keys

Note

URL format: Uses standard GitLab SSH keys endpoint. Format: "https://gitlab.com/{username}.keys"

Buffer requirements: URL buffer must be at least 64 bytes (same as build_github_ssh_url).

Warning

URL buffer must be large enough for formatted URL.

Definition at line 95 of file https_keys.c.

                                                                                             {
  if (!username || !url_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: username=%p, url_out=%p", username, url_out);
    return ERROR_INVALID_PARAM;
  }
 
  if (url_size < 64) {
    SET_ERRNO(ERROR_INVALID_PARAM, "URL buffer too small: %zu (minimum 64)", url_size);
    return ERROR_INVALID_PARAM;
  }
 
  // Construct GitLab SSH keys URL: https://gitlab.com/username.keys
  int result = safe_snprintf(url_out, url_size, "https://gitlab.com/%s.keys", username);
  if (result < 0 || result >= (int)url_size) {
    SET_ERRNO(ERROR_STRING, "Failed to construct GitLab SSH URL");
    return ERROR_STRING;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_STRING, safe_snprintf(), and SET_ERRNO.

Referenced by fetch_gitlab_ssh_keys().

check_gpg_key_expiry()

asciichat_error_t check_gpg_key_expiry	(	const char *	gpg_key_text,
		bool *	is_expired
	)

#include <gpg_keys.h>

Check if GPG key is expired.

Parameters

gpg_key_text	GPG key in armored format (must not be NULL)
is_expired	Output: true if key is expired, false otherwise (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Checks if GPG key has expired by parsing expiration date from key structure.

Note

Expiration checking: Parses OpenPGP packet structure to find expiration date. Compares expiration date with current date.

Default behavior: Currently defaults to not expired if parsing fails. Function returns error but sets is_expired to false.

Warning

NOT YET IMPLEMENTED: This function is not yet implemented. Returns ERROR_CRYPTO_KEY with "GPG key expiry checking not yet implemented". Defaults is_expired to false before returning error.

GPG support is currently disabled. Function will not work until implemented.

Definition at line 164 of file gpg_keys.c.

                                                                                   {
  if (!gpg_key_text || !is_expired) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: gpg_key_text=%p, is_expired=%p", gpg_key_text, is_expired);
    return ERROR_INVALID_PARAM;
  }
 
  // For GPG key expiry checking, we need a key ID
  // If gpg_key_text is a key ID (8, 16, or 40 hex chars), use it directly
  // Otherwise, we'd need to parse the GPG armored text (complex)
  size_t key_len = strlen(gpg_key_text);
  const char *key_id = gpg_key_text;
 
  // Check if it looks like a key ID (hex characters only)
  bool is_hex = true;
  for (size_t i = 0; i < key_len; i++) {
    if (!((gpg_key_text[i] >= '0' && gpg_key_text[i] <= '9') || (gpg_key_text[i] >= 'A' && gpg_key_text[i] <= 'F') ||
          (gpg_key_text[i] >= 'a' && gpg_key_text[i] <= 'f'))) {
      is_hex = false;
      break;
    }
  }
 
  // Only support key ID format (8, 16, or 40 hex chars)
  if (!is_hex || (key_len != 8 && key_len != 16 && key_len != 40)) {
    log_warn("check_gpg_key_expiry: Input is not a key ID format (expected 8/16/40 hex chars)");
    *is_expired = false; // Assume not expired if we can't check
    return ASCIICHAT_OK;
  }
 
  // Use gpg --list-keys with colon-separated output to check expiry
  char cmd[512];
  safe_snprintf(cmd, sizeof(cmd), "gpg --list-keys --with-colons %s 2>/dev/null", key_id);
 
  FILE *fp = SAFE_POPEN(cmd, "r");
  if (!fp) {
    log_error("Failed to run gpg --list-keys for key %s", key_id);
    *is_expired = false; // Assume not expired if we can't check
    return ASCIICHAT_OK;
  }
 
  char line[1024];
  bool found_pub = false;
  *is_expired = false;
 
  // Parse colon-separated output
  // Format: pub:trust:keylen:algo:keyid:creation:expiry:...
  // Field 6 is expiry timestamp (seconds since epoch), or empty if no expiry
  while (fgets(line, sizeof(line), fp)) {
    if (strncmp(line, "pub:", 4) == 0) {
      found_pub = true;
 
      // Split line by colons
      char *fields[12];
      int field_count = 0;
      char *ptr = line;
      char *field_start = ptr;
 
      while (*ptr && field_count < 12) {
        if (*ptr == ':' || *ptr == '\n') {
          *ptr = '\0';
          fields[field_count++] = field_start;
          field_start = ptr + 1;
        }
        ptr++;
      }
 
      // Field 6 is expiry date (index 6)
      if (field_count >= 7 && strlen(fields[6]) > 0) {
        // Parse expiry timestamp
        long expiry_timestamp = atol(fields[6]);
        time_t now = time(NULL);
 
        if (expiry_timestamp > 0 && expiry_timestamp < now) {
          *is_expired = true;
          log_warn("GPG key %s has expired (expiry: %ld, now: %ld)", key_id, expiry_timestamp, (long)now);
        } else if (expiry_timestamp > 0) {
          log_debug("GPG key %s expires at timestamp %ld (valid)", key_id, expiry_timestamp);
        } else {
          log_debug("GPG key %s has no expiration date", key_id);
        }
      } else {
        log_debug("GPG key %s has no expiration date (field empty)", key_id);
      }
 
      break; // Found the pub line, stop parsing
    }
  }
 
  SAFE_PCLOSE(fp);
 
  if (!found_pub) {
    log_warn("Could not find GPG key %s in keyring", key_id);
    *is_expired = false; // Assume not expired if key not found
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, log_debug, log_error, log_warn, SAFE_PCLOSE, SAFE_POPEN, safe_snprintf(), and SET_ERRNO.

check_key_expiry()

asciichat_error_t check_key_expiry	(	const public_key_t *	key,
		bool *	is_expired
	)

#include <keys_validation.h>

Check if a key is expired.

Parameters

key	Key to check (must not be NULL)
is_expired	Output: true if expired, false otherwise (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Checks if key has expired by parsing expiration date from key structure.

Note

Expiration checking: Would parse key creation dates and expiration times from key structure. Currently not implemented.

Current implementation: Always returns false (not expired). Key expiry checking is not yet implemented.

Warning

NOT YET IMPLEMENTED: This function always returns false (not expired). Key expiry checking is not yet implemented.

Definition at line 110 of file keys_validation.c.

                                                                              {
  if (!key || !is_expired) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key=%p, is_expired=%p", key, is_expired);
    return ERROR_INVALID_PARAM;
  }
 
  // For now, we don't implement key expiry checking
  // This would require parsing key creation dates and expiration times
  *is_expired = false;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, and SET_ERRNO.

check_key_fingerprint()

asciichat_error_t check_key_fingerprint	(	const public_key_t *	key,
		const uint8_t *	fingerprint,
		size_t	fingerprint_len,
		bool *	matches
	)

#include <keys_validation.h>

Check if key matches a fingerprint.

Parameters

key	Key to check (must not be NULL)
fingerprint	Fingerprint to match against (must not be NULL)
fingerprint_len	Length of fingerprint (must be > 0)
matches	Output: true if fingerprint matches, false otherwise (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Checks if key matches a fingerprint by computing key fingerprint and comparing.

Note

Fingerprint comparison: Computes key fingerprint using generate_key_fingerprint() and compares with provided fingerprint using constant-time comparison.

Constant-time: Uses constant-time comparison to prevent timing attacks.

Fingerprint format: Fingerprint is typically SHA-256 hash of key material. Length depends on hash algorithm used (typically 32 bytes for SHA-256).

Warning

Always uses constant-time comparison for fingerprints. Do NOT use regular memcmp() for fingerprint comparison.

Definition at line 435 of file keys_validation.c.

                                                       {
  if (!key || !fingerprint || !matches) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key=%p, fingerprint=%p, matches=%p", key, fingerprint, matches);
    return ERROR_INVALID_PARAM;
  }
 
  *matches = false;
 
  // Generate fingerprint for the key
  uint8_t key_fingerprint[32];
  asciichat_error_t fingerprint_result = generate_key_fingerprint(key, key_fingerprint, 32);
  if (fingerprint_result != ASCIICHAT_OK) {
    return fingerprint_result;
  }
 
  // Compare fingerprints
  size_t compare_len = (fingerprint_len < 32) ? fingerprint_len : 32;
  if (sodium_memcmp(key_fingerprint, fingerprint, compare_len) == 0) {
    *matches = true;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, generate_key_fingerprint(), and SET_ERRNO.

check_key_patterns()

asciichat_error_t check_key_patterns	(	const public_key_t *	key,
		bool *	has_weak_patterns
	)

#include <keys_validation.h>

Check for key reuse or weak patterns.

Parameters

key	Key to check (must not be NULL)
has_weak_patterns	Output: true if weak patterns found, false otherwise (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Checks key for weak patterns that could indicate security vulnerabilities. Detects keys with predictable or weak patterns.

Note

Pattern analysis: Would analyze key material for weak patterns. Currently not fully implemented.

Weak patterns: Would detect:

• Keys with repeated patterns
• Keys with low entropy
• Keys matching known weak patterns

Warning

NOT YET FULLY IMPLEMENTED: Weak pattern detection is not yet fully implemented. Function may always return false (no weak patterns).

Definition at line 320 of file keys_validation.c.

                                                                                       {
  if (!key || !has_weak_patterns) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key=%p, has_weak_patterns=%p", key, has_weak_patterns);
    return ERROR_INVALID_PARAM;
  }
 
  *has_weak_patterns = false;
 
  // Check for sequential patterns
  bool is_sequential = true;
  for (int i = 1; i < 32; i++) {
    if (key->key[i] != key->key[i - 1] + 1) {
      is_sequential = false;
      break;
    }
  }
 
  if (is_sequential) {
    *has_weak_patterns = true;
    return ASCIICHAT_OK;
  }
 
  // Check for repeated byte patterns (e.g., all 0xAA, all 0x55)
  // Common weak patterns to check
  const uint8_t weak_bytes[] = {0x00, 0xFF, 0xAA, 0x55, 0x11, 0x22, 0x33, 0x44,
                                0x66, 0x77, 0x88, 0x99, 0xBB, 0xCC, 0xDD, 0xEE};
  for (size_t pattern_idx = 0; pattern_idx < sizeof(weak_bytes); pattern_idx++) {
    uint8_t pattern_byte = weak_bytes[pattern_idx];
    bool is_repeated = true;
    for (size_t j = 0; j < 32; j++) {
      // CORRECT: Compare against pattern_byte, not key->key[0]
      if (key->key[j] != pattern_byte) {
        is_repeated = false;
        break;
      }
    }
    if (is_repeated) {
      *has_weak_patterns = true;
      return ASCIICHAT_OK;
    }
  }
 
  // Check for alternating bit patterns (e.g., 0xAA 0xBB 0xAA 0xBB or 0x55 0xAA 0x55 0xAA)
  // A proper alternating pattern has at most 2 unique byte values that truly alternate
  bool byte_appeared[256] = {0};
  int unique_values = 0;
  for (size_t i = 0; i < 32; i++) {
    if (!byte_appeared[key->key[i]]) {
      byte_appeared[key->key[i]] = true;
      unique_values++;
    }
  }
 
  // Only consider it weak if there are 2 or fewer unique values AND they properly alternate
  if (unique_values <= 2) {
    bool is_alternating = true;
    for (size_t i = 1; i < 32; i++) {
      // In a true alternating pattern:
      // 1. Adjacent bytes must be different
      // 2. Pattern must repeat every 2 bytes (byte[i] == byte[i-2])
      if (key->key[i] == key->key[i - 1] || (i >= 2 && key->key[i] != key->key[i - 2])) {
        is_alternating = false;
        break;
      }
    }
    if (is_alternating) {
      *has_weak_patterns = true;
      return ASCIICHAT_OK;
    }
  }
 
  // Check for common cryptographic initialization patterns
  // OpenSSL weak keys, old Debian SSH keys, etc.
  uint32_t *words = (uint32_t *)key->key;
  // Check if all 32-bit words are identical
  bool all_words_same = true;
  for (size_t i = 1; i < 8; i++) {
    if (words[i] != words[0]) {
      all_words_same = false;
      break;
    }
  }
  if (all_words_same) {
    *has_weak_patterns = true;
    return ASCIICHAT_OK;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, public_key_t::key, and SET_ERRNO.

check_key_strength()

asciichat_error_t check_key_strength	(	const public_key_t *	key,
		bool *	is_weak
	)

#include <keys_validation.h>

Check if key has weak parameters.

Parameters

key	Key to check (must not be NULL)
is_weak	Output: true if weak, false otherwise (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Checks if key has weak cryptographic parameters. Detects keys with weak entropy or predictable patterns.

Note

Weak key detection: Would analyze key material for weak patterns. Currently not fully implemented.

Security analysis: Would check for:

• Low entropy keys
• Predictable patterns
• Known weak keys

Warning

NOT YET FULLY IMPLEMENTED: Weak key detection is not yet fully implemented. Function may always return false (not weak).

Definition at line 247 of file keys_validation.c.

                                                                             {
  if (!key || !is_weak) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key=%p, is_weak=%p", key, is_weak);
    return ERROR_INVALID_PARAM;
  }
 
  *is_weak = false;
 
  // Check for all zeros (already checked in validate_public_key)
  // Check for all ones
  bool is_ones = true;
  for (int i = 0; i < 32; i++) {
    if (key->key[i] != 0xFF) {
      is_ones = false;
      break;
    }
  }
 
  if (is_ones) {
    *is_weak = true;
    return ASCIICHAT_OK;
  }
 
  // Check for low entropy: Count unique bytes
  // A properly random 32-byte key should have ~24-32 unique values
  // Low entropy keys will have very few unique bytes
  bool byte_seen[256] = {0};
  int unique_bytes = 0;
  for (int i = 0; i < 32; i++) {
    uint8_t byte_val = key->key[i];
    if (!byte_seen[byte_val]) {
      byte_seen[byte_val] = true;
      unique_bytes++;
    }
  }
 
  // If less than 8 unique bytes in 32 bytes, entropy is very low
  // This indicates non-random key generation (e.g., PRNG seed not properly initialized)
  if (unique_bytes < 8) {
    *is_weak = true;
    return ASCIICHAT_OK;
  }
 
  // Additional weak key pattern detection:
  // - Check for repeated patterns (handled in check_key_patterns)
  // - Check for known weak sequences (see check_key_patterns)
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, public_key_t::key, and SET_ERRNO.

compare_public_keys()

asciichat_error_t compare_public_keys	(	const public_key_t *	key1,
		const public_key_t *	key2,
		bool *	are_equal
	)

#include <keys_validation.h>

Compare two public keys for equality.

Parameters

key1	First key to compare (must not be NULL)
key2	Second key to compare (must not be NULL)
are_equal	Output: true if keys are equal, false otherwise (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Compares two public keys for equality using constant-time comparison. Compares key type and key data.

Note

Key comparison: Compares key type and 32-byte key data. Uses constant-time comparison to prevent timing attacks.

Constant-time: Uses sodium_memcmp() for constant-time comparison. Prevents timing attacks that could leak key information.

Comment comparison: Comments are NOT compared. Only key type and key data are compared.

Warning

Always uses constant-time comparison for keys. Do NOT use regular memcmp() for key comparison.

Definition at line 414 of file keys_validation.c.

                                                                                                           {
  if (!key1 || !key2 || !are_equal) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key1=%p, key2=%p, are_equal=%p", key1, key2, are_equal);
    return ERROR_INVALID_PARAM;
  }
 
  *are_equal = false;
 
  // Compare key types
  if (key1->type != key2->type) {
    return ASCIICHAT_OK;
  }
 
  // Compare key data using constant-time comparison
  if (sodium_memcmp(key1->key, key2->key, 32) == 0) {
    *are_equal = true;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, public_key_t::key, SET_ERRNO, and public_key_t::type.

ed25519_sign_message()

asciichat_error_t ed25519_sign_message	(	const private_key_t *	key,
		const uint8_t *	message,
		size_t	message_len,
		uint8_t	signature[64]
	)

#include <keys.h>

Sign a message with Ed25519 (uses SSH agent if available, otherwise in-memory key)

Sign a message with Ed25519 private key.

Parameters

key	Private key for signing (must not be NULL)
message	Message to sign (must not be NULL)
message_len	Length of message to sign
signature	Output buffer for Ed25519 signature (64 bytes)

Returns

ASCIICHAT_OK on success, error code on failure

Signs a message using Ed25519. This is the main signing function that abstracts SSH agent vs in-memory signing.

Note

Agent support: If use_ssh_agent is true, uses SSH agent for signing. Key stays in agent (not loaded into memory). Signing happens via agent protocol.

In-memory signing: If use_ssh_agent is false, uses in-memory key for signing. Key must be loaded into memory (via parse_private_key()).

Setting use_gpg_agent=true will not work until GPG support is re-enabled.

Note

Signature format: Ed25519 signature is always 64 bytes (R || S format).

Warning

Agent availability: If use_ssh_agent is true but SSH agent is not available, function returns error. Check SSH agent availability before using.

exists but will not work until GPG support is re-enabled.

Parameters

key	Ed25519 private key (must not be NULL)
message	Message to sign (must not be NULL)
message_len	Length of message to sign
signature	Output buffer for Ed25519 signature (64 bytes, must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Signs a message using Ed25519. Uses SSH agent if available, otherwise in-memory key.

Note

Agent support: If use_ssh_agent is true, uses SSH agent for signing. Key stays in agent (not loaded into memory). Signing happens via agent protocol.

In-memory signing: If use_ssh_agent is false, uses in-memory key for signing. Key must be loaded into memory (via parse_ssh_private_key()).

Signature format: Ed25519 signature is always 64 bytes (R || S format).

Warning

Agent availability: If use_ssh_agent is true but SSH agent is not available, function returns error. Check SSH agent availability before using.

Definition at line 1067 of file ssh_keys.c.

                                                              {
  if (!key || !message || !signature) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key=%p, message=%p, signature=%p", key, message,
                     signature);
  }
 
  if (key->type != KEY_TYPE_ED25519) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Key is not an Ed25519 key");
  }
 
  // If using GPG agent, delegate signing to GPG agent
  if (key->use_gpg_agent) {
    log_debug("Using GPG agent for Ed25519 signing (keygrip: %.40s)", key->gpg_keygrip);
 
    // Connect to GPG agent
    int agent_sock = gpg_agent_connect();
    log_debug("GPG agent connection result: %d", agent_sock);
 
    if (agent_sock < 0) {
      log_info("GPG agent not available, falling back to gpg --detach-sign for signing");
 
      // Extract GPG key ID from key comment ("GPG key <key_id>")
      const char *key_id_prefix = "GPG key ";
      const char *key_id = NULL;
      if (strncmp(key->key_comment, key_id_prefix, strlen(key_id_prefix)) == 0) {
        key_id = key->key_comment + strlen(key_id_prefix);
      }
 
      log_debug("Extracted GPG key ID: %s (len=%zu)", key_id ? key_id : "NULL", key_id ? strlen(key_id) : 0);
 
      if (!key_id || strlen(key_id) != 16) {
        return SET_ERRNO(ERROR_CRYPTO, "Cannot extract GPG key ID from comment for fallback signing");
      }
 
      // Use gpg --detach-sign fallback
      log_debug("Calling gpg_sign_detached_ed25519 with key %s", key_id);
      int result = gpg_sign_detached_ed25519(key_id, message, message_len, signature);
      log_debug("gpg_sign_detached_ed25519 result: %d", result);
 
      if (result != 0) {
        return SET_ERRNO(ERROR_CRYPTO, "GPG fallback signing failed (both agent and gpg command failed)");
      }
 
      log_info("Successfully signed message with gpg --detach-sign fallback (64 bytes)");
      return ASCIICHAT_OK;
    }
 
    log_debug("Using GPG agent for signing");
 
    // Sign the message using GPG agent
    size_t sig_len = 0;
    int result = gpg_agent_sign(agent_sock, key->gpg_keygrip, message, message_len, signature, &sig_len);
 
    // Disconnect from agent
    gpg_agent_disconnect(agent_sock);
 
    if (result != 0) {
      return SET_ERRNO(ERROR_CRYPTO, "GPG agent signing failed");
    }
 
    if (sig_len != 64) {
      return SET_ERRNO(ERROR_CRYPTO, "GPG agent returned invalid signature length: %zu (expected 64)", sig_len);
    }
 
    log_info("Successfully signed message with GPG agent (64 bytes)");
    return ASCIICHAT_OK;
  }
 
  // If using SSH agent, delegate signing to SSH agent
  if (key->use_ssh_agent) {
    log_debug("Using SSH agent for Ed25519 signing");
 
    // Create a public_key_t from the stored public key
    public_key_t pub_key = {0};
    pub_key.type = KEY_TYPE_ED25519;
    memcpy(pub_key.key, key->public_key, 32);
 
    // Sign using SSH agent
    asciichat_error_t result = ssh_agent_sign(&pub_key, message, message_len, signature);
    if (result != ASCIICHAT_OK) {
      return result; // Error already set by ssh_agent_sign
    }
 
    log_info("Successfully signed message with SSH agent (64 bytes)");
    return ASCIICHAT_OK;
  }
 
  // Sign the message with Ed25519 (in-memory key)
  if (crypto_sign_detached(signature, NULL, message, message_len, key->key.ed25519) != 0) {
    return SET_ERRNO(ERROR_CRYPTO, "Failed to sign message with Ed25519");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, private_key_t::ed25519, ERROR_CRYPTO, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, gpg_agent_connect(), gpg_agent_disconnect(), gpg_agent_sign(), private_key_t::gpg_keygrip, gpg_sign_detached_ed25519(), public_key_t::key, private_key_t::key, private_key_t::key_comment, KEY_TYPE_ED25519, log_debug, log_info, private_key_t::public_key, SET_ERRNO, ssh_agent_sign(), public_key_t::type, private_key_t::type, private_key_t::use_gpg_agent, and private_key_t::use_ssh_agent.

Referenced by crypto_handshake_client_key_exchange(), and crypto_handshake_server_start().

ed25519_to_x25519_private()

asciichat_error_t ed25519_to_x25519_private	(	const uint8_t	ed25519_sk[64],
		uint8_t	x25519_sk[32]
	)

#include <ssh_keys.h>

Convert Ed25519 private key to X25519 for key exchange.

Parameters

ed25519_sk	Ed25519 private key (64 bytes: seed + public, must not be NULL)
x25519_sk	Output buffer for X25519 private key (32 bytes, must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Converts Ed25519 private key to X25519 format for Diffie-Hellman key exchange. Uses libsodium's conversion function.

Note

Ed25519 key format: Ed25519 private key is 64 bytes (32-byte seed + 32-byte public key). Function extracts seed (first 32 bytes) and converts to X25519 scalar.

Conversion: Uses crypto_sign_ed25519_sk_to_curve25519() from libsodium. Conversion is mathematically safe (same curve, different representation).

Key size: Ed25519 private key is 64 bytes, X25519 private key is 32 bytes. Extracts 32-byte seed from Ed25519 key and converts to X25519 scalar.

Use case: Used for key exchange when Ed25519 key is used for signing but X25519 is needed for key exchange (DH).

Warning

Ed25519 key must be exactly 64 bytes (32-byte seed + 32-byte public). Function validates key size before conversion.

Definition at line 1050 of file ssh_keys.c.

                                                                                                 {
  if (!ed25519_sk || !x25519_sk) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ed25519_sk=%p, x25519_sk=%p", ed25519_sk, x25519_sk);
  }
 
  // Convert Ed25519 private key to X25519 private key
  if (crypto_sign_ed25519_sk_to_curve25519(x25519_sk, ed25519_sk) != 0) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to convert Ed25519 private key to X25519");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by private_key_to_x25519().

ed25519_to_x25519_public()

asciichat_error_t ed25519_to_x25519_public	(	const uint8_t	ed25519_pk[32],
		uint8_t	x25519_pk[32]
	)

#include <ssh_keys.h>

Convert Ed25519 public key to X25519 for key exchange.

Parameters

ed25519_pk	Ed25519 public key (32 bytes, must not be NULL)
x25519_pk	Output buffer for X25519 public key (32 bytes, must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Converts Ed25519 public key to X25519 format for Diffie-Hellman key exchange. Uses libsodium's conversion function.

Note

Conversion: Uses crypto_sign_ed25519_pk_to_curve25519() from libsodium. Conversion is mathematically safe (same curve, different representation).

Key size: Both Ed25519 and X25519 keys are 32 bytes. No size change during conversion.

Use case: Used for key exchange when Ed25519 key is used for signing but X25519 is needed for key exchange (DH).

Warning

All keys must be 32 bytes. Function validates key size before conversion.

Definition at line 1037 of file ssh_keys.c.

                                                                                                {
  if (!ed25519_pk || !x25519_pk) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ed25519_pk=%p, x25519_pk=%p", ed25519_pk, x25519_pk);
  }
 
  // Convert Ed25519 public key to X25519 public key
  if (crypto_sign_ed25519_pk_to_curve25519(x25519_pk, ed25519_pk) != 0) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to convert Ed25519 public key to X25519");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by public_key_to_x25519().

ed25519_verify_signature()

asciichat_error_t ed25519_verify_signature	(	const uint8_t	public_key[32],
		const uint8_t *	message,
		size_t	message_len,
		const uint8_t	signature[64],
		const char *	gpg_key_id
	)

#include <keys.h>

Verify an Ed25519 signature.

Parameters

public_key	Ed25519 public key (32 bytes)
message	Message that was signed (must not be NULL)
message_len	Length of message that was signed
signature	Ed25519 signature to verify (64 bytes)

Returns

ASCIICHAT_OK if signature is valid, error code on failure

Verifies an Ed25519 signature using libsodium's verification function.

Note

Signature format: Ed25519 signature is always 64 bytes (R || S format).

Verification: Uses crypto_sign_ed25519_verify_detached() from libsodium. Returns error if signature is invalid or message was tampered with.

Constant-time: Verification uses constant-time comparison to prevent timing attacks.

Warning

Always check return value. Error indicates invalid signature or tampering.

Parameters

public_key	Ed25519 public key (32 bytes, must not be NULL)
message	Message that was signed (must not be NULL)
message_len	Length of message that was signed
signature	Ed25519 signature to verify (64 bytes, must not be NULL)

Returns

ASCIICHAT_OK if signature is valid, error code on failure

Verifies an Ed25519 signature using libsodium's verification function.

Note

Signature format: Ed25519 signature is always 64 bytes (R || S format).

Verification: Uses crypto_sign_ed25519_verify_detached() from libsodium. Returns error if signature is invalid or message was tampered with.

Constant-time: Verification uses constant-time comparison to prevent timing attacks.

Warning

Always check return value. Error indicates invalid signature or tampering.

Definition at line 1163 of file ssh_keys.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);
  }
 
  // Try standard Ed25519 verification first
  if (crypto_sign_verify_detached(signature, message, message_len, public_key) == 0) {
    return ASCIICHAT_OK;
  }
 
  // If standard verification fails, try GPG fallback (for GPG-signed messages)
  // Use provided gpg_key_id if available, otherwise check environment variable (for tests)
  const char *key_id_to_use = gpg_key_id;
  size_t key_id_len = key_id_to_use ? strlen(key_id_to_use) : 0;
  // Accept 8, 16, or 40 character GPG key IDs (short, long, or full fingerprint)
  bool valid_key_id = (key_id_len == 8 || key_id_len == 16 || key_id_len == 40);
 
  if (!valid_key_id) {
    key_id_to_use = platform_getenv("TEST_GPG_KEY_ID");
    key_id_len = key_id_to_use ? strlen(key_id_to_use) : 0;
    valid_key_id = (key_id_len == 8 || key_id_len == 16 || key_id_len == 40);
  }
 
  if (valid_key_id) {
    log_debug("Standard Ed25519 verification failed, trying GPG fallback with key %s", key_id_to_use);
    int gpg_result = gpg_verify_detached_ed25519(key_id_to_use, message, message_len, signature);
    if (gpg_result == 0) {
      log_debug("GPG verification succeeded");
      return ASCIICHAT_OK;
    }
    log_debug("GPG verification also failed");
  }
 
  return SET_ERRNO(ERROR_CRYPTO, "Ed25519 signature verification failed (tried both libsodium and GPG)");
}

References ASCIICHAT_OK, ERROR_CRYPTO, ERROR_INVALID_PARAM, gpg_verify_detached_ed25519(), log_debug, platform_getenv(), and SET_ERRNO.

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

extract_ed25519_from_gpg()

asciichat_error_t extract_ed25519_from_gpg	(	const char *	gpg_key_text,
		uint8_t	ed25519_pk[32]
	)

#include <gpg_keys.h>

Extract Ed25519 public key from GPG key.

Parameters

gpg_key_text	GPG key in armored format (must not be NULL)
ed25519_pk	Output buffer for Ed25519 public key (32 bytes, must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Extracts Ed25519 public key from GPG key by parsing OpenPGP packet structure.

Note

OpenPGP parsing: Parses OpenPGP packet structure to find Ed25519 public key packet. Requires parsing of packet headers and packet data.

Key extraction: Finds Ed25519 subkey in GPG key structure. Extracts 32-byte Ed25519 public key material.

Warning

NOT YET IMPLEMENTED: This function is not yet implemented. Returns ERROR_CRYPTO_KEY with "Ed25519 extraction from GPG key not yet implemented".

GPG support is currently disabled. Function will not work until implemented.

Definition at line 95 of file gpg_keys.c.

                                                                                           {
  if (!gpg_key_id || !ed25519_pk) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: gpg_key_id=%p, ed25519_pk=%p", gpg_key_id, ed25519_pk);
    return ERROR_INVALID_PARAM;
  }
 
  // Use gpg_get_public_key() to extract Ed25519 public key from GPG keyring
  // Note: gpg_key_id should be the key ID (e.g., "7FE90A79F2E80ED3")
  char keygrip[64];
  if (gpg_get_public_key(gpg_key_id, ed25519_pk, keygrip) != 0) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to extract Ed25519 public key from GPG for key ID: %s", gpg_key_id);
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, gpg_get_public_key(), and SET_ERRNO.

Referenced by gpg_to_x25519_public(), and parse_gpg_key().

extract_gpg_key_comment()

asciichat_error_t extract_gpg_key_comment	(	const char *	gpg_key_text,
		char *	comment_out,
		size_t	comment_size
	)

#include <gpg_keys.h>

Extract key comment/email from GPG key.

Parameters

gpg_key_text	GPG key in armored format (must not be NULL)
comment_out	Output buffer for comment (must not be NULL)
comment_size	Size of comment buffer (must be > 0)

Returns

ASCIICHAT_OK on success, error code on failure

Extracts comment/email from GPG key by parsing user ID packet.

Note

Comment extraction: Parses OpenPGP packet structure to find user ID packet. Extracts comment/email from user ID packet.

User ID format: GPG user IDs typically contain name and email. Format: "Name <email@example.com>" or just "email@example.com"

Warning

GPG support is currently disabled. Function may not work until GPG support is re-enabled.

Definition at line 303 of file gpg_keys.c.

                                                                                                            {
  if (!gpg_key_text || !comment_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: gpg_key_text=%p, comment_out=%p", gpg_key_text, comment_out);
    return ERROR_INVALID_PARAM;
  }
 
  if (comment_size == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid comment size: %zu", comment_size);
    return ERROR_INVALID_PARAM;
  }
 
  // TODO: Implement GPG key comment extraction
  // This requires parsing the OpenPGP packet structure and extracting user ID packets
 
  // For now, use a generic comment
  SAFE_STRNCPY(comment_out, "GPG key", comment_size - 1);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, SAFE_STRNCPY, and SET_ERRNO.

fetch_github_gpg_keys()

asciichat_error_t fetch_github_gpg_keys	(	const char *	username,
		char ***	keys_out,
		size_t *	num_keys
	)

#include <https_keys.h>

Fetch GPG keys from GitHub using HTTPS.

Fetch GPG keys from GitHub using BearSSL.

Parameters

username	GitHub username (must not be NULL)
keys_out	Output array of GPG key strings (caller must free each string and array)
num_keys	Output parameter for number of keys fetched

Returns

ASCIICHAT_OK on success, error code on failure

Fetches GPG keys from GitHub: GET https://github.com/username.gpg

Note

Network operation: Requires network connectivity and valid GitHub username. May fail if network is unavailable or username doesn't exist.

GPG format: Fetches GPG keys in armored format. Response contains GPG key blocks (--—BEGIN PGP PUBLIC KEY BLOCK--—).

Memory management: Caller must free each key string and the keys array (same as fetch_github_ssh_keys).

Warning

Network dependency: Requires active network connection.

GPG support: GPG key parsing may not work until GPG support is re-enabled.

Parameters

username	GitHub username (must not be NULL)
keys_out	Output array of GPG key strings (caller must free each string and array)
num_keys	Output parameter for number of GPG keys fetched

Returns

ASCIICHAT_OK on success, error code on failure

Fetches GPG keys from GitHub: GET https://github.com/username.gpg

Note

Memory management: Caller must free each key string and the keys array (same as fetch_github_keys).

Warning

Network dependency: Requires active network connection.

Definition at line 242 of file https_keys.c.

                                                                                                  {
  if (!username || !keys_out || !num_keys) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: username=%p, keys_out=%p, num_keys=%p", username, keys_out,
              num_keys);
    return ERROR_INVALID_PARAM;
  }
 
  // Build the GitHub GPG keys URL
  char url[256];
  asciichat_error_t url_result = build_github_gpg_url(username, url, sizeof(url));
  if (url_result != ASCIICHAT_OK) {
    return url_result;
  }
 
  // Fetch the keys using HTTPS
  char *response_text = NULL;
  size_t response_len = 0;
  asciichat_error_t fetch_result = https_fetch_keys(url, &response_text, &response_len);
  if (fetch_result != ASCIICHAT_OK) {
    return fetch_result;
  }
 
  // Parse GPG keys from the response
  asciichat_error_t parse_result =
      parse_gpg_keys_from_response(response_text, response_len, keys_out, num_keys, MAX_CLIENTS);
 
  // Clean up response text
  SAFE_FREE(response_text);
 
  return parse_result;
}

References ASCIICHAT_OK, build_github_gpg_url(), ERROR_INVALID_PARAM, MAX_CLIENTS, parse_gpg_keys_from_response(), SAFE_FREE, and SET_ERRNO.

Referenced by fetch_github_keys(), and parse_public_keys().

fetch_github_keys()

asciichat_error_t fetch_github_keys	(	const char *	username,
		char ***	keys_out,
		size_t *	num_keys,
		bool	use_gpg
	)

#include <keys.h>

Fetch SSH/GPG keys from GitHub using BearSSL.

Parameters

username	GitHub username (must not be NULL)
keys_out	Output array of key strings (caller must free each string and array)
num_keys	Output parameter for number of keys fetched
use_gpg	True to fetch GPG keys, false to fetch SSH keys

Returns

ASCIICHAT_OK on success, error code on failure

Fetches keys from GitHub:

• SSH keys: GET https://github.com/username.keys
• GPG keys: GET https://github.com/username.gpg

Note

Network operation: Requires network connectivity and valid GitHub username. May fail if network is unavailable or username doesn't exist.

Memory management: Caller must free each key string and the keys array: c for (size_t i = 0; i < num_keys; i++) { free(keys_out[i]); } free(keys_out);

Warning

Network dependency: Requires active network connection. May fail if GitHub is unreachable or username doesn't exist.

Definition at line 315 of file keys.c.

                                                                                                            {
  if (!username || !keys_out || !num_keys) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for fetch_github_keys");
  }
 
  if (use_gpg) {
    return fetch_github_gpg_keys(username, keys_out, num_keys);
  } else {
    return fetch_github_ssh_keys(username, keys_out, num_keys);
  }
}

References ERROR_INVALID_PARAM, fetch_github_gpg_keys(), fetch_github_ssh_keys(), and SET_ERRNO.

fetch_github_ssh_keys()

asciichat_error_t fetch_github_ssh_keys	(	const char *	username,
		char ***	keys_out,
		size_t *	num_keys
	)

#include <https_keys.h>

Fetch SSH keys from GitHub using HTTPS.

Parameters

username	GitHub username (must not be NULL)
keys_out	Output array of SSH key strings (caller must free each string and array)
num_keys	Output parameter for number of keys fetched

Returns

ASCIICHAT_OK on success, error code on failure

Fetches SSH keys from GitHub: GET https://github.com/username.keys

Note

Network operation: Requires network connectivity and valid GitHub username. May fail if network is unavailable or username doesn't exist.

Key format: Only Ed25519 SSH keys are parsed from response. Other key types (RSA, ECDSA) are skipped.

Memory management: Caller must free each key string and the keys array: c for (size_t i = 0; i < num_keys; i++) { free(keys_out[i]); } free(keys_out);

Response parsing: Parses response as one key per line. Each line is parsed as SSH key format ("ssh-ed25519 AAAAC3... comment").

Warning

Network dependency: Requires active network connection. May fail if GitHub is unreachable or username doesn't exist.

Memory leak: Caller must free returned strings and array. Function allocates memory that must be freed.

Definition at line 178 of file https_keys.c.

                                                                                                  {
  if (!username || !keys_out || !num_keys) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: username=%p, keys_out=%p, num_keys=%p", username, keys_out,
              num_keys);
    return ERROR_INVALID_PARAM;
  }
 
  // Build the GitHub SSH keys URL
  char url[256];
  asciichat_error_t url_result = build_github_ssh_url(username, url, sizeof(url));
  if (url_result != ASCIICHAT_OK) {
    return url_result;
  }
 
  // Fetch the keys using HTTPS
  char *response_text = NULL;
  size_t response_len = 0;
  asciichat_error_t fetch_result = https_fetch_keys(url, &response_text, &response_len);
  if (fetch_result != ASCIICHAT_OK) {
    return fetch_result;
  }
 
  // Parse SSH keys from the response
  asciichat_error_t parse_result =
      parse_ssh_keys_from_response(response_text, response_len, keys_out, num_keys, MAX_CLIENTS);
 
  // Clean up response text
  SAFE_FREE(response_text);
 
  return parse_result;
}

References ASCIICHAT_OK, build_github_ssh_url(), ERROR_INVALID_PARAM, MAX_CLIENTS, parse_ssh_keys_from_response(), SAFE_FREE, and SET_ERRNO.

Referenced by fetch_github_keys(), and parse_public_keys().

fetch_gitlab_gpg_keys()

asciichat_error_t fetch_gitlab_gpg_keys	(	const char *	username,
		char ***	keys_out,
		size_t *	num_keys
	)

#include <https_keys.h>

Fetch GPG keys from GitLab using HTTPS.

Fetch GPG keys from GitLab using BearSSL.

Parameters

username	GitLab username (must not be NULL)
keys_out	Output array of GPG key strings (caller must free each string and array)
num_keys	Output parameter for number of keys fetched

Returns

ASCIICHAT_OK on success, error code on failure

Fetches GPG keys from GitLab: GET https://gitlab.com/username.gpg

Note

Network operation: Requires network connectivity and valid GitLab username. May fail if network is unavailable or username doesn't exist.

GPG format: Fetches GPG keys in armored format. Response contains GPG key blocks (--—BEGIN PGP PUBLIC KEY BLOCK--—).

Memory management: Caller must free each key string and the keys array (same as fetch_gitlab_ssh_keys).

Warning

Network dependency: Requires active network connection.

GPG support: GPG key parsing may not work until GPG support is re-enabled.

Parameters

username	GitLab username (must not be NULL)
keys_out	Output array of GPG key strings (caller must free each string and array)
num_keys	Output parameter for number of GPG keys fetched

Returns

ASCIICHAT_OK on success, error code on failure

Fetches GPG keys from GitLab: GET https://gitlab.com/username.gpg

Note

Memory management: Caller must free each key string and the keys array (same as fetch_gitlab_keys).

Warning

Network dependency: Requires active network connection.

Definition at line 274 of file https_keys.c.

                                                                                                  {
  if (!username || !keys_out || !num_keys) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: username=%p, keys_out=%p, num_keys=%p", username, keys_out,
              num_keys);
    return ERROR_INVALID_PARAM;
  }
 
  // Build the GitLab GPG keys URL
  char url[256];
  asciichat_error_t url_result = build_gitlab_gpg_url(username, url, sizeof(url));
  if (url_result != ASCIICHAT_OK) {
    return url_result;
  }
 
  // Fetch the keys using HTTPS
  char *response_text = NULL;
  size_t response_len = 0;
  asciichat_error_t fetch_result = https_fetch_keys(url, &response_text, &response_len);
  if (fetch_result != ASCIICHAT_OK) {
    return fetch_result;
  }
 
  // Parse GPG keys from the response
  asciichat_error_t parse_result =
      parse_gpg_keys_from_response(response_text, response_len, keys_out, num_keys, MAX_CLIENTS);
 
  // Clean up response text
  SAFE_FREE(response_text);
 
  return parse_result;
}

References ASCIICHAT_OK, build_gitlab_gpg_url(), ERROR_INVALID_PARAM, MAX_CLIENTS, parse_gpg_keys_from_response(), SAFE_FREE, and SET_ERRNO.

Referenced by fetch_gitlab_keys(), and parse_public_keys().

fetch_gitlab_keys()

asciichat_error_t fetch_gitlab_keys	(	const char *	username,
		char ***	keys_out,
		size_t *	num_keys,
		bool	use_gpg
	)

#include <keys.h>

Fetch SSH/GPG keys from GitLab using BearSSL.

Parameters

username	GitLab username (must not be NULL)
keys_out	Output array of key strings (caller must free each string and array)
num_keys	Output parameter for number of keys fetched
use_gpg	True to fetch GPG keys, false to fetch SSH keys

Returns

ASCIICHAT_OK on success, error code on failure

Fetches keys from GitLab:

• SSH keys: GET https://gitlab.com/username.keys
• GPG keys: GET https://gitlab.com/username.gpg

Note

Network operation: Requires network connectivity and valid GitLab username. May fail if network is unavailable or username doesn't exist.

Memory management: Caller must free each key string and the keys array (same as fetch_github_keys).

Warning

Network dependency: Requires active network connection. May fail if GitLab is unreachable or username doesn't exist.

Definition at line 327 of file keys.c.

                                                                                                            {
  if (!username || !keys_out || !num_keys) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for fetch_gitlab_keys");
  }
 
  if (use_gpg) {
    return fetch_gitlab_gpg_keys(username, keys_out, num_keys);
  } else {
    return fetch_gitlab_ssh_keys(username, keys_out, num_keys);
  }
}

References ERROR_INVALID_PARAM, fetch_gitlab_gpg_keys(), fetch_gitlab_ssh_keys(), and SET_ERRNO.

fetch_gitlab_ssh_keys()

asciichat_error_t fetch_gitlab_ssh_keys	(	const char *	username,
		char ***	keys_out,
		size_t *	num_keys
	)

#include <https_keys.h>

Fetch SSH keys from GitLab using HTTPS.

Parameters

username	GitLab username (must not be NULL)
keys_out	Output array of SSH key strings (caller must free each string and array)
num_keys	Output parameter for number of keys fetched

Returns

ASCIICHAT_OK on success, error code on failure

Fetches SSH keys from GitLab: GET https://gitlab.com/username.keys

Note

Network operation: Requires network connectivity and valid GitLab username. May fail if network is unavailable or username doesn't exist.

Key format: Only Ed25519 SSH keys are parsed from response. Other key types (RSA, ECDSA) are skipped.

Memory management: Caller must free each key string and the keys array (same as fetch_github_ssh_keys).

Warning

Network dependency: Requires active network connection. May fail if GitLab is unreachable or username doesn't exist.

Definition at line 210 of file https_keys.c.

                                                                                                  {
  if (!username || !keys_out || !num_keys) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: username=%p, keys_out=%p, num_keys=%p", username, keys_out,
              num_keys);
    return ERROR_INVALID_PARAM;
  }
 
  // Build the GitLab SSH keys URL
  char url[256];
  asciichat_error_t url_result = build_gitlab_ssh_url(username, url, sizeof(url));
  if (url_result != ASCIICHAT_OK) {
    return url_result;
  }
 
  // Fetch the keys using HTTPS
  char *response_text = NULL;
  size_t response_len = 0;
  asciichat_error_t fetch_result = https_fetch_keys(url, &response_text, &response_len);
  if (fetch_result != ASCIICHAT_OK) {
    return fetch_result;
  }
 
  // Parse SSH keys from the response
  asciichat_error_t parse_result =
      parse_ssh_keys_from_response(response_text, response_len, keys_out, num_keys, MAX_CLIENTS);
 
  // Clean up response text
  SAFE_FREE(response_text);
 
  return parse_result;
}

References ASCIICHAT_OK, build_gitlab_ssh_url(), ERROR_INVALID_PARAM, MAX_CLIENTS, parse_ssh_keys_from_response(), SAFE_FREE, and SET_ERRNO.

Referenced by fetch_gitlab_keys(), and parse_public_keys().

format_gpg_key_display()

asciichat_error_t format_gpg_key_display	(	const char *	gpg_key_text,
		char *	output,
		size_t	output_size
	)

#include <gpg_keys.h>

Format GPG key for display.

Parameters

gpg_key_text	GPG key in armored format (must not be NULL)
output	Output buffer for formatted key (must not be NULL)
output_size	Size of output buffer (must be >= 64)

Returns

ASCIICHAT_OK on success, error code on failure

Formats GPG key for display by extracting key ID and creating display string.

Note

Display format: "GPG key ID: <hex_key_id>" (e.g., "GPG key ID: EDDAE1DA7360D7F4").

Key ID extraction: Uses get_gpg_key_id() to extract key ID. Falls back to generic message if extraction fails.

Buffer requirements: Output buffer must be at least 64 bytes. Format string is "GPG key ID: " (12 chars) + 16 hex chars + null = 29 bytes minimum.

Warning

GPG support is currently disabled. Function depends on get_gpg_key_id() which is not yet implemented. Falls back to generic message if extraction fails.

Definition at line 266 of file gpg_keys.c.

                                                                                                     {
  if (!gpg_key_text || !output) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: gpg_key_text=%p, output=%p", gpg_key_text, output);
    return ERROR_INVALID_PARAM;
  }
 
  if (output_size < 64) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Output buffer too small: %zu (minimum 64)", output_size);
    return ERROR_INVALID_PARAM;
  }
 
  // Extract key ID for display
  uint8_t key_id[8];
  asciichat_error_t key_id_result = get_gpg_key_id(gpg_key_text, key_id);
  if (key_id_result != ASCIICHAT_OK) {
    // Fallback to generic GPG key display
    SAFE_STRNCPY(output, "GPG key (key ID extraction failed)", output_size - 1);
    return ASCIICHAT_OK;
  }
 
  // Format as hex key ID
  char hex_key_id[17];
  for (int i = 0; i < 8; i++) {
    safe_snprintf(hex_key_id + i * 2, 3, "%02x", key_id[i]);
  }
  hex_key_id[16] = '\0';
 
  // Create display string
  int result = safe_snprintf(output, output_size, "GPG key ID: %s", hex_key_id);
  if (result < 0 || result >= (int)output_size) {
    SET_ERRNO(ERROR_STRING, "Failed to format GPG key display");
    return ERROR_STRING;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_STRING, get_gpg_key_id(), safe_snprintf(), SAFE_STRNCPY, and SET_ERRNO.

format_public_key()

void format_public_key	(	const public_key_t *	key,
		char *	output,
		size_t	output_size
	)

#include <keys.h>

Convert public key to display format (ssh-ed25519 or x25519 hex)

Parameters

key	Public key to format (must not be NULL)
output	Output buffer for formatted key string (must not be NULL)
output_size	Size of output buffer (must be large enough for formatted key)

Formats public key for display:

• Ed25519: "ssh-ed25519 AAAAC3..." (base64-encoded key)
• X25519: "x25519 <hex>" (hex-encoded key)

Note

Output format: Depends on key type. Ed25519 uses base64, X25519 uses hex.

Buffer size: Output buffer should be at least 512 bytes for Ed25519 format. X25519 format requires at least 65 bytes (64 hex chars + "x25519 " prefix + null).

Warning

Output buffer must be large enough for formatted key string. Function does not check buffer size (may overflow).

Definition at line 387 of file keys.c.

                                                                                  {
  if (!key || !output || output_size == 0) {
    return;
  }
 
  if (key->type == KEY_TYPE_ED25519) {
    // Format as SSH Ed25519 public key
    // Simple base64 encoding for 32 bytes = 43 chars + padding
    // For now, just use hex encoding
    char hex_key[65];
    for (size_t i = 0; i < 32; i++) {
      char hex_byte[3];
      safe_snprintf(hex_byte, sizeof(hex_byte), "%02x", key->key[i]);
      hex_key[i * 2] = hex_byte[0];
      hex_key[i * 2 + 1] = hex_byte[1];
    }
    hex_key[64] = '\0';
    safe_snprintf(output, output_size, "ssh-ed25519 %s %s", hex_key, key->comment);
  } else if (key->type == KEY_TYPE_X25519) {
    // Format as hex X25519 key
    char hex_key[65];
    for (size_t i = 0; i < 32; i++) {
      char hex_byte[3];
      safe_snprintf(hex_byte, sizeof(hex_byte), "%02x", key->key[i]);
      hex_key[i * 2] = hex_byte[0];
      hex_key[i * 2 + 1] = hex_byte[1];
    }
    hex_key[64] = '\0';
    safe_snprintf(output, output_size, "x25519 %s", hex_key);
  } else {
    safe_snprintf(output, output_size, "unknown key type: %d", key->type);
  }
}

References public_key_t::comment, public_key_t::key, KEY_TYPE_ED25519, KEY_TYPE_X25519, safe_snprintf(), and public_key_t::type.

generate_key_fingerprint()

asciichat_error_t generate_key_fingerprint	(	const public_key_t *	key,
		uint8_t *	fingerprint_out,
		size_t	fingerprint_size
	)

#include <keys_validation.h>

Generate key fingerprint.

Parameters

key	Key to fingerprint (must not be NULL)
fingerprint_out	Output buffer for fingerprint (must not be NULL)
fingerprint_size	Size of fingerprint buffer (must be >= 32 for SHA-256)

Returns

ASCIICHAT_OK on success, error code on failure

Generates key fingerprint by computing hash of key material. Typically uses SHA-256 for fingerprint generation.

Note

Fingerprint algorithm: Uses SHA-256 hash of key material. Fingerprint is 32 bytes (256 bits) for SHA-256.

Key material: Hashes raw 32-byte key data (not key type or comment). Fingerprint uniquely identifies the key.

Buffer requirements: Fingerprint buffer must be at least 32 bytes for SHA-256. Function may use different hash algorithms in the future.

Warning

Fingerprint buffer must be large enough for hash output. Function validates buffer size but may overflow if buffer is too small.

Definition at line 460 of file keys_validation.c.

                                                                                                                       {
  if (!key || !fingerprint_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key=%p, fingerprint_out=%p", key, fingerprint_out);
    return ERROR_INVALID_PARAM;
  }
 
  if (fingerprint_size < 32) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Fingerprint buffer too small: %zu (minimum 32)", fingerprint_size);
    return ERROR_INVALID_PARAM;
  }
 
  // Generate SHA-256 fingerprint of the key
  if (crypto_hash_sha256(fingerprint_out, key->key, 32) != 0) {
    SET_ERRNO(ERROR_CRYPTO, "Failed to generate key fingerprint");
    return ERROR_CRYPTO;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO, ERROR_INVALID_PARAM, public_key_t::key, and SET_ERRNO.

Referenced by check_key_fingerprint().

get_gpg_fingerprint()

asciichat_error_t get_gpg_fingerprint	(	const char *	gpg_key_text,
		uint8_t	fingerprint_out[20]
	)

#include <gpg_keys.h>

Get GPG key fingerprint.

Parameters

gpg_key_text	GPG key in armored format (must not be NULL)
fingerprint_out	Output buffer for fingerprint (20 bytes for SHA-1, must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Extracts GPG key fingerprint (SHA-1 hash of key material). Used for key identification and verification.

Note

Fingerprint format: SHA-1 hash of key material (20 bytes). Standard GPG fingerprint format.

OpenPGP parsing: Parses OpenPGP packet structure and computes SHA-1 hash. Requires parsing of packet structure.

Warning

NOT YET IMPLEMENTED: This function is not yet implemented. Returns ERROR_CRYPTO_KEY with "GPG fingerprint extraction not yet implemented".

GPG support is currently disabled. Function will not work until implemented.

Definition at line 137 of file gpg_keys.c.

                                                                                             {
  if (!gpg_key_text || !fingerprint_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: gpg_key_text=%p, fingerprint_out=%p", gpg_key_text,
              fingerprint_out);
    return ERROR_INVALID_PARAM;
  }
 
  // TODO: Implement GPG fingerprint extraction
  // This requires parsing the OpenPGP packet structure and computing SHA-1
 
  SET_ERRNO(ERROR_CRYPTO_KEY, "GPG fingerprint extraction not yet implemented");
  return ERROR_CRYPTO_KEY;
}

References ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, and SET_ERRNO.

get_gpg_key_id()

asciichat_error_t get_gpg_key_id	(	const char *	gpg_key_text,
		uint8_t	key_id_out[8]
	)

#include <gpg_keys.h>

Get GPG key ID (short fingerprint)

Parameters

gpg_key_text	GPG key in armored format (must not be NULL)
key_id_out	Output buffer for key ID (8 bytes, must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Extracts GPG key ID (last 8 bytes of SHA-1 fingerprint). Used for key identification in short form.

Note

Key ID format: Last 8 bytes of SHA-1 fingerprint (16 hex chars). Example: "EDDAE1DA7360D7F4"

Key ID extraction: Computes full fingerprint and extracts last 8 bytes. Alternatively, can parse from GPG key structure directly.

Warning

NOT YET IMPLEMENTED: This function is not yet implemented. Returns ERROR_CRYPTO_KEY with "GPG key ID extraction not yet implemented".

GPG support is currently disabled. Function will not work until implemented.

Definition at line 151 of file gpg_keys.c.

                                                                                  {
  if (!gpg_key_text || !key_id_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: gpg_key_text=%p, key_id_out=%p", gpg_key_text, key_id_out);
    return ERROR_INVALID_PARAM;
  }
 
  // TODO: Implement GPG key ID extraction
  // This is typically the last 8 bytes of the fingerprint
 
  SET_ERRNO(ERROR_CRYPTO_KEY, "GPG key ID extraction not yet implemented");
  return ERROR_CRYPTO_KEY;
}

References ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by format_gpg_key_display().

gpg_to_x25519_public()

asciichat_error_t gpg_to_x25519_public	(	const char *	gpg_key_text,
		uint8_t	x25519_pk[32]
	)

#include <gpg_keys.h>

Convert GPG key to X25519 for key exchange.

Parameters

gpg_key_text	GPG key in armored format (must not be NULL)
x25519_pk	Output buffer for X25519 public key (32 bytes, must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Converts GPG key to X25519 format for Diffie-Hellman key exchange. Extracts Ed25519 key and converts to X25519.

Note

Conversion flow:

1. Extract Ed25519 public key from GPG key
2. Convert Ed25519 to X25519 using libsodium

Key conversion: Uses crypto_sign_ed25519_pk_to_curve25519() from libsodium. Conversion is mathematically safe (same curve, different representation).

Warning

GPG support is currently disabled. Function depends on extract_ed25519_from_gpg() which is not yet implemented. Function will not work until GPG support is re-enabled.

Definition at line 111 of file gpg_keys.c.

                                                                                        {
  if (!gpg_key_text || !x25519_pk) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: gpg_key_text=%p, x25519_pk=%p", gpg_key_text, x25519_pk);
    return ERROR_INVALID_PARAM;
  }
 
  // First extract the Ed25519 public key from the GPG key
  uint8_t ed25519_pk[32];
  asciichat_error_t extract_result = extract_ed25519_from_gpg(gpg_key_text, ed25519_pk);
  if (extract_result != ASCIICHAT_OK) {
    return extract_result;
  }
 
  // Convert Ed25519 to X25519
  if (crypto_sign_ed25519_pk_to_curve25519(x25519_pk, ed25519_pk) != 0) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to convert Ed25519 to X25519");
    return ERROR_CRYPTO_KEY;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, extract_ed25519_from_gpg(), and SET_ERRNO.

hex_decode()

asciichat_error_t hex_decode	(	const char *	hex,
		uint8_t *	output,
		size_t	output_len
	)

#include <keys.h>

Decode hex string to binary (utility function for testing)

Parameters

hex	Hex string to decode (must not be NULL, must have even length)
output	Output buffer for binary data (must not be NULL)
output_len	Expected output length in bytes (hex string must be output_len * 2 chars)

Returns

ASCIICHAT_OK on success, error code on failure

Decodes hex string to binary data. Utility function primarily for testing.

Note

Hex format: Must contain only valid hex characters (0-9, a-f, A-F). Must have even length (2 chars per byte).

Length validation: Hex string must be exactly output_len * 2 characters. Returns error if length doesn't match.

Invalid characters: Returns error if hex string contains invalid characters.

Warning

Hex string must have even length. Odd-length strings return error.

Definition at line 425 of file keys.c.

                                                                                  {
  if (!hex || !output) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for hex_decode");
  }
 
  size_t hex_len = strlen(hex);
  size_t expected_hex_len = output_len * 2;
 
  if (hex_len != expected_hex_len) {
    return SET_ERRNO(ERROR_INVALID_PARAM,
                     "Hex string length (%zu) doesn't match expected output length (%zu * 2 = %zu)", hex_len,
                     output_len, expected_hex_len);
  }
 
  // Decode hex string to binary
  for (size_t i = 0; i < output_len; i++) {
    char hex_byte[3] = {hex[i * 2], hex[i * 2 + 1], '\0'};
    char *endptr;
    unsigned long byte = strtoul(hex_byte, &endptr, 16);
 
    // Validate hex character
    if (*endptr != '\0' || byte > 255) {
      return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid hex character at position %zu: '%c%c'", i * 2, hex[i * 2],
                       hex[i * 2 + 1]);
    }
 
    output[i] = (uint8_t)byte;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by parse_public_key().

parse_gpg_key()

asciichat_error_t parse_gpg_key	(	const char *	gpg_key_text,
		public_key_t *	key_out
	)

#include <gpg_keys.h>

Parse GPG key from armored text format.

Parse Ed25519 public key from PGP armored format.

Parameters

gpg_key_text	GPG key in armored format (--—BEGIN PGP PUBLIC KEY BLOCK--—, must not be NULL)
key_out	Output structure for parsed public key (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Parses GPG key from armored format and extracts Ed25519 public key. Converts to X25519 for key exchange.

Note

GPG format: Expects PEM-armored GPG key format. Format: "-----BEGIN PGP PUBLIC KEY BLOCK-----" ... "-----END PGP PUBLIC KEY BLOCK-----"

Ed25519 extraction: Extracts Ed25519 public key from GPG key structure. Parses OpenPGP packet structure to find Ed25519 subkey.

Key conversion: Converts extracted Ed25519 key to X25519 for key exchange. Uses libsodium's conversion function.

Key validation: Validates GPG key format before parsing. Returns error if format is invalid.

Warning

GPG support is currently disabled. Many underlying functions are not implemented. This function may not work until GPG support is re-enabled.

Key format: Only Ed25519 GPG keys are supported. RSA/ECDSA GPG keys will return error.

Parameters

gpg_key_text	GPG key in armored format (must not be NULL)
key_out	Output structure for parsed public key (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Extracts Ed25519 public key from PGP armored format. Parses GPG key structure and converts to Ed25519/X25519 format.

Note

Key format: GPG keys are parsed from armored format (--—BEGIN PGP PUBLIC KEY BLOCK--—). Extracts Ed25519 subkey and converts to X25519 for key exchange.

Definition at line 32 of file gpg_keys.c.

                                                                               {
  if (!gpg_key_id || !key_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: gpg_key_id=%p, key_out=%p", gpg_key_id, key_out);
    return ERROR_INVALID_PARAM;
  }
 
  // Validate key ID format (must be 8, 16, or 40 hex characters, optionally with 0x prefix)
  // - 8 chars: short key ID (last 8 chars of fingerprint)
  // - 16 chars: long key ID (last 16 chars of fingerprint)
  // - 40 chars: full fingerprint
  const char *key_id = gpg_key_id;
  if (strncmp(key_id, "0x", 2) == 0 || strncmp(key_id, "0X", 2) == 0) {
    key_id += 2; // Skip 0x prefix
  }
 
  size_t key_id_len = strlen(key_id);
  if (key_id_len != 8 && key_id_len != 16 && key_id_len != 40) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid GPG key ID length: %zu (expected 8, 16, or 40 hex chars)", key_id_len);
  }
 
  // Validate hex characters
  for (size_t i = 0; i < key_id_len; i++) {
    char c = key_id[i];
    if (!((c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F'))) {
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid GPG key ID: contains non-hex character '%c'", c);
    }
  }
 
  // Extract Ed25519 public key from GPG keyring using gpg --list-keys
  uint8_t ed25519_pk[32];
  asciichat_error_t extract_result = extract_ed25519_from_gpg(key_id, ed25519_pk);
  if (extract_result != ASCIICHAT_OK) {
    return extract_result;
  }
 
  // Initialize the public key structure
  memset(key_out, 0, sizeof(public_key_t));
  key_out->type = KEY_TYPE_GPG;
  memcpy(key_out->key, ed25519_pk, 32);
 
  // Set comment for display
  safe_snprintf(key_out->comment, sizeof(key_out->comment), "GPG key %s", key_id);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, public_key_t::comment, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, extract_ed25519_from_gpg(), public_key_t::key, KEY_TYPE_GPG, safe_snprintf(), SET_ERRNO, and public_key_t::type.

Referenced by parse_public_key().

parse_gpg_key_binary()

asciichat_error_t parse_gpg_key_binary	(	const uint8_t *	gpg_key_binary,
		size_t	key_size,
		public_key_t *	key_out
	)

#include <gpg_keys.h>

Parse GPG key from binary format.

Parameters

gpg_key_binary	GPG key in binary format (must not be NULL)
key_size	Size of binary key data (must be > 0)
key_out	Output structure for parsed public key (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Parses GPG key from binary format (raw OpenPGP packets). Extracts Ed25519 public key and converts to X25519.

Note

Binary format: Accepts raw OpenPGP packet structure. Must parse packet structure to find Ed25519 public key packet.

OpenPGP packets: Parses OpenPGP packet format to extract public key. Requires understanding of OpenPGP packet structure.

Warning

NOT YET IMPLEMENTED: This function is not yet implemented. Returns ERROR_CRYPTO_KEY with "Binary GPG key parsing not yet implemented".

GPG support is currently disabled. Function will not work until implemented.

Definition at line 78 of file gpg_keys.c.

                                                                                                              {
  if (!gpg_key_binary || !key_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: gpg_key_binary=%p, key_out=%p", gpg_key_binary, key_out);
    return ERROR_INVALID_PARAM;
  }
 
  if (key_size == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid key size: %zu", key_size);
    return ERROR_INVALID_PARAM;
  }
 
  // TODO: Implement binary GPG key parsing
  // This requires parsing the OpenPGP packet format
  SET_ERRNO(ERROR_CRYPTO_KEY, "Binary GPG key parsing not yet implemented");
  return ERROR_CRYPTO_KEY;
}

References ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, and SET_ERRNO.

parse_gpg_keys_from_response()

asciichat_error_t parse_gpg_keys_from_response	(	const char *	response_text,
		size_t	response_len,
		char ***	keys_out,
		size_t *	num_keys,
		size_t	max_keys
	)

#include <https_keys.h>

Parse GPG keys from HTTPS response text.

Parameters

response_text	HTTPS response containing GPG keys (must not be NULL)
response_len	Length of response text
keys_out	Output array of parsed GPG keys (must not be NULL)
num_keys	Output parameter for number of keys parsed (must not be NULL)
max_keys	Maximum number of keys to parse (must be > 0)

Returns

ASCIICHAT_OK on success, error code on failure

Parses GPG keys from HTTPS response text (armored format). Extracts GPG key blocks and allocates memory for each key string.

Note

Response format: Expects GPG keys in armored format. Format: "-----BEGIN PGP PUBLIC KEY BLOCK-----" ... "-----END PGP PUBLIC KEY BLOCK-----"

Key extraction: Finds GPG key blocks (BEGIN/END markers) and extracts each block. Allocates memory for each complete GPG key block.

Memory allocation: Allocates memory for each key string. Caller must free each string and the array.

Maximum keys: Stops parsing after max_keys keys are found. Function returns ASCIICHAT_OK even if more keys exist in response.

Warning

Memory leak: Caller must free returned strings and array. Function allocates memory that must be freed.

GPG support: GPG key parsing may not work until GPG support is re-enabled.

Definition at line 408 of file https_keys.c.

                                                                                  {
  (void)max_keys;
  if (!response_text || !keys_out || !num_keys) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for GPG key parsing");
    return ERROR_INVALID_PARAM;
  }
 
  *num_keys = 0;
  *keys_out = NULL;
 
  // Check if this looks like a GPG key (starts with -----BEGIN PGP)
  if (strncmp(response_text, "-----BEGIN PGP", 14) != 0) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "Response does not contain a valid GPG key");
    return ERROR_CRYPTO_KEY;
  }
 
  // Write armored block to temp file
  char temp_file[] = "/tmp/asciichat_gpg_import_XXXXXX";
  int fd = mkstemp(temp_file);
  if (fd < 0) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to create temp file for GPG import");
  }
 
  ssize_t written = write(fd, response_text, response_len);
  close(fd);
 
  if (written != (ssize_t)response_len) {
    unlink(temp_file);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to write GPG key to temp file");
  }
 
  // Import the key using gpg --import
  char import_cmd[512];
  snprintf(import_cmd, sizeof(import_cmd), "gpg --import '%s' 2>&1", temp_file);
  FILE *import_fp = popen(import_cmd, "r");
  if (!import_fp) {
    unlink(temp_file);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to run gpg --import");
  }
 
  char import_output[2048];
  size_t import_len = fread(import_output, 1, sizeof(import_output) - 1, import_fp);
  import_output[import_len] = '\0';
  pclose(import_fp);
  unlink(temp_file);
 
  // Extract ALL key IDs from import output (format: "gpg: key KEYID: ...")
  // GitHub often returns multiple keys in one armored block
  const char *key_marker = "gpg: key ";
  char key_ids[16][17]; // Support up to 16 keys
  size_t key_count = 0;
 
  log_debug("GPG import output:\n%s", import_output);
 
  char *search_pos = import_output;
  while (key_count < 16) {
    char *key_line = strstr(search_pos, key_marker);
    if (!key_line)
      break;
 
    key_line += strlen(key_marker);
    int i = 0;
    while (i < 16 && key_line[i] != ':' && key_line[i] != ' ' && key_line[i] != '\n') {
      key_ids[key_count][i] = key_line[i];
      i++;
    }
    key_ids[key_count][i] = '\0';
 
    if (i > 0) {
      log_debug("Extracted GPG key ID #%zu: %s", key_count, key_ids[key_count]);
      key_count++;
    }
    search_pos = key_line + i;
  }
 
  if (key_count == 0) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to extract any key IDs from GPG import output");
  }
 
  log_debug("Total GPG keys extracted from import: %zu", key_count);
 
  // Allocate array for results
  *keys_out = SAFE_MALLOC(sizeof(char *) * key_count, char **);
  if (!*keys_out) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate GPG keys array");
  }
 
  // Process each key ID to get full fingerprint
  size_t valid_keys = 0;
  for (size_t k = 0; k < key_count; k++) {
    // Get full fingerprint from gpg --list-keys output
    char list_cmd[256];
    snprintf(list_cmd, sizeof(list_cmd), "gpg --list-keys --with-colons --fingerprint '%s' 2>/dev/null", key_ids[k]);
    FILE *list_fp = popen(list_cmd, "r");
    if (!list_fp) {
      continue; // Skip this key if we can't list it
    }
 
    char list_output[4096];
    size_t list_len = fread(list_output, 1, sizeof(list_output) - 1, list_fp);
    list_output[list_len] = '\0';
    pclose(list_fp);
 
    // Check if it contains an Ed25519 key (algorithm 22)
    if (!strstr(list_output, ":22:") && !strstr(list_output, "ed25519")) {
      continue; // Skip non-Ed25519 keys
    }
 
    // Extract full 40-character fingerprint from "fpr:" line
    // Format: fpr:::::::::FINGERPRINT:
    // The fingerprint is field 10 (after 9 colons)
    char fingerprint[41] = {0};
    const char *fpr_marker = "\nfpr:";
    char *fpr_line = strstr(list_output, fpr_marker);
    if (fpr_line) {
      fpr_line += 1; // Skip the newline
      // Count 9 colons from the start of the line
      int colon_count = 0;
      while (*fpr_line && colon_count < 9) {
        if (*fpr_line == ':')
          colon_count++;
        fpr_line++;
      }
      // Now we should be at the start of the fingerprint
      // Extract up to 40 hex characters
      int fpr_len = 0;
      while (fpr_len < 40 && fpr_line[fpr_len] && fpr_line[fpr_len] != ':' && fpr_line[fpr_len] != '\n') {
        fingerprint[fpr_len] = fpr_line[fpr_len];
        fpr_len++;
      }
      fingerprint[fpr_len] = '\0';
    }
 
    // If fingerprint extraction failed, use the short key ID
    if (strlen(fingerprint) == 0) {
      log_warn("Failed to extract fingerprint for key %s, using short key ID", key_ids[k]);
      SAFE_STRNCPY(fingerprint, key_ids[k], sizeof(fingerprint));
    }
 
    log_debug("Key %s -> fingerprint: %s (length: %zu)", key_ids[k], fingerprint, strlen(fingerprint));
 
    // Allocate and store this key in gpg:KEYID format
    size_t gpg_key_len = strlen("gpg:") + strlen(fingerprint) + 1;
    (*keys_out)[valid_keys] = SAFE_MALLOC(gpg_key_len, char *);
    if (!(*keys_out)[valid_keys]) {
      // Cleanup on allocation failure
      for (size_t cleanup = 0; cleanup < valid_keys; cleanup++) {
        SAFE_FREE((*keys_out)[cleanup]);
      }
      SAFE_FREE(*keys_out);
      *keys_out = NULL;
      return SET_ERRNO(ERROR_MEMORY, "Failed to allocate GPG key string");
    }
 
    snprintf((*keys_out)[valid_keys], gpg_key_len, "gpg:%s", fingerprint);
    log_debug("Added valid Ed25519 key #%zu: %s", valid_keys, (*keys_out)[valid_keys]);
    valid_keys++;
  }
 
  if (valid_keys == 0) {
    SAFE_FREE(*keys_out);
    *keys_out = NULL;
    return SET_ERRNO(ERROR_CRYPTO_KEY, "No valid Ed25519 keys found in imported GPG keys");
  }
 
  *num_keys = valid_keys;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, ERROR_MEMORY, log_debug, log_warn, SAFE_FREE, SAFE_MALLOC, SAFE_STRNCPY, and SET_ERRNO.

Referenced by fetch_github_gpg_keys(), and fetch_gitlab_gpg_keys().

parse_keys_from_file()

asciichat_error_t parse_keys_from_file	(	const char *	path,
		public_key_t *	keys,
		size_t *	num_keys,
		size_t	max_keys
	)

#include <keys.h>

Parse SSH keys from file (supports authorized_keys and known_hosts formats)

Parameters

path	Path to key file (must not be NULL)
keys	Output array for parsed public keys (must not be NULL)
num_keys	Output parameter for number of keys parsed (must not be NULL)
max_keys	Maximum number of keys to parse (must be > 0)

Returns

ASCIICHAT_OK on success, error code on failure

Parses multiple SSH keys from file. Supports:

• authorized_keys format: One key per line (ssh-ed25519 AAAAC3... comment)
• **.pub file with multiple entries**: File containing multiple SSH public key entries, one per line (each line in ssh-ed25519 AAAAC3... comment format). This format is similar to authorized_keys and can contain any number of keys.
• known_hosts format: Multiple keys per line (hostname ssh-ed25519 AAAAC3... comment)

File format examples:

# authorized_keys format or .pub file with multiple entries
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... alice@example.com
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... bob@example.com

Note

Key filtering: Only Ed25519 and X25519 keys are parsed. RSA/ECDSA keys are skipped (not supported).

File format: Automatically detects file format based on content. Supports both authorized_keys format (one key per line) and known_hosts format. Also supports .pub files containing multiple key entries (one per line).

Maximum keys: Stops parsing after max_keys keys are found. Function returns ASCIICHAT_OK even if more keys exist in file.

Warning

File must exist and be readable. Returns error if file cannot be opened.

Definition at line 343 of file keys.c.

                                                                                                                {
  if (!path || !keys || !num_keys) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for key file parsing");
  }
 
  *num_keys = 0;
 
  if (!path_looks_like_path(path)) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid keys file path: %s", path);
  }
 
  char *normalized_path = NULL;
  asciichat_error_t path_result = path_validate_user_path(path, PATH_ROLE_CLIENT_KEYS, &normalized_path);
  if (path_result != ASCIICHAT_OK) {
    SAFE_FREE(normalized_path);
    return path_result;
  }
 
  FILE *f = platform_fopen(normalized_path, "r");
  if (!f) {
    SAFE_FREE(normalized_path);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to open keys file: %s", path);
  }
 
  char line[BUFFER_SIZE_LARGE];
  while (fgets(line, sizeof(line), f) && *num_keys < max_keys) {
    // Remove newline
    line[strcspn(line, "\r\n")] = 0;
 
    // Skip empty lines and comments
    if (strlen(line) == 0 || line[0] == '#') {
      continue;
    }
 
    if (parse_public_key(line, &keys[*num_keys]) == ASCIICHAT_OK) {
      (*num_keys)++;
    }
  }
 
  (void)fclose(f);
  SAFE_FREE(normalized_path);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, BUFFER_SIZE_LARGE, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, parse_public_key(), path_looks_like_path(), PATH_ROLE_CLIENT_KEYS, path_validate_user_path(), platform_fopen(), SAFE_FREE, and SET_ERRNO.

Referenced by parse_public_keys().

parse_private_key()

asciichat_error_t parse_private_key	(	const char *	path,
		private_key_t *	key_out
	)

#include <keys.h>

Parse SSH private key from file.

Parameters

path	Path to private key file
key_out	Output structure for parsed private key (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Parses private key from file. Supports:

• OpenSSH Ed25519: ~/.ssh/id_ed25519 (OpenSSH Ed25519 format)
• Raw hex file: File containing 64 hex chars for X25519 key

Note

Encrypted keys: If key is encrypted (has password), prompts for password and decrypts it using platform-specific password prompt.

SSH agent detection: If use_ssh_agent is true, key is loaded from SSH agent instead of file. Key stays in agent (not loaded into memory).

File permissions: Validates file permissions before parsing. Warns if file has overly permissive permissions (world-readable).

Key format: Currently only supports Ed25519 keys (OpenSSH format). RSA/ECDSA keys are NOT supported.

Warning

File permissions: Private key files should have restrictive permissions (0600). Function warns but does not fail on overly permissive permissions.

Definition at line 108 of file keys.c.

                                                                                  {
  if (!key_path || !key_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for private key parsing");
  }
 
  // Clear output structure
  memset(key_out, 0, sizeof(private_key_t));
 
  // Check for GPG key format: "gpg:KEYID" where KEYID is 8, 16, or 40 hex chars
  // - 8 chars: short key ID (last 8 chars of fingerprint)
  // - 16 chars: long key ID (last 16 chars of fingerprint)
  // - 40 chars: full fingerprint
  if (strncmp(key_path, "gpg:", 4) == 0) {
    const char *key_id = key_path + 4; // Skip "gpg:" prefix
 
    // Validate key ID format (must be 8, 16, or 40 hex characters)
    size_t key_id_len = strlen(key_id);
    if (key_id_len != 8 && key_id_len != 16 && key_id_len != 40) {
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid GPG key ID length: %zu (expected 8, 16, or 40 hex chars)",
                       key_id_len);
    }
 
    // Validate hex characters
    for (size_t i = 0; i < key_id_len; i++) {
      char c = key_id[i];
      if (!((c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F'))) {
        return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid GPG key ID: contains non-hex character '%c'", c);
      }
    }
 
    // Get public key and keygrip from GPG keyring
    uint8_t public_key[32];
    char keygrip[64];
    if (gpg_get_public_key(key_id, public_key, keygrip) != 0) {
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to get public key from GPG for key ID: %s", key_id);
    }
 
    // Populate private_key_t structure for GPG agent use
    key_out->type = KEY_TYPE_ED25519;
    key_out->use_gpg_agent = true;
    key_out->use_ssh_agent = false;
 
    // Store public key (for handshake and verification)
    memcpy(key_out->public_key, public_key, 32);
 
    // Store keygrip (for GPG agent signing operations)
    platform_strncpy(key_out->gpg_keygrip, sizeof(key_out->gpg_keygrip), keygrip, sizeof(key_out->gpg_keygrip) - 1);
 
    // Store comment for display
    safe_snprintf(key_out->key_comment, sizeof(key_out->key_comment), "GPG key %s", key_id);
 
    // Clear the key.ed25519 field (we don't have the private key in memory)
    // The private key stays protected in GPG agent
    memset(key_out->key.ed25519, 0, 64);
 
    // Set the public key in the second half of ed25519 key (standard Ed25519 format)
    // This is for compatibility with code that expects the public key at offset 32
    memcpy(key_out->key.ed25519 + 32, public_key, 32);
 
    log_info("Loaded GPG key %s (keygrip: %.40s) for agent signing", key_id, keygrip);
    return ASCIICHAT_OK;
  }
 
  // Try SSH private key parsing
  char *normalized_path = NULL;
  asciichat_error_t path_result = path_validate_user_path(key_path, PATH_ROLE_KEY_PRIVATE, &normalized_path);
  if (path_result != ASCIICHAT_OK) {
    SAFE_FREE(normalized_path);
    return path_result;
  }
  asciichat_error_t result = parse_ssh_private_key(normalized_path, key_out);
  SAFE_FREE(normalized_path);
  return result;
}

References ASCIICHAT_OK, private_key_t::ed25519, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, gpg_get_public_key(), private_key_t::gpg_keygrip, private_key_t::key, private_key_t::key_comment, KEY_TYPE_ED25519, log_info, parse_ssh_private_key(), PATH_ROLE_KEY_PRIVATE, path_validate_user_path(), platform_strncpy(), private_key_t::public_key, SAFE_FREE, safe_snprintf(), SET_ERRNO, private_key_t::type, private_key_t::use_gpg_agent, and private_key_t::use_ssh_agent.

Referenced by client_crypto_init().

parse_public_key()

asciichat_error_t parse_public_key	(	const char *	input,
		public_key_t *	key_out
	)

#include <keys.h>

Parse SSH/GPG public key from any format (returns first key only)

Parameters

input	Key input in various formats (see below)
key_out	Output structure for parsed public key (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Parses public key from various input formats:

Supported formats:

• SSH Ed25519: "ssh-ed25519 AAAAC3... comment" (direct key string)
• GitHub SSH: "github:username" (fetches from https://github.com/username.keys, returns first Ed25519 key)
• GitLab SSH: "gitlab:username" (fetches from https://gitlab.com/username.keys, returns first Ed25519 key)
• GitHub GPG: "github:username.gpg" (fetches GPG key from https://github.com/username.gpg)
• GitLab GPG: "gitlab:username.gpg" (fetches GPG key from https://gitlab.com/username.gpg)
• GPG keyring: "gpg:0xKEYID" (shells out to gpg --export KEYID)
• File path: Path to .pub file or any file containing key (reads first line)
• Raw hex: 64 hex chars for X25519 key

File support: When a file path is provided, the file is read and the first line is parsed as an SSH public key. Common formats:

• .pub file: Standard SSH public key file (one key per file, reads first line)
• Any text file: First line containing SSH key format is used

Note

Key normalization: All keys are converted to X25519 format for key exchange. Ed25519 keys are converted using libsodium conversion function.

GPG support: GPG Ed25519 keys are fully supported. Accepts 8, 16, or 40 character key IDs (short/long/full fingerprint). Requires gpg binary in PATH and gpg-agent running.

GitHub/GitLab fetching: Uses BearSSL for HTTPS requests. Requires network connectivity. Only first Ed25519 key is returned. For multiple keys, use parse_public_keys() instead.

File path: Reads first line of file and parses as SSH key format. File must exist and be readable. For files with multiple keys (one per line), use parse_keys_from_file() instead.

Warning

Network operations: GitHub/GitLab fetching requires network connectivity. May fail if network is unavailable or endpoints are blocked.

Definition at line 24 of file keys.c.

                                                                             {
  if (!input || !key_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for public key parsing");
  }
 
  // Clear output structure
  memset(key_out, 0, sizeof(public_key_t));
 
  // Try SSH key parsing first
  if (strncmp(input, "ssh-ed25519", 11) == 0) {
    key_out->type = KEY_TYPE_ED25519;
    asciichat_error_t result = parse_ssh_ed25519_line(input, key_out->key);
    if (result == ASCIICHAT_OK) {
      platform_strncpy(key_out->comment, sizeof(key_out->comment), "ssh-ed25519", sizeof(key_out->comment) - 1);
    }
    return result;
  }
 
  // Try GPG key parsing
  if (strncmp(input, "gpg:", 4) == 0) {
    return parse_gpg_key(input + 4, key_out);
  }
 
  // Try HTTPS key fetching (GitHub/GitLab) - delegate to parse_public_keys and return first
  if (strncmp(input, "github:", 7) == 0 || strncmp(input, "gitlab:", 7) == 0) {
    public_key_t keys[1];
    size_t num_keys = 0;
    asciichat_error_t result = parse_public_keys(input, keys, &num_keys, 1);
    if (result == ASCIICHAT_OK && num_keys > 0) {
      *key_out = keys[0];
    }
    return result;
  }
 
  // Try raw hex key (64 hex chars = 32 bytes)
  if (strlen(input) == 64) {
    // Check if it's valid hex
    bool is_valid_hex = true;
    for (int i = 0; i < 64; i++) {
      if (!((input[i] >= '0' && input[i] <= '9') || (input[i] >= 'a' && input[i] <= 'f') ||
            (input[i] >= 'A' && input[i] <= 'F'))) {
        is_valid_hex = false;
        break;
      }
    }
 
    if (is_valid_hex) {
      // Assume it's a raw X25519 public key in hex (default for raw hex)
      key_out->type = KEY_TYPE_X25519;
      // Use hex_decode utility to safely decode hex string to binary
      if (hex_decode(input, key_out->key, 32) != ASCIICHAT_OK) {
        return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to decode hex key");
      }
      platform_strncpy(key_out->comment, sizeof(key_out->comment), "raw-hex", sizeof(key_out->comment) - 1);
      return ASCIICHAT_OK;
    }
  }
 
  if (path_looks_like_path(input)) {
    char *normalized_path = NULL;
    asciichat_error_t path_result = path_validate_user_path(input, PATH_ROLE_KEY_PUBLIC, &normalized_path);
    if (path_result != ASCIICHAT_OK) {
      SAFE_FREE(normalized_path);
      return path_result;
    }
 
    FILE *f = platform_fopen(normalized_path, "r");
    if (f) {
      char line[BUFFER_SIZE_LARGE];
      if (fgets(line, sizeof(line), f)) {
        (void)fclose(f);
        SAFE_FREE(normalized_path);
        // Remove newline
        line[strcspn(line, "\r\n")] = 0;
        return parse_public_key(line, key_out);
      }
      (void)fclose(f);
    }
    SAFE_FREE(normalized_path);
  }
 
  return SET_ERRNO(ERROR_CRYPTO_KEY, "Unsupported key format: %s", input);
}

References ASCIICHAT_OK, BUFFER_SIZE_LARGE, public_key_t::comment, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, hex_decode(), public_key_t::key, KEY_TYPE_ED25519, KEY_TYPE_X25519, parse_gpg_key(), parse_public_key(), parse_public_keys(), parse_ssh_ed25519_line(), path_looks_like_path(), PATH_ROLE_KEY_PUBLIC, path_validate_user_path(), platform_fopen(), platform_strncpy(), SAFE_FREE, SET_ERRNO, and public_key_t::type.

Referenced by check_known_host(), parse_keys_from_file(), parse_public_key(), and parse_public_keys().

parse_public_keys()

asciichat_error_t parse_public_keys	(	const char *	input,
		public_key_t *	keys_out,
		size_t *	num_keys,
		size_t	max_keys
	)

#include <keys.h>

Parse all SSH/GPG public keys from any format (returns all keys)

Parameters

input	Key input in various formats (see parse_public_key for supported formats)
keys_out	Output array for parsed public keys (must not be NULL)
num_keys	Output parameter for number of keys parsed (must not be NULL)
max_keys	Maximum number of keys to parse (must be > 0)

Returns

ASCIICHAT_OK on success, error code on failure

Similar to parse_public_key(), but returns ALL keys for formats that support multiple keys:

Multiple key support:

• GitHub SSH: "github:username" - returns ALL Ed25519 keys from user's profile
• GitLab SSH: "gitlab:username" - returns ALL Ed25519 keys from user's profile
• File path: Returns all keys from file (one per line)

Single key formats (behaves like parse_public_key):

• SSH Ed25519: "ssh-ed25519 AAAAC3..." - returns single key
• Raw hex: 64 hex chars - returns single key
• GPG formats: Returns single key

This function is useful when you need to verify against ANY of a user's keys, such as when a user has multiple SSH keys for different machines on their GitHub/GitLab account.

Note

GitHub/GitLab: Users often have multiple SSH keys for different machines. This function fetches all keys so you can verify against any of them.

Key filtering: Only Ed25519 keys are returned. RSA/ECDSA keys are skipped.

Warning

Network operations: GitHub/GitLab fetching requires network connectivity.

Definition at line 187 of file keys.c.

                                                                                                                  {
  if (!input || !keys_out || !num_keys || max_keys == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for multi-key parsing");
  }
 
  *num_keys = 0;
 
  // Check for direct SSH Ed25519 key format BEFORE checking for file paths
  // (SSH keys can contain '/' in base64, which would match path_looks_like_path)
  if (strncmp(input, "ssh-ed25519", 11) == 0) {
    asciichat_error_t result = parse_public_key(input, &keys_out[0]);
    if (result == ASCIICHAT_OK) {
      *num_keys = 1;
    }
    return result;
  }
 
  // Check if this is a GitHub/GitLab reference - these support multiple keys
  if (strncmp(input, "github:", 7) == 0 || strncmp(input, "gitlab:", 7) == 0) {
    const char *username = input + 7; // Skip "github:" or "gitlab:"
    bool is_github = (strncmp(input, "github:", 7) == 0);
    bool is_gpg = (strstr(username, ".gpg") != NULL);
 
    char **keys = NULL;
    size_t num_fetched_keys = 0;
    asciichat_error_t result;
 
    if (is_github) {
      if (is_gpg) {
        result = fetch_github_gpg_keys(username, &keys, &num_fetched_keys);
      } else {
        result = fetch_github_ssh_keys(username, &keys, &num_fetched_keys);
      }
    } else {
      if (is_gpg) {
        result = fetch_gitlab_gpg_keys(username, &keys, &num_fetched_keys);
      } else {
        result = fetch_gitlab_ssh_keys(username, &keys, &num_fetched_keys);
      }
    }
 
    if (result != ASCIICHAT_OK || num_fetched_keys == 0) {
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to fetch keys from %s for user: %s", is_github ? "GitHub" : "GitLab",
                       username);
    }
 
    // Parse each fetched key (only Ed25519 keys will succeed)
    for (size_t i = 0; i < num_fetched_keys && *num_keys < max_keys; i++) {
      if (parse_public_key(keys[i], &keys_out[*num_keys]) == ASCIICHAT_OK) {
        (*num_keys)++;
      }
      // Non-Ed25519 keys are silently skipped
    }
 
    // Free the keys array
    for (size_t i = 0; i < num_fetched_keys; i++) {
      SAFE_FREE(keys[i]);
    }
    SAFE_FREE(keys);
 
    if (*num_keys == 0) {
      return SET_ERRNO(ERROR_CRYPTO_KEY, "No valid Ed25519 keys found for %s user: %s", is_github ? "GitHub" : "GitLab",
                       username);
    }
 
    log_info("Parsed %zu Ed25519 key(s) from %s user: %s", *num_keys, is_github ? "GitHub" : "GitLab", username);
    return ASCIICHAT_OK;
  }
 
  // For file paths, delegate to parse_keys_from_file
  if (path_looks_like_path(input)) {
    return parse_keys_from_file(input, keys_out, num_keys, max_keys);
  }
 
  // For all other formats, use single-key parsing
  asciichat_error_t result = parse_public_key(input, &keys_out[0]);
  if (result == ASCIICHAT_OK) {
    *num_keys = 1;
  }
  return result;
}

References ASCIICHAT_OK, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, fetch_github_gpg_keys(), fetch_github_ssh_keys(), fetch_gitlab_gpg_keys(), fetch_gitlab_ssh_keys(), log_info, parse_keys_from_file(), parse_public_key(), path_looks_like_path(), SAFE_FREE, and SET_ERRNO.

Referenced by crypto_handshake_client_key_exchange(), and parse_public_key().

parse_ssh_ed25519_line()

asciichat_error_t parse_ssh_ed25519_line	(	const char *	line,
		uint8_t	ed25519_pk[32]
	)

#include <ssh_keys.h>

Parse SSH Ed25519 public key from "ssh-ed25519 AAAAC3..." format.

Parameters

line	SSH key line to parse (must not be NULL)
ed25519_pk	Output buffer for Ed25519 public key (32 bytes, must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Parses SSH Ed25519 public key from standard SSH public key format. Format: "ssh-ed25519 <base64_key> [comment]"

Note

Format: Expects "ssh-ed25519" prefix followed by base64-encoded public key. Optional comment after key is ignored.

Base64 decoding: Decodes base64 key to extract 32-byte Ed25519 public key. Validates key format and length.

Key size: Ed25519 public key is exactly 32 bytes. Returns error if decoded key is not 32 bytes.

Warning

Key format: Must start with "ssh-ed25519". Other key types (RSA, ECDSA) are NOT supported.

Definition at line 167 of file ssh_keys.c.

                                                                                   {
  if (!line || !ed25519_pk) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: line=%p, ed25519_pk=%p", line, ed25519_pk);
  }
 
  // Find "ssh-ed25519 "
  const char *type_start = strstr(line, "ssh-ed25519");
  if (!type_start) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "SSH key line does not contain 'ssh-ed25519'");
  }
 
  // Skip to base64 part
  const char *base64_start = type_start + 11; // strlen("ssh-ed25519")
  while (*base64_start == ' ' || *base64_start == '\t') {
    base64_start++;
  }
 
  // Find end of base64 (space, newline, or end of string)
  const char *base64_end = base64_start;
  while (*base64_end && *base64_end != ' ' && *base64_end != '\t' && *base64_end != '\n' && *base64_end != '\r') {
    base64_end++;
  }
 
  size_t base64_len = base64_end - base64_start;
 
  // Base64 decode
  uint8_t *blob;
  size_t blob_len;
  if (base64_decode_ssh_key(base64_start, base64_len, &blob, &blob_len) != 0) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to decode SSH key base64 data");
  }
 
  // Parse SSH key blob structure:
  // [4 bytes: length of "ssh-ed25519"]
  // [11 bytes: "ssh-ed25519"]
  // [4 bytes: length of public key (32)]
  // [32 bytes: Ed25519 public key]
 
  if (blob_len < SSH_KEY_HEADER_SIZE) {
    SAFE_FREE(blob);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "SSH key blob too small: %zu bytes (expected at least %d)", blob_len,
                     SSH_KEY_HEADER_SIZE);
  }
 
  // Extract Ed25519 public key (last 32 bytes)
  memcpy(ed25519_pk, blob + blob_len - ED25519_PUBLIC_KEY_SIZE, ED25519_PUBLIC_KEY_SIZE);
  SAFE_FREE(blob);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ED25519_PUBLIC_KEY_SIZE, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, SAFE_FREE, SET_ERRNO, and SSH_KEY_HEADER_SIZE.

Referenced by parse_public_key(), and parse_ssh_private_key().

parse_ssh_keys_from_response()

asciichat_error_t parse_ssh_keys_from_response	(	const char *	response_text,
		size_t	response_len,
		char ***	keys_out,
		size_t *	num_keys,
		size_t	max_keys
	)

#include <https_keys.h>

Parse SSH keys from HTTPS response text.

Parameters

response_text	HTTPS response containing SSH keys (must not be NULL)
response_len	Length of response text
keys_out	Output array of parsed SSH keys (must not be NULL)
num_keys	Output parameter for number of keys parsed (must not be NULL)
max_keys	Maximum number of keys to parse (must be > 0)

Returns

ASCIICHAT_OK on success, error code on failure

Parses SSH keys from HTTPS response text (one key per line). Extracts Ed25519 keys and allocates memory for each key string.

Note

Response format: Expects one SSH key per line. Format: "ssh-ed25519 AAAAC3... comment" (one key per line)

Key filtering: Only Ed25519 SSH keys are parsed. Other key types (RSA, ECDSA) are skipped.

Memory allocation: Allocates memory for each key string. Caller must free each string and the array.

Maximum keys: Stops parsing after max_keys keys are found. Function returns ASCIICHAT_OK even if more keys exist in response.

Warning

Memory leak: Caller must free returned strings and array. Function allocates memory that must be freed.

Definition at line 310 of file https_keys.c.

                                                                                  {
  if (!response_text || !keys_out || !num_keys) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for SSH key parsing");
    return ERROR_INVALID_PARAM;
  }
 
  *num_keys = 0;
  *keys_out = NULL;
 
  // Count the number of SSH keys in the response
  size_t key_count = 0;
  const char *line_start = response_text;
  const char *line_end;
 
  while ((line_end = strchr(line_start, '\n')) != NULL) {
    size_t line_len = line_end - line_start;
    if (line_len > 0 && line_start[0] != '\r' && line_start[0] != '\n') {
      key_count++;
    }
    line_start = line_end + 1;
  }
 
  // Handle last line if it doesn't end with newline
  if (line_start < response_text + response_len) {
    key_count++;
  }
 
  if (key_count == 0) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "No SSH keys found in response");
    return ERROR_CRYPTO_KEY;
  }
 
  if (key_count > max_keys) {
    key_count = max_keys;
  }
 
  // Allocate array for key strings
  *keys_out = SAFE_MALLOC(sizeof(char *) * key_count, char **);
  if (!*keys_out) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate SSH keys array");
  }
 
  // Parse each SSH key line
  line_start = response_text;
  size_t parsed_keys = 0;
 
  while (parsed_keys < key_count && (line_end = strchr(line_start, '\n')) != NULL) {
    size_t line_len = line_end - line_start;
 
    // Skip empty lines
    if (line_len > 0 && line_start[0] != '\r' && line_start[0] != '\n') {
      // Allocate space for this key line
      (*keys_out)[parsed_keys] = SAFE_MALLOC(line_len + 1, char *);
      if (!(*keys_out)[parsed_keys]) {
        // Cleanup previously allocated keys
        for (size_t i = 0; i < parsed_keys; i++) {
          SAFE_FREE((*keys_out)[i]);
        }
        SAFE_FREE(*keys_out);
        *keys_out = NULL;
        return SET_ERRNO(ERROR_MEMORY, "Failed to allocate SSH key string");
      }
 
      // Copy the key line
      memcpy((*keys_out)[parsed_keys], line_start, line_len);
      (*keys_out)[parsed_keys][line_len] = '\0';
 
      parsed_keys++;
    }
 
    line_start = line_end + 1;
  }
 
  // Handle last line if it doesn't end with newline
  if (parsed_keys < key_count && line_start < response_text + response_len) {
    size_t line_len = (response_text + response_len) - line_start;
    if (line_len > 0) {
      (*keys_out)[parsed_keys] = SAFE_MALLOC(line_len + 1, char *);
      if (!(*keys_out)[parsed_keys]) {
        // Cleanup previously allocated keys
        for (size_t i = 0; i < parsed_keys; i++) {
          SAFE_FREE((*keys_out)[i]);
        }
        SAFE_FREE(*keys_out);
        *keys_out = NULL;
        return SET_ERRNO(ERROR_MEMORY, "Failed to allocate SSH key string");
      }
      memcpy((*keys_out)[parsed_keys], line_start, line_len);
      (*keys_out)[parsed_keys][line_len] = '\0';
      parsed_keys++;
    }
  }
 
  *num_keys = parsed_keys;
  return ASCIICHAT_OK;
}

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

Referenced by fetch_github_ssh_keys(), and fetch_gitlab_ssh_keys().

parse_ssh_private_key()

asciichat_error_t parse_ssh_private_key	(	const char *	key_path,
		private_key_t *	key_out
	)

#include <ssh_keys.h>

Parse SSH Ed25519 private key from file.

Parameters

key_path	Path to SSH private key file (must not be NULL)
key_out	Output structure for parsed private key (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Parses OpenSSH Ed25519 private key from file. Supports both encrypted and unencrypted keys.

Note

Key format: Supports OpenSSH private key format (openssh-key-v1). Format: "-----BEGIN OPENSSH PRIVATE KEY-----" ... "-----END OPENSSH PRIVATE KEY-----"

Encrypted keys: If key is encrypted, prompts for password and decrypts it natively. Uses bcrypt_pbkdf (from libsodium-bcrypt-pbkdf) + BearSSL AES (aes256-ctr/aes256-cbc) for OpenSSH format decryption. No external tools (ssh-keygen) required.

Key structure: Parses OpenSSH key structure:

• Magic: "openssh-key-v1\0"
• Ciphername: "none" for unencrypted, cipher name for encrypted
• KDF name and options (for encrypted keys)
• Number of keys (must be 1)
• Public key (for verification)
• Private key blob (decrypted if encrypted)

Ed25519 extraction: Extracts Ed25519 seed (32 bytes) and public key (32 bytes) from private key blob. Stores as 64-byte Ed25519 key (seed + public).

File validation: Validates file permissions before parsing. Warns if file has overly permissive permissions (world-readable).

Warning

Key format: Only Ed25519 keys are supported. RSA/ECDSA keys will return error.

File permissions: Private key files should have restrictive permissions (0600). Function warns but does not fail on overly permissive permissions.

Password: Encrypted keys require password for native decryption. Decryption is done using bcrypt_pbkdf + BearSSL AES (supports aes256-ctr and aes256-cbc). May fail if password is incorrect, KDF parameters are unsupported, or unsupported encryption cipher.

Definition at line 218 of file ssh_keys.c.

                                                                                      {
  if (!key_path || !key_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key_path=%p, key_out=%p", key_path, key_out);
  }
 
  // First, check if we can get the key from ssh-agent (password-free)
  // This requires reading the public key from the .pub file
  char pub_key_path[BUFFER_SIZE_LARGE];
  safe_snprintf(pub_key_path, sizeof(pub_key_path), "%s.pub", key_path);
 
  FILE *pub_f = platform_fopen(pub_key_path, "r");
  if (pub_f) {
    char pub_line[BUFFER_SIZE_LARGE];
    if (fgets(pub_line, sizeof(pub_line), pub_f)) {
      public_key_t pub_key = {0};
      pub_key.type = KEY_TYPE_ED25519;
 
      if (parse_ssh_ed25519_line(pub_line, pub_key.key) == ASCIICHAT_OK) {
        // Check if this key is in ssh-agent
        if (ssh_agent_has_key(&pub_key)) {
          fclose(pub_f);
          log_info("Key found in ssh-agent - using cached key (no password required)");
          // Key is in agent, we can use it
          key_out->type = KEY_TYPE_ED25519;
          key_out->use_ssh_agent = true;
          memcpy(key_out->key.ed25519 + 32, pub_key.key, 32); // Copy public key to second half
          memcpy(key_out->public_key, pub_key.key, 32);       // Also store in public_key field
          // Note: We don't have the private key seed, but ssh-agent will sign for us
          return ASCIICHAT_OK;
        } else {
          log_debug("Key not found in ssh-agent - will decrypt from file");
        }
      }
    }
    fclose(pub_f);
  }
 
  // Validate the SSH key file first
  asciichat_error_t validation_result = validate_ssh_key_file(key_path);
  if (validation_result != ASCIICHAT_OK) {
    return validation_result;
  }
 
  // Read the private key file
  FILE *f = platform_fopen(key_path, "r");
  if (!f) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Cannot read private key file: %s", key_path);
  }
 
  // Read the entire file
  char *file_content = NULL;
  size_t file_size = 0;
  char buffer[BUFFER_SIZE_XXLARGE];
  size_t bytes_read;
 
  while ((bytes_read = fread(buffer, 1, sizeof(buffer), f)) > 0) {
    file_content = SAFE_REALLOC(file_content, file_size + bytes_read + 1, char *);
    if (!file_content) {
      (void)fclose(f);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Out of memory reading private key file");
    }
    memcpy(file_content + file_size, buffer, bytes_read);
    file_size += bytes_read;
  }
  (void)fclose(f);
 
  if (file_size == 0) {
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Private key file is empty: %s", key_path);
  }
 
  file_content[file_size] = '\0';
 
  // Check if this is an OpenSSH private key
  if (strstr(file_content, "BEGIN OPENSSH PRIVATE KEY") == NULL) {
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Unsupported private key format (only OpenSSH format supported): %s", key_path);
  }
 
  // Parse the OpenSSH private key format
  // The format is:
  // -----BEGIN OPENSSH PRIVATE KEY-----
  // [base64 encoded data]
  // -----END OPENSSH PRIVATE KEY-----
 
  // Find the base64 data between the headers
  const char *base64_start = strstr(file_content, "-----BEGIN OPENSSH PRIVATE KEY-----");
  if (!base64_start) {
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid OpenSSH private key format: %s", key_path);
  }
 
  // Skip to the end of the header line
  base64_start = strchr(base64_start, '\n');
  if (!base64_start) {
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid OpenSSH private key format: %s", key_path);
  }
  base64_start++; // Skip the newline
 
  // Find the end of the base64 data
  const char *base64_end = strstr(base64_start, "-----END OPENSSH PRIVATE KEY-----");
  if (!base64_end) {
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid OpenSSH private key format: %s", key_path);
  }
 
  // Remove any whitespace/newlines from the base64 data
  char *clean_base64 = SAFE_MALLOC(base64_end - base64_start + 1, char *);
  char *clean_ptr = clean_base64;
  for (const char *p = base64_start; p < base64_end; p++) {
    if (*p != '\n' && *p != '\r' && *p != ' ' && *p != '\t') {
      *clean_ptr++ = *p;
    }
  }
  *clean_ptr = '\0';
 
  // Decode the base64 data
  uint8_t *key_blob;
  size_t key_blob_len;
  asciichat_error_t decode_result = base64_decode_ssh_key(clean_base64, strlen(clean_base64), &key_blob, &key_blob_len);
  SAFE_FREE(clean_base64);
 
  if (decode_result != ASCIICHAT_OK) {
    SAFE_FREE(file_content);
    return decode_result;
  }
 
  // Parse the OpenSSH private key structure
  // Format: [4 bytes: magic] [4 bytes: ciphername length] [ciphername] [4 bytes: kdfname length] [kdfname]
  //         [4 bytes: kdfoptions length] [kdfoptions] [4 bytes: num keys] [4 bytes: pubkey length] [pubkey]
  //         [4 bytes: privkey length] [privkey]
 
  if (key_blob_len < 4) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key blob too small: %s", key_path);
  }
 
  // Check magic number (should be "openssh-key-v1\0")
  if (memcmp(key_blob, "openssh-key-v1\0", 15) != 0) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid OpenSSH private key magic: %s", key_path);
  }
 
  size_t offset = 15; // Skip magic
 
  // Read ciphername
  if (offset + 4 > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at ciphername: %s", key_path);
  }
 
  uint32_t ciphername_len = read_u32_be(&key_blob[offset]);
  offset += 4;
 
  if (offset + ciphername_len > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at ciphername data: %s", key_path);
  }
 
  // Store the position of ciphername for later use
  size_t ciphername_pos = offset;
 
  // Check if key is encrypted
  bool is_encrypted = (ciphername_len > 0 && memcmp(key_blob + offset, "none", 4) != 0);
 
  offset += ciphername_len;
 
  // Skip kdfname and kdfoptions (we don't support encryption)
  if (offset + 4 > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at kdfname: %s", key_path);
  }
 
  uint32_t kdfname_len = read_u32_be(&key_blob[offset]);
  offset += 4;
 
  // Store the position of kdfname for later use
  size_t kdfname_pos = offset;
 
  offset += kdfname_len;
 
  if (offset + 4 > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at kdfoptions: %s", key_path);
  }
 
  uint32_t kdfoptions_len = read_u32_be(&key_blob[offset]);
  offset += 4 + kdfoptions_len;
 
  // Handle encrypted keys
  if (is_encrypted) {
    // Parse the cipher name from the stored position
    char ciphername[32] = {0};
    if (ciphername_len > 0 && ciphername_len < sizeof(ciphername)) {
      memcpy(ciphername, key_blob + ciphername_pos, ciphername_len);
    }
 
    // Parse the KDF name from the stored position
    char kdfname[32] = {0};
    if (kdfname_len > 0 && kdfname_len < sizeof(kdfname)) {
      memcpy(kdfname, key_blob + kdfname_pos, kdfname_len);
    }
 
    log_debug("Cipher: %s, KDF: %s", ciphername, kdfname);
 
    // Check if we support this encryption method
    if (strcmp(ciphername, "aes256-ctr") != 0 && strcmp(ciphername, "aes256-cbc") != 0) {
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY,
                       "Unsupported cipher '%s' for encrypted SSH key: %s\n"
                       "Supported ciphers: aes256-ctr, aes256-cbc",
                       ciphername, key_path);
    }
 
    if (strcmp(kdfname, "bcrypt") != 0) {
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY,
                       "Unsupported KDF '%s' for encrypted SSH key: %s\n"
                       "Only bcrypt KDF is supported",
                       kdfname, key_path);
    }
 
    // Parse KDF options (bcrypt salt and rounds)
    if (kdfoptions_len < 8) {
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid KDF options length: %s", key_path);
    }
 
    // Parse KDF options: [salt_length:4][salt:N][rounds:4]
    size_t kdf_opt_offset = offset - kdfoptions_len;
 
    // Read salt length
    if (kdf_opt_offset + 4 > key_blob_len) {
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "KDF options truncated at salt length: %s", key_path);
    }
    uint32_t salt_len = read_u32_be(&key_blob[kdf_opt_offset]);
    kdf_opt_offset += 4;
 
    // Read salt
    if (salt_len != 16) {
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Unexpected bcrypt salt length %u (expected 16): %s", salt_len, key_path);
    }
    if (kdf_opt_offset + salt_len > key_blob_len) {
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "KDF options truncated at salt data: %s", key_path);
    }
    uint8_t bcrypt_salt[16];
    memcpy(bcrypt_salt, key_blob + kdf_opt_offset, salt_len);
    kdf_opt_offset += salt_len;
 
    // Read rounds
    if (kdf_opt_offset + 4 > key_blob_len) {
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "KDF options truncated at rounds: %s", key_path);
    }
    uint32_t bcrypt_rounds = read_u32_be(&key_blob[kdf_opt_offset]);
 
    // Check for password in environment variable first
    const char *env_password = platform_getenv("ASCII_CHAT_KEY_PASSWORD");
    char *password = NULL;
    if (env_password && strlen(env_password) > 0) {
      // Use password from environment variable
      password = platform_strdup(env_password);
      if (!password) {
        SAFE_FREE(key_blob);
        SAFE_FREE(file_content);
        return SET_ERRNO(ERROR_MEMORY, "Failed to allocate memory for password");
      }
    } else {
      // Prompt for password interactively - allocate buffer for input
      password = SAFE_MALLOC(1024, char *);
      if (!password) {
        SAFE_FREE(key_blob);
        SAFE_FREE(file_content);
        return SET_ERRNO(ERROR_MEMORY, "Failed to allocate memory for password");
      }
      if (prompt_password_simple("Encrypted SSH key - enter passphrase", password, 1024) != 0) {
        SAFE_FREE(key_blob);
        SAFE_FREE(file_content);
        return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to read passphrase for encrypted key: %s", key_path);
      }
    }
 
    // Native OpenSSH key decryption using bcrypt_pbkdf + BearSSL AES
 
    // Skip past the unencrypted public key section to get to encrypted private keys
    // Format: [num_keys:4][pubkey_len:4][pubkey:N]...[encrypted_len:4][encrypted:N]
 
    // Read num_keys
    if (offset + 4 > key_blob_len) {
      sodium_memzero(password, strlen(password));
      SAFE_FREE(password);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Encrypted key truncated at num_keys: %s", key_path);
    }
    uint32_t num_keys = read_u32_be(&key_blob[offset]);
    offset += 4;
    log_debug("num_keys=%u", num_keys);
 
    // Skip all public keys
    for (uint32_t i = 0; i < num_keys; i++) {
      if (offset + 4 > key_blob_len) {
        sodium_memzero(password, strlen(password));
        SAFE_FREE(password);
        SAFE_FREE(key_blob);
        SAFE_FREE(file_content);
        return SET_ERRNO(ERROR_CRYPTO_KEY, "Encrypted key truncated at pubkey %u length: %s", i, key_path);
      }
      uint32_t pubkey_len = read_u32_be(&key_blob[offset]);
      offset += 4;
      log_debug("Skipping public key %u: %u bytes", i, pubkey_len);
 
      if (offset + pubkey_len > key_blob_len) {
        sodium_memzero(password, strlen(password));
        SAFE_FREE(password);
        SAFE_FREE(key_blob);
        SAFE_FREE(file_content);
        return SET_ERRNO(ERROR_CRYPTO_KEY, "Encrypted key truncated at pubkey %u data: %s", i, key_path);
      }
      offset += pubkey_len;
    }
 
    // Read encrypted private keys length
    if (offset + 4 > key_blob_len) {
      sodium_memzero(password, strlen(password));
      SAFE_FREE(password);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Encrypted key truncated at encrypted_len: %s", key_path);
    }
    uint32_t encrypted_len = read_u32_be(&key_blob[offset]);
    offset += 4;
 
    // Now offset points to the actual encrypted data
    size_t encrypted_data_start = offset;
    size_t encrypted_data_len = encrypted_len;
 
    if (encrypted_data_len < 16) {
      sodium_memzero(password, strlen(password));
      SAFE_FREE(password);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Encrypted data too small: %s", key_path);
    }
 
    // Extract encrypted blob (includes everything from offset onwards)
    const uint8_t *encrypted_blob = key_blob + encrypted_data_start;
 
    // Call native decryption function
    uint8_t *decrypted_blob = NULL;
    size_t decrypted_blob_len = 0;
 
    // Note: decrypt_openssh_private_key derives IV from bcrypt_pbkdf, not from encrypted data
    asciichat_error_t decrypt_result =
        decrypt_openssh_private_key(encrypted_blob, encrypted_data_len, password, bcrypt_salt, salt_len, bcrypt_rounds,
                                    ciphername, &decrypted_blob, &decrypted_blob_len);
 
    // Clean up password immediately after use
    sodium_memzero(password, strlen(password));
    SAFE_FREE(password);
 
    if (decrypt_result != ASCIICHAT_OK) {
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return decrypt_result;
    }
 
    // Parse the decrypted private key structure
    // OpenSSH format (decrypted):
    //   [checkint1:4][checkint2:4][keytype:string][pubkey:string][privkey:string][comment:string][padding:N]
 
    if (decrypted_blob_len < 8) {
      SAFE_FREE(decrypted_blob);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Decrypted data too small (no checkints): %s", key_path);
    }
 
    // Verify checkints (first 8 bytes should be two identical 32-bit values)
    uint32_t checkint1 = read_u32_be(&decrypted_blob[0]);
    uint32_t checkint2 = read_u32_be(&decrypted_blob[4]);
    if (checkint1 != checkint2) {
      SAFE_FREE(decrypted_blob);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY,
                       "Incorrect passphrase or corrupted key (checkint mismatch): %s\n"
                       "Expected matching checkints, got 0x%08x != 0x%08x",
                       key_path, checkint1, checkint2);
    }
 
    // Parse the decrypted private key structure manually
    // Format after checkints: [keytype:string][pubkey:string][privkey:string][comment:string][padding:N]
    size_t dec_offset = 8; // Skip checkints
 
    // Read keytype length
    if (dec_offset + 4 > decrypted_blob_len) {
      SAFE_FREE(decrypted_blob);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Decrypted key truncated at keytype length: %s", key_path);
    }
    uint32_t keytype_len = read_u32_be(&decrypted_blob[dec_offset]);
    dec_offset += 4;
 
    // Read keytype
    if (dec_offset + keytype_len > decrypted_blob_len) {
      SAFE_FREE(decrypted_blob);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Decrypted key truncated at keytype data: %s", key_path);
    }
    char keytype[BUFFER_SIZE_SMALL / 4] = {0}; // SSH key type strings are short
    if (keytype_len > 0 && keytype_len < sizeof(keytype)) {
      memcpy(keytype, decrypted_blob + dec_offset, keytype_len);
    }
    dec_offset += keytype_len;
 
    // Check if it's Ed25519
    if (strcmp(keytype, "ssh-ed25519") != 0) {
      SAFE_FREE(decrypted_blob);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Unsupported key type after decryption: '%s'", keytype);
    }
 
    // Read public key length
    if (dec_offset + 4 > decrypted_blob_len) {
      SAFE_FREE(decrypted_blob);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Decrypted key truncated at pubkey length: %s", key_path);
    }
    uint32_t pubkey_data_len = read_u32_be(&decrypted_blob[dec_offset]);
    dec_offset += 4;
 
    // Read public key (32 bytes for Ed25519)
    if (pubkey_data_len != 32) {
      SAFE_FREE(decrypted_blob);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid Ed25519 public key length: %u (expected 32)", pubkey_data_len);
    }
    if (dec_offset + pubkey_data_len > decrypted_blob_len) {
      SAFE_FREE(decrypted_blob);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Decrypted key truncated at pubkey data: %s", key_path);
    }
    uint8_t ed25519_pk[32];
    memcpy(ed25519_pk, decrypted_blob + dec_offset, 32);
    dec_offset += 32;
 
    // Read private key length
    if (dec_offset + 4 > decrypted_blob_len) {
      SAFE_FREE(decrypted_blob);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Decrypted key truncated at privkey length: %s", key_path);
    }
    uint32_t privkey_data_len = read_u32_be(&decrypted_blob[dec_offset]);
    dec_offset += 4;
 
    // Read private key (64 bytes for Ed25519: 32-byte seed + 32-byte public key)
    if (privkey_data_len != 64) {
      SAFE_FREE(decrypted_blob);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid Ed25519 private key length: %u (expected 64)", privkey_data_len);
    }
    if (dec_offset + privkey_data_len > decrypted_blob_len) {
      SAFE_FREE(decrypted_blob);
      SAFE_FREE(key_blob);
      SAFE_FREE(file_content);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Decrypted key truncated at privkey data: %s", key_path);
    }
    uint8_t ed25519_sk[64];
    memcpy(ed25519_sk, decrypted_blob + dec_offset, 64);
    dec_offset += 64;
 
    // Populate key_out (ed25519_sk contains: 32-byte seed + 32-byte public key)
    key_out->type = KEY_TYPE_ED25519;
    memcpy(key_out->key.ed25519, ed25519_sk, 32);           // Seed (first 32 bytes)
    memcpy(key_out->key.ed25519 + 32, ed25519_sk + 32, 32); // Public key (next 32 bytes)
 
    // Clean up decrypted data (sensitive!)
    sodium_memzero(decrypted_blob, decrypted_blob_len);
    SAFE_FREE(decrypted_blob);
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
 
    log_debug("Successfully parsed decrypted Ed25519 key");
 
    // Attempt to add the decrypted key to ssh-agent for future password-free use
    log_info("Attempting to add decrypted key to ssh-agent");
    asciichat_error_t agent_result = ssh_agent_add_key(key_out, key_path);
    if (agent_result == ASCIICHAT_OK) {
      log_info("Successfully added key to ssh-agent - password will not be required on next run");
    } else {
      // Non-fatal: key is already decrypted and loaded, just won't be cached in agent
      log_warn("Failed to add key to ssh-agent (non-fatal): %s", asciichat_error_string(agent_result));
      log_warn("You can manually add it with: ssh-add %s", key_path);
    }
 
    return ASCIICHAT_OK;
  }
 
  // Read number of keys
  if (offset + 4 > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at num keys: %s", key_path);
  }
 
  uint32_t num_keys = read_u32_be(&key_blob[offset]);
  offset += 4;
 
  log_debug("num_keys=%u, offset=%zu, key_blob_len=%zu", num_keys, offset, key_blob_len);
  log_debug("Raw bytes at offset %zu: %02x %02x %02x %02x", offset, key_blob[offset], key_blob[offset + 1],
            key_blob[offset + 2], key_blob[offset + 3]);
  log_debug("After num_keys, offset=%zu", offset);
 
  if (num_keys != 1) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key contains %u keys (expected 1): %s", num_keys, key_path);
  }
 
  // Read public key
  if (offset + 4 > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at pubkey length: %s", key_path);
  }
 
  log_debug("About to read pubkey_len at offset=%zu, bytes: %02x %02x %02x %02x", offset, key_blob[offset],
            key_blob[offset + 1], key_blob[offset + 2], key_blob[offset + 3]);
 
  uint32_t pubkey_len = read_u32_be(&key_blob[offset]);
  offset += 4;
 
  log_debug("pubkey_len=%u, offset=%zu", pubkey_len, offset);
 
  if (offset + pubkey_len > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at pubkey data: %s", key_path);
  }
 
  // Parse the public key to extract the Ed25519 public key for validation
  if (pubkey_len < 4) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH public key too small: %s", key_path);
  }
 
  uint32_t key_type_len = read_u32_be(&key_blob[offset]);
  offset += 4;
 
  // Check if it's an Ed25519 key
  if (key_type_len != 11 || memcmp(key_blob + offset, "ssh-ed25519", 11) != 0) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key is not Ed25519: %s", key_path);
  }
 
  offset += key_type_len; // Skip the key type string
  log_debug("After skipping key type, offset=%zu", offset);
 
  // Read the public key length
  if (offset + 4 > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at public key length: %s", key_path);
  }
 
  uint32_t pubkey_data_len = read_u32_be(&key_blob[offset]);
  offset += 4;
  log_debug("Public key data length: %u, offset=%zu", pubkey_data_len, offset);
 
  log_debug("Public key data length: %u (expected 32 for Ed25519)", pubkey_data_len);
 
  // For Ed25519, the public key should be 32 bytes, but let's be more flexible
  if (pubkey_data_len < 32) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH public key data too small (%u bytes, expected at least 32): %s",
                     pubkey_data_len, key_path);
  }
 
  // Read Ed25519 public key (first 32 bytes) for validation
  if (offset + 32 > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at public key: %s", key_path);
  }
 
  uint8_t ed25519_pubkey[32];
  memcpy(ed25519_pubkey, key_blob + offset, 32);
  offset += pubkey_data_len; // Skip the entire public key data
 
  // Skip the rest of the public key data to get to the private key
  // We've already parsed: 4 (key_type_len) + 11 (ssh-ed25519) + 4 (pubkey_data_len) + 32 (key) = 51 bytes
  // So we need to skip the remaining pubkey_len - 51 bytes
  // Check for underflow before subtraction
  if (pubkey_len >= 51) {
    size_t remaining_pubkey = pubkey_len - 51;
    if (remaining_pubkey > 0) {
      offset += remaining_pubkey;
    }
  }
 
  // Read private key
  if (offset + 4 > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at privkey length: %s", key_path);
  }
 
  uint32_t privkey_len = read_u32_be(&key_blob[offset]);
  offset += 4;
 
  if (offset + privkey_len > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at privkey data: %s", key_path);
  }
 
  // Parse the private key structure
  // Format: [4 bytes: checkint1] [4 bytes: checkint2] [4 bytes: key type length] [key type]
  //         [4 bytes: public key length] [public key] [4 bytes: private key length] [private key]
  //         [4 bytes: comment length] [comment]
 
  if (privkey_len < 8) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key data too small: %s", key_path);
  }
 
  // Verify checkints (should be equal)
  uint32_t checkint1 = read_u32_be(&key_blob[offset]);
  uint32_t checkint2 = read_u32_be(&key_blob[offset + 4]);
  offset += 8;
 
  if (checkint1 != checkint2) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key checkints don't match: %s", key_path);
  }
 
  // Skip key type
  if (offset + 4 > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at key type length: %s", key_path);
  }
 
  uint32_t key_type_len_priv = read_u32_be(&key_blob[offset]);
  // Check for integer overflow before adding to offset
  if (key_type_len_priv > key_blob_len || offset + 4 + key_type_len_priv > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key type length overflow: %u", key_type_len_priv);
  }
  offset += 4 + key_type_len_priv;
 
  // Skip public key
  if (offset + 4 > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at pubkey length: %s", key_path);
  }
 
  uint32_t pubkey_len_priv = read_u32_be(&key_blob[offset]);
  // Check for integer overflow before adding to offset
  if (pubkey_len_priv > key_blob_len || offset + 4 + pubkey_len_priv > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key public key length overflow: %u", pubkey_len_priv);
  }
  offset += 4 + pubkey_len_priv;
 
  // Read private key
  if (offset + 4 > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at privkey length: %s", key_path);
  }
 
  uint32_t privkey_data_len = read_u32_be(&key_blob[offset]);
  offset += 4;
 
  if (offset + privkey_data_len > key_blob_len) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key truncated at privkey data: %s", key_path);
  }
 
  // The private key data should be at least 64 bytes (32 bytes private key + 32 bytes public key)
  // But OpenSSH format may have additional data
  if (privkey_data_len < 64) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key data length is %u (expected at least 64): %s",
                     privkey_data_len, key_path);
  }
 
  // Extract the Ed25519 private key (first 32 bytes)
  uint8_t ed25519_privkey[32];
  memcpy(ed25519_privkey, key_blob + offset, 32);
 
  // Verify the public key matches
  // The public key in the privkey section is raw Ed25519, while the one in pubkey section is SSH format
  // We need to compare the raw public key from privkey with the raw public key extracted from pubkey
  // Use constant-time comparison for cryptographic material
  if (sodium_memcmp(key_blob + offset + 32, ed25519_pubkey, 32) != 0) {
    SAFE_FREE(key_blob);
    SAFE_FREE(file_content);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "OpenSSH private key public key mismatch: %s", key_path);
  }
 
  // Initialize the private key structure
  memset(key_out, 0, sizeof(private_key_t));
  key_out->type = KEY_TYPE_ED25519;
 
  // Store the actual private key (seed + public key = 64 bytes)
  // Ed25519 private key format: [32 bytes seed][32 bytes public key]
  memcpy(key_out->key.ed25519, ed25519_privkey, 32);     // Store the seed (first 32 bytes)
  memcpy(key_out->key.ed25519 + 32, ed25519_pubkey, 32); // Store the public key (next 32 bytes)
 
  // Also store the public key in the public_key field for easy access
  memcpy(key_out->public_key, ed25519_pubkey, 32);
 
  // Set a comment
  SAFE_STRNCPY(key_out->key_comment, "ssh-ed25519", sizeof(key_out->key_comment) - 1);
 
  SAFE_FREE(key_blob);
  SAFE_FREE(file_content);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, BUFFER_SIZE_LARGE, BUFFER_SIZE_SMALL, BUFFER_SIZE_XXLARGE, private_key_t::ed25519, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, ERROR_MEMORY, public_key_t::key, private_key_t::key, private_key_t::key_comment, KEY_TYPE_ED25519, log_debug, log_info, log_warn, parse_ssh_ed25519_line(), platform_fopen(), platform_getenv(), platform_strdup(), prompt_password_simple(), private_key_t::public_key, SAFE_FREE, SAFE_MALLOC, SAFE_REALLOC, safe_snprintf(), SAFE_STRNCPY, SET_ERRNO, ssh_agent_add_key(), ssh_agent_has_key(), public_key_t::type, private_key_t::type, private_key_t::use_ssh_agent, and validate_ssh_key_file().

Referenced by parse_private_key().

private_key_to_x25519()

asciichat_error_t private_key_to_x25519	(	const private_key_t *	key,
		uint8_t	x25519_sk[32]
	)

#include <keys.h>

Convert private key to X25519 for Diffie-Hellman key exchange.

Parameters

key	Private key to convert (must not be NULL)
x25519_sk	Output buffer for X25519 private key (32 bytes)

Returns

ASCIICHAT_OK on success, error code on failure

Converts private key to X25519 format for key exchange:

• Ed25519 → X25519: Uses libsodium conversion function (crypto_sign_ed25519_sk_to_curve25519)
• X25519: Passthrough (key is already in X25519 format)

Note

Conversion: Ed25519 keys are converted using libsodium's conversion function. Conversion is mathematically safe (same curve, different representation).

Ed25519 keys: Extracts 32-byte seed from Ed25519 key (first 32 bytes of ed25519 union). Converts seed to X25519 scalar using libsodium.

X25519 passthrough: If key is already X25519, key is copied directly.

Warning

All keys must be 32 bytes. Function validates key size before conversion.

Definition at line 292 of file keys.c.

                                                                                         {
  if (!key || !x25519_sk) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for private_key_to_x25519");
  }
 
  if (key->type == KEY_TYPE_X25519) {
    // Passthrough for X25519 keys
    memcpy(x25519_sk, key->key.x25519, 32);
    return ASCIICHAT_OK;
  }
 
  if (key->type == KEY_TYPE_ED25519) {
    // Convert Ed25519 to X25519 (Ed25519 private key is 64 bytes: seed + public)
    return ed25519_to_x25519_private(key->key.ed25519, x25519_sk);
  }
 
  return SET_ERRNO(ERROR_CRYPTO_KEY, "Unsupported key type for X25519 conversion: %d", key->type);
}

References ASCIICHAT_OK, private_key_t::ed25519, ed25519_to_x25519_private(), ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, private_key_t::key, KEY_TYPE_ED25519, KEY_TYPE_X25519, SET_ERRNO, private_key_t::type, and private_key_t::x25519.

public_key_to_x25519()

asciichat_error_t public_key_to_x25519	(	const public_key_t *	key,
		uint8_t	x25519_pk[32]
	)

#include <keys.h>

Convert public key to X25519 for Diffie-Hellman key exchange.

Parameters

key	Public key to convert (must not be NULL)
x25519_pk	Output buffer for X25519 public key (32 bytes)

Returns

ASCIICHAT_OK on success, error code on failure

Converts public key to X25519 format for key exchange:

• Ed25519 → X25519: Uses libsodium conversion function (crypto_sign_ed25519_pk_to_curve25519)
• X25519: Passthrough (key is already in X25519 format)
• GPG: Already derived to X25519 during GPG parsing

Note

Conversion: Ed25519 keys are converted using libsodium's conversion function. Conversion is mathematically safe (same curve, different representation).

X25519 passthrough: If key is already X25519, key is copied directly.

GPG keys: GPG keys are already converted to X25519 during parsing. No additional conversion needed.

Warning

All keys must be 32 bytes. Function validates key size before conversion.

Definition at line 273 of file keys.c.

                                                                                       {
  if (!key || !x25519_pk) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for public_key_to_x25519");
  }
 
  if (key->type == KEY_TYPE_X25519) {
    // Passthrough for X25519 keys
    memcpy(x25519_pk, key->key, 32);
    return ASCIICHAT_OK;
  }
 
  if (key->type == KEY_TYPE_ED25519) {
    // Convert Ed25519 to X25519
    return ed25519_to_x25519_public(key->key, x25519_pk);
  }
 
  return SET_ERRNO(ERROR_CRYPTO_KEY, "Unsupported key type for X25519 conversion: %d", key->type);
}

References ASCIICHAT_OK, ed25519_to_x25519_public(), ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, public_key_t::key, KEY_TYPE_ED25519, KEY_TYPE_X25519, SET_ERRNO, and public_key_t::type.

validate_gpg_key_format()

asciichat_error_t validate_gpg_key_format

(

const char *

gpg_key_text

)

#include <gpg_keys.h>

Validate GPG key format and structure.

Validate GPG key format.

Parameters

gpg_key_text

GPG key text to validate (must not be NULL)

Returns

ASCIICHAT_OK if valid, error code on failure

Validates GPG key format before parsing. Checks for correct armored format and basic structure.

Note

Format validation: Checks for correct armored format markers. Validates basic GPG key structure.

Use case: Called before parsing to ensure key format is valid. Returns error early if format is invalid.

Warning

GPG support is currently disabled. Function may not work until GPG support is re-enabled.

Parameters

key_text

GPG key text to validate (must not be NULL)

Returns

ASCIICHAT_OK if valid, error code on failure

Validates GPG key format by checking for correct armored format markers. Expects "-----BEGIN PGP PUBLIC KEY BLOCK-----" and "-----END PGP PUBLIC KEY BLOCK-----".

Note

Format validation: Checks for correct GPG armored format markers. Validates basic GPG key structure.

GPG format: Expects PEM-armored GPG key format. Format: "-----BEGIN PGP PUBLIC KEY BLOCK-----" ... "-----END PGP PUBLIC KEY BLOCK-----"

Warning

GPG support: GPG key validation may not work until GPG support is re-enabled.

Definition at line 176 of file keys_validation.c.

                                                                {
  if (!key_text) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key_text=%p", key_text);
    return ERROR_INVALID_PARAM;
  }
 
  // Check for GPG armor header
  if (strncmp(key_text, "-----BEGIN PGP", 14) != 0) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "GPG key does not start with armor header");
    return ERROR_CRYPTO_KEY;
  }
 
  // Check for GPG armor footer
  if (strstr(key_text, "-----END PGP") == NULL) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "GPG key does not contain armor footer");
    return ERROR_CRYPTO_KEY;
  }
 
  // Additional GPG key validation
  // Validate armor format (should have valid armor headers)
  bool has_version_header = (strstr(key_text, "Version:") != NULL);
  bool has_charset_header = (strstr(key_text, "Charset:") != NULL || strstr(key_text, "Version:") != NULL);
 
  if (!has_version_header && !has_charset_header) {
    // Missing common armor headers - might be incomplete
    log_warn("GPG armor missing version/charset headers - key might be incomplete");
  }
 
  // Validate base64 content (keys must have non-empty body between headers and footer)
  const char *start_pos = strstr(key_text, "\n\n");
  const char *end_pos = strstr(key_text, "\n-----END");
  if (start_pos && end_pos && start_pos < end_pos) {
    // -2 for \n\n at start_pos; check for underflow before casting to size_t
    ptrdiff_t diff = end_pos - start_pos - 2;
    if (diff <= 0) {
      SET_ERRNO(ERROR_CRYPTO_KEY, "GPG key has empty or malformed body content");
      return ERROR_CRYPTO_KEY;
    }
  }
 
  return ASCIICHAT_OK;
}

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

validate_key_permissions()

asciichat_error_t validate_key_permissions

(

const char *

key_path

)

#include <keys_validation.h>

Validate key file permissions.

Parameters

key_path

Path to key file (must not be NULL)

Returns

ASCIICHAT_OK if permissions are secure, error code on failure

Validates key file permissions by checking Unix file permissions. Ensures file has restrictive permissions (0600).

Note

Permission checking: Checks file permissions on Unix systems. Validates that file has owner read/write only (0600).

Platform-specific: Permission checking is Unix-specific. Windows does not have Unix-style permissions.

Recommended permissions: Private key files should have 0600 permissions. Public key files can have more permissive permissions (0644).

Warning

Platform-specific: Permission checking is Unix-specific. Windows does not have Unix-style permissions.

Definition at line 297 of file keys_validation.c.

                                                                 {
  if (!key_path) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key_path=%p", key_path);
    return ERROR_INVALID_PARAM;
  }
 
#ifndef _WIN32
  struct stat st;
  if (stat(key_path, &st) != 0) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "Cannot stat key file: %s", key_path);
    return ERROR_CRYPTO_KEY;
  }
 
  // Check for overly permissive permissions
  if ((st.st_mode & SSH_KEY_PERMISSIONS_MASK) != 0) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "Key file has overly permissive permissions: %o (recommended: 600)", st.st_mode & 0777);
    return ERROR_CRYPTO_KEY;
  }
#endif
 
  return ASCIICHAT_OK;
}

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

Referenced by validate_key_security().

validate_key_security()

asciichat_error_t validate_key_security

(

const char *

key_path

)

#include <keys_validation.h>

Validate key permissions and security.

Parameters

key_path

Path to key file (must not be NULL)

Returns

ASCIICHAT_OK if secure, error code on failure

Validates key file permissions and performs security checks. Combines permission validation with additional security checks.

Note

Permission checking: Validates file permissions using validate_key_permissions(). Checks that file has restrictive permissions (0600).

Security checks: Additional security checks would include:

• Weak key pattern detection
• Key strength validation
• Known weak key detection These are not yet fully implemented (TODOs in implementation).

Warning

Security checks incomplete: Additional security checks (weak keys, etc.) are not yet fully implemented. Function currently only checks permissions.

Definition at line 123 of file keys_validation.c.

                                                              {
  if (!key_path) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key_path=%p", key_path);
    return ERROR_INVALID_PARAM;
  }
 
  // Check file permissions
  asciichat_error_t perm_result = validate_key_permissions(key_path);
  if (perm_result != ASCIICHAT_OK) {
    return perm_result;
  }
 
  // Additional security checks have been implemented in check_key_strength()
  // and check_key_patterns() functions. File permissions check is the critical one.
  // Known weak keys database would require periodic updates and is beyond scope.
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, SET_ERRNO, and validate_key_permissions().

validate_private_key()

asciichat_error_t validate_private_key

(

const private_key_t *

key

)

#include <keys_validation.h>

Validate a private key structure.

Parameters

key	Private key to validate (must not be NULL)

Returns

ASCIICHAT_OK if valid, error code on failure

Validates private key structure by checking:

• Key type is valid (Ed25519 or X25519)
• Key data is not all zeros
• Comment length is within limits

Note

Key type validation: Checks that key type is one of: KEY_TYPE_ED25519 or KEY_TYPE_X25519 GPG keys are NOT supported for private keys (only public).

Key size: Ed25519 private keys are 64 bytes (seed + public). X25519 private keys are 32 bytes. Function validates key size based on key type.

Zero key check: Rejects keys with all-zero key data. Zero keys are invalid and should not be used.

Comment validation: Checks that comment length is less than MAX_COMMENT_LEN.

Warning

Zero keys: Keys with all-zero data are rejected as invalid.

Definition at line 67 of file keys_validation.c.

                                                                 {
  if (!key) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key=%p", key);
    return ERROR_INVALID_PARAM;
  }
 
  // Check key type
  if (key->type == KEY_TYPE_UNKNOWN) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "Private key type is unknown");
    return ERROR_CRYPTO_KEY;
  }
 
  if (key->type != KEY_TYPE_ED25519 && key->type != KEY_TYPE_X25519) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "Unsupported private key type: %d", key->type);
    return ERROR_CRYPTO_KEY;
  }
 
  // Check key data is not all zeros
  bool is_zero = true;
  size_t key_size = (key->type == KEY_TYPE_ED25519) ? 64 : 32;
 
  for (size_t i = 0; i < key_size; i++) {
    if (key->key.ed25519[i] != 0) {
      is_zero = false;
      break;
    }
  }
 
  if (is_zero) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "Private key data is all zeros");
    return ERROR_CRYPTO_KEY;
  }
 
  // Check comment length
  if (strlen(key->key_comment) >= MAX_COMMENT_LEN) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "Private key comment too long: %zu (maximum %d)", strlen(key->key_comment),
              MAX_COMMENT_LEN - 1);
    return ERROR_CRYPTO_KEY;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, private_key_t::ed25519, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, private_key_t::key, private_key_t::key_comment, KEY_TYPE_ED25519, KEY_TYPE_UNKNOWN, KEY_TYPE_X25519, MAX_COMMENT_LEN, SET_ERRNO, and private_key_t::type.

validate_public_key()

asciichat_error_t validate_public_key

(

const public_key_t *

key

)

#include <keys_validation.h>

Validate a public key structure.

Parameters

key	Public key to validate (must not be NULL)

Returns

ASCIICHAT_OK if valid, error code on failure

Validates public key structure by checking:

• Key type is valid (Ed25519, X25519, or GPG)
• Key data is not all zeros
• Comment length is within limits

Note

Key type validation: Checks that key type is one of: KEY_TYPE_ED25519, KEY_TYPE_X25519, or KEY_TYPE_GPG

Zero key check: Rejects keys with all-zero key data. Zero keys are invalid and should not be used.

Comment validation: Checks that comment length is less than MAX_COMMENT_LEN. Comments can be up to 255 characters (including null terminator).

Warning

Zero keys: Keys with all-zero data are rejected as invalid.

Definition at line 27 of file keys_validation.c.

                                                               {
  if (!key) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key=%p", key);
    return ERROR_INVALID_PARAM;
  }
 
  // Check key type
  if (key->type == KEY_TYPE_UNKNOWN) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "Key type is unknown");
    return ERROR_CRYPTO_KEY;
  }
 
  if (key->type != KEY_TYPE_ED25519 && key->type != KEY_TYPE_X25519 && key->type != KEY_TYPE_GPG) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "Unsupported key type: %d", key->type);
    return ERROR_CRYPTO_KEY;
  }
 
  // Check key data is not all zeros
  bool is_zero = true;
  for (int i = 0; i < 32; i++) {
    if (key->key[i] != 0) {
      is_zero = false;
      break;
    }
  }
 
  if (is_zero) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "Key data is all zeros");
    return ERROR_CRYPTO_KEY;
  }
 
  // Check comment length
  if (strlen(key->comment) >= MAX_COMMENT_LEN) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "Key comment too long: %zu (maximum %d)", strlen(key->comment), MAX_COMMENT_LEN - 1);
    return ERROR_CRYPTO_KEY;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, public_key_t::comment, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, public_key_t::key, KEY_TYPE_ED25519, KEY_TYPE_GPG, KEY_TYPE_UNKNOWN, KEY_TYPE_X25519, MAX_COMMENT_LEN, SET_ERRNO, and public_key_t::type.

validate_ssh_key_file()

asciichat_error_t validate_ssh_key_file

(

const char *

key_path

)

#include <keys.h>

Validate SSH key file before parsing.

Validate SSH key file permissions and format.

Parameters

key_path

Path to SSH key file (must not be NULL)

Returns

ASCIICHAT_OK if valid, error code on failure

Validates SSH key file before parsing. Checks:

• File exists and is readable
• File has valid SSH private key header ("-----BEGIN OPENSSH PRIVATE KEY-----")
• File permissions are appropriate (warns if overly permissive)

Note

Permission checking: Checks file permissions on Unix systems. Warns if file has world-readable permissions but does not fail validation.

File header: Validates that file starts with correct SSH private key header. Returns error if header is missing or invalid.

Platform-specific: Permission checking is Unix-specific. Windows does not have Unix-style permissions.

Warning

File permissions: Private key files should have restrictive permissions (0600). Function warns but does not fail on overly permissive permissions.

Definition at line 977 of file ssh_keys.c.

                                                              {
  if (!key_path) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key_path=%p", key_path);
  }
 
  if (!path_looks_like_path(key_path)) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Invalid SSH key path: %s", key_path);
  }
 
  char *normalized_path = NULL;
  asciichat_error_t path_result = path_validate_user_path(key_path, PATH_ROLE_KEY_PRIVATE, &normalized_path);
  if (path_result != ASCIICHAT_OK) {
    SAFE_FREE(normalized_path);
    return path_result;
  }
 
  // Check if file exists and is readable
  FILE *test_file = platform_fopen(normalized_path, "r");
  if (test_file == NULL) {
    SAFE_FREE(normalized_path);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Cannot read key file: %s", key_path);
  }
 
  // Check if this is an SSH key file by looking for the header
  char header[BUFFER_SIZE_SMALL];
  bool is_ssh_key_file = false;
  if (fgets(header, sizeof(header), test_file) != NULL) {
    if (strstr(header, "BEGIN OPENSSH PRIVATE KEY") != NULL || strstr(header, "BEGIN RSA PRIVATE KEY") != NULL ||
        strstr(header, "BEGIN EC PRIVATE KEY") != NULL) {
      is_ssh_key_file = true;
    }
  }
  (void)fclose(test_file);
 
  if (!is_ssh_key_file) {
    SAFE_FREE(normalized_path);
    return SET_ERRNO(ERROR_CRYPTO_KEY, "File is not a valid SSH key: %s", key_path);
  }
 
  // Check permissions for SSH key files (should be 600 or 400)
#ifndef _WIN32
  struct stat st;
  if (stat(normalized_path, &st) == 0) {
    if ((st.st_mode & SSH_KEY_PERMISSIONS_MASK) != 0) {
      log_error("SSH key file %s has overly permissive permissions: %o", key_path, st.st_mode & 0777);
      log_error("Run 'chmod 600 %s' to fix this", key_path);
      SAFE_FREE(normalized_path);
      return SET_ERRNO(ERROR_CRYPTO_KEY, "SSH key file has overly permissive permissions: %s", key_path);
    }
  }
#endif
 
  SAFE_FREE(normalized_path);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, BUFFER_SIZE_SMALL, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, log_error, path_looks_like_path(), PATH_ROLE_KEY_PRIVATE, path_validate_user_path(), platform_fopen(), SAFE_FREE, SET_ERRNO, and SSH_KEY_PERMISSIONS_MASK.

Referenced by client_crypto_init(), and parse_ssh_private_key().

validate_ssh_key_format()

asciichat_error_t validate_ssh_key_format

(

const char *

key_text

)

#include <keys_validation.h>

Validate SSH key format.

Parameters

key_text

SSH key text to validate (must not be NULL)

Returns

ASCIICHAT_OK if valid, error code on failure

Validates SSH key format by checking for correct format markers. Expects "ssh-ed25519 " prefix followed by base64-encoded key.

Note

Format validation: Checks that key text starts with "ssh-ed25519 ". Validates basic SSH key format structure.

Key type: Only Ed25519 SSH keys are validated. Other key types (RSA, ECDSA) will fail validation.

Warning

Key format: Must start with "ssh-ed25519 ". Other SSH key types (RSA, ECDSA) are NOT supported.

Definition at line 146 of file keys_validation.c.

                                                                {
  if (!key_text) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key_text=%p", key_text);
    return ERROR_INVALID_PARAM;
  }
 
  // Check for SSH key format
  if (strncmp(key_text, "ssh-ed25519 ", 12) != 0) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "SSH key does not start with 'ssh-ed25519 '");
    return ERROR_CRYPTO_KEY;
  }
 
  // Check for base64 data
  const char *base64_start = key_text + 12;
  while (*base64_start == ' ' || *base64_start == '\t') {
    base64_start++;
  }
 
  if (*base64_start == '\0' || *base64_start == '\n' || *base64_start == '\r') {
    SET_ERRNO(ERROR_CRYPTO_KEY, "SSH key has no base64 data");
    return ERROR_CRYPTO_KEY;
  }
 
  // Additional comprehensive SSH key validation (base64, blob structure, etc.)
  // would require full OpenSSH format parsing. Basic format check above is sufficient
  // to catch malformed keys. Full validation happens during key loading.
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, and SET_ERRNO.

validate_x25519_key_format()

asciichat_error_t validate_x25519_key_format

(

const char *

key_hex

)

#include <keys_validation.h>

Validate X25519 key format.

Parameters

key_hex

X25519 key in hex format (must not be NULL)

Returns

ASCIICHAT_OK if valid, error code on failure

Validates X25519 key format by checking hex string format. Expects 64 hex characters (32 bytes).

Note

Format validation: Checks that key is 64 hex characters (32 bytes). Validates hex character format (0-9, a-f, A-F).

Key size: X25519 keys must be exactly 64 hex characters (32 bytes). Returns error if length doesn't match or contains invalid characters.

Warning

Key format: Must be exactly 64 hex characters. Invalid characters or wrong length will fail validation.

Definition at line 219 of file keys_validation.c.

                                                                  {
  if (!key_hex) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: key_hex=%p", key_hex);
    return ERROR_INVALID_PARAM;
  }
 
  // Check hex string length (32 bytes = 64 hex characters)
  size_t hex_len = strlen(key_hex);
  if (hex_len != 64) {
    SET_ERRNO(ERROR_CRYPTO_KEY, "X25519 key has invalid length: %zu (expected 64)", hex_len);
    return ERROR_CRYPTO_KEY;
  }
 
  // Check that all characters are valid hex
  for (size_t i = 0; i < hex_len; i++) {
    if (!isxdigit(key_hex[i])) {
      SET_ERRNO(ERROR_CRYPTO_KEY, "X25519 key contains invalid hex character at position %zu: '%c'", i, key_hex[i]);
      return ERROR_CRYPTO_KEY;
    }
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, and SET_ERRNO.

Variable Documentation

comment

char public_key_t::comment[256]

Key comment/label (e.g., "user@hostname")

Definition at line 72 of file key_types.h.

Referenced by client_crypto_init(), crypto_handshake_server_auth_challenge(), crypto_handshake_server_complete(), format_public_key(), parse_gpg_key(), parse_public_key(), and validate_public_key().

ed25519 [1/2]

uint8_t private_key_t::ed25519[64]

Ed25519 seed (32) + public key (32) = 64 bytes

Definition at line 94 of file key_types.h.

Referenced by crypto_sign_ephemeral_key(), ed25519_sign_message(), parse_private_key(), parse_ssh_private_key(), private_key_to_x25519(), ssh_agent_add_key(), and validate_private_key().

[] [2/2]

uint8_t { ... } ::ed25519[64]

Ed25519 seed (32) + public key (32) = 64 bytes

Definition at line 94 of file key_types.h.

gpg_keygrip

char private_key_t::gpg_keygrip[64]

GPG keygrip (40 hex chars + null) for gpg-agent signing

Definition at line 101 of file key_types.h.

Referenced by ed25519_sign_message(), and parse_private_key().

key [1/2]

uint8_t public_key_t::key[32]

Public key data (always 32 bytes)

Definition at line 71 of file key_types.h.

Referenced by check_key_patterns(), check_key_strength(), check_known_host(), client_crypto_init(), compare_public_keys(), crypto_handshake_server_auth_challenge(), crypto_handshake_server_complete(), ed25519_sign_message(), format_public_key(), generate_key_fingerprint(), parse_gpg_key(), parse_public_key(), parse_ssh_private_key(), public_key_to_x25519(), server_crypto_handshake(), ssh_agent_has_key(), ssh_agent_sign(), and validate_public_key().

[union] [2/2]

union { ... } private_key_t::key

Private key data (union based on key type)

Referenced by crypto_sign_ephemeral_key(), ed25519_sign_message(), parse_private_key(), parse_ssh_private_key(), private_key_to_x25519(), ssh_agent_add_key(), and validate_private_key().

key_comment

char private_key_t::key_comment[256]

SSH key comment (for agent identification)

Definition at line 100 of file key_types.h.

Referenced by client_crypto_init(), ed25519_sign_message(), parse_private_key(), parse_ssh_private_key(), and validate_private_key().

public_key

uint8_t private_key_t::public_key[32]

Ed25519 public key (for agent mode or verification)

Definition at line 99 of file key_types.h.

Referenced by client_crypto_init(), crypto_handshake_client_key_exchange(), crypto_handshake_server_start(), ed25519_sign_message(), parse_private_key(), parse_ssh_private_key(), server_crypto_handshake(), and server_main().

type [1/2]

key_type_t public_key_t::type

Key type (Ed25519, X25519, or GPG)

Definition at line 70 of file key_types.h.

Referenced by client_crypto_handshake(), client_crypto_init(), compare_public_keys(), crypto_handshake_server_auth_challenge(), crypto_handshake_server_complete(), ed25519_sign_message(), format_public_key(), parse_gpg_key(), parse_public_key(), parse_ssh_private_key(), public_key_to_x25519(), server_crypto_handshake(), ssh_agent_sign(), and validate_public_key().

type [2/2]

key_type_t private_key_t::type

Key type (Ed25519, X25519, or GPG)

Definition at line 92 of file key_types.h.

Referenced by client_crypto_init(), crypto_handshake_client_auth_response(), crypto_handshake_client_key_exchange(), crypto_handshake_server_start(), crypto_sign_ephemeral_key(), ed25519_sign_message(), parse_private_key(), parse_ssh_private_key(), private_key_to_x25519(), server_crypto_handshake(), ssh_agent_add_key(), and validate_private_key().

use_gpg_agent

bool private_key_t::use_gpg_agent

If true, use GPG agent for signing (currently disabled)

Definition at line 98 of file key_types.h.

Referenced by ed25519_sign_message(), and parse_private_key().

use_ssh_agent

bool private_key_t::use_ssh_agent

If true, use SSH agent for signing (key stays in agent)

Definition at line 97 of file key_types.h.

Referenced by ed25519_sign_message(), parse_private_key(), and parse_ssh_private_key().

x25519 [1/2]

uint8_t private_key_t::x25519[32]

X25519 private key (32 bytes)

Definition at line 95 of file key_types.h.

Referenced by private_key_to_x25519().

[] [2/2]

uint8_t { ... } ::x25519[32]

X25519 private key (32 bytes)

Definition at line 95 of file key_types.h.