discovery_keys.h File Reference

Discovery Server Public Key Trust Management. More...

Go to the source code of this file.

Macros
#define	ACDS_OFFICIAL_SERVER   ACDS_OFFICIAL_SERVER_HOSTNAME
	Official ACDS server hostname (automatic HTTPS key trust)
#define	ACDS_OFFICIAL_KEY_SSH_URL   "https://discovery.ascii-chat.com/key.pub"
	Default HTTPS URLs for official ACDS keys.
#define	ACDS_OFFICIAL_KEY_GPG_URL   "https://discovery.ascii-chat.com/key.gpg"
#define	ACDS_KEYS_CACHE_DIR   "acds_keys"
	Key cache directory (relative to config dir)

Functions
asciichat_error_t	discovery_keys_verify (const char *acds_server, const char *key_spec, uint8_t pubkey_out[32])
	Verify and load ACDS server public key.
asciichat_error_t	discovery_keys_download_https (const char *url, uint8_t pubkey_out[32])
	Download key from HTTPS URL.
asciichat_error_t	discovery_keys_load_file (const char *file_path, uint8_t pubkey_out[32])
	Load key from local file.
asciichat_error_t	discovery_keys_get_cache_path (const char *acds_server, char *path_out, size_t path_size)
	Get cached key path for ACDS server.
asciichat_error_t	discovery_keys_load_cached (const char *acds_server, uint8_t pubkey_out[32])
	Check if cached key exists and load it.
asciichat_error_t	discovery_keys_save_cached (const char *acds_server, const uint8_t pubkey[32])
	Save key to cache.
asciichat_error_t	discovery_keys_verify_change (const char *acds_server, const uint8_t old_pubkey[32], const uint8_t new_pubkey[32])
	Verify key change with user.
asciichat_error_t	discovery_keys_clear_cache (const char *acds_server)
	Clear cached key for ACDS server.

Detailed Description

Discovery Server Public Key Trust Management.

This module handles verification and trust management for ACDS server public keys. It provides functionality to:

• Download keys from HTTPS URLs using lib/crypto/http_client.h
• Load keys from local files (SSH/GPG formats)
• Special-case automatic trust for discovery-service.ascii-chat.com
• Cache keys locally and detect changes (requires user verification)
• Parse github:user and gitlab:user.gpg key specifications

Trust Model

Official ACDS Server (discovery-service.ascii-chat.com):

• Automatically trusts keys downloaded from https://discovery-service.ascii-chat.com/key.pub or /key.gpg
• First connection: downloads and caches key
• Subsequent connections: uses cached key
• Key changes: requires user verification (prevents MITM attacks)

Third-Party ACDS Servers:

• Requires explicit –discovery-service-key configuration
• Can be HTTPS URL, local file path, or github:user/gitlab:user specification
• Keys are cached after first successful download/verification
• Key changes require user verification

Usage

// Download and verify key from HTTPS URL
uint8_t pubkey[32];
asciichat_error_t result = discovery_keys_verify("acds.example.com",
                                            "https://acds.example.com/key.pub",
                                            pubkey);
 
// Automatic trust for official server
result = discovery_keys_verify("discovery-service.ascii-chat.com", NULL, pubkey);
 
// Load from local file
result = discovery_keys_verify("acds.example.com", "/path/to/key.pub", pubkey);
 
// GitHub key
result = discovery_keys_verify("acds.example.com", "github:zfogg", pubkey);

Author

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

Date

January 2026

Definition in file discovery_keys.h.

Macro Definition Documentation

ACDS_KEYS_CACHE_DIR

#define ACDS_KEYS_CACHE_DIR   "acds_keys"

Key cache directory (relative to config dir)

Definition at line 79 of file discovery_keys.h.

ACDS_OFFICIAL_KEY_GPG_URL

#define ACDS_OFFICIAL_KEY_GPG_URL   "https://discovery.ascii-chat.com/key.gpg"

Definition at line 74 of file discovery_keys.h.

ACDS_OFFICIAL_KEY_SSH_URL

#define ACDS_OFFICIAL_KEY_SSH_URL   "https://discovery.ascii-chat.com/key.pub"

Default HTTPS URLs for official ACDS keys.

Definition at line 73 of file discovery_keys.h.

ACDS_OFFICIAL_SERVER

#define ACDS_OFFICIAL_SERVER   ACDS_OFFICIAL_SERVER_HOSTNAME

Official ACDS server hostname (automatic HTTPS key trust)

References the authoritative definition from network/acip/acds.h

Definition at line 68 of file discovery_keys.h.

Function Documentation

discovery_keys_clear_cache()

asciichat_error_t discovery_keys_clear_cache

(

const char *

acds_server

)

Clear cached key for ACDS server.

Removes the cached key for the given ACDS server. Useful for testing or forcing key re-download.

Parameters

acds_server

ACDS server hostname

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 208 of file discovery_keys.c.

                                                                      {
  if (!acds_server) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL parameter in discovery_keys_clear_cache");
  }
 
  char cache_path[PLATFORM_MAX_PATH_LENGTH];
  asciichat_error_t result = discovery_keys_get_cache_path(acds_server, cache_path, sizeof(cache_path));
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  if (platform_is_regular_file(cache_path)) {
    if (remove(cache_path) != 0) {
      return SET_ERRNO_SYS(ERROR_FILE_OPERATION, "Failed to delete cached key: %s", cache_path);
    }
    log_debug("Cleared cached ACDS key for server: %s", acds_server);
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, discovery_keys_get_cache_path(), ERROR_FILE_OPERATION, ERROR_INVALID_PARAM, log_debug, platform_is_regular_file(), PLATFORM_MAX_PATH_LENGTH, SET_ERRNO, and SET_ERRNO_SYS.

discovery_keys_download_https()

asciichat_error_t discovery_keys_download_https	(	const char *	url,
		uint8_t	pubkey_out[32]
	)

Download key from HTTPS URL.

Downloads a public key from an HTTPS URL using lib/crypto/http_client.h. Supports both SSH (OpenSSH format) and GPG (ASCII-armored or binary) keys.

Parameters

url	HTTPS URL to download from
pubkey_out	Ed25519 public key output (32 bytes)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 80 of file discovery_keys.c.

                                                                                         {
  if (!url || !pubkey_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL parameter in discovery_keys_download_https");
  }
 
  log_debug("Downloading ACDS key from %s", url);
 
  // Use existing parse_public_key infrastructure which handles HTTPS URLs
  public_key_t key;
  asciichat_error_t result = parse_public_key(url, &key);
  if (result != ASCIICHAT_OK) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to download and parse ACDS key from %s", url);
  }
 
  memcpy(pubkey_out, key.key, 32);
  log_debug("Successfully downloaded and parsed ACDS key from %s", url);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, public_key_t::key, log_debug, parse_public_key(), and SET_ERRNO.

discovery_keys_get_cache_path()

asciichat_error_t discovery_keys_get_cache_path	(	const char *	acds_server,
		char *	path_out,
		size_t	path_size
	)

Get cached key path for ACDS server.

Returns the local cache path for a given ACDS server's key. Path: ~/.config/ascii-chat/acds_keys/<hostname>/key.pub

Parameters

acds_server	ACDS server hostname
path_out	Output buffer for cache path
path_size	Size of output buffer

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 122 of file discovery_keys.c.

                                                                                                           {
  if (!acds_server || !path_out || path_size == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL parameter in discovery_keys_get_cache_path");
  }
 
  char *config_dir = get_config_dir();
  if (!config_dir) {
    return SET_ERRNO(ERROR_CONFIG, "Failed to get config directory");
  }
 
  // Path: ~/.config/ascii-chat/acds_keys/<hostname>/key.pub
  safe_snprintf(path_out, path_size, "%s" ACDS_KEYS_CACHE_DIR PATH_SEPARATOR_STR "%s" PATH_SEPARATOR_STR "key.pub",
                config_dir, acds_server);
  SAFE_FREE(config_dir);
 
  return ASCIICHAT_OK;
}

References ACDS_KEYS_CACHE_DIR, ASCIICHAT_OK, ERROR_CONFIG, ERROR_INVALID_PARAM, get_config_dir(), PATH_SEPARATOR_STR, SAFE_FREE, safe_snprintf(), and SET_ERRNO.

Referenced by discovery_keys_clear_cache(), discovery_keys_load_cached(), and discovery_keys_save_cached().

discovery_keys_load_cached()

asciichat_error_t discovery_keys_load_cached	(	const char *	acds_server,
		uint8_t	pubkey_out[32]
	)

Check if cached key exists and load it.

Attempts to load a cached key for the given ACDS server.

Parameters

acds_server	ACDS server hostname
pubkey_out	Ed25519 public key output (32 bytes)

Returns

ASCIICHAT_OK if cached key exists and loaded successfully, error otherwise

Definition at line 140 of file discovery_keys.c.

                                                                                              {
  if (!acds_server || !pubkey_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL parameter in discovery_keys_load_cached");
  }
 
  char cache_path[PLATFORM_MAX_PATH_LENGTH];
  asciichat_error_t result = discovery_keys_get_cache_path(acds_server, cache_path, sizeof(cache_path));
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  // Check if cached key exists
  if (!platform_is_regular_file(cache_path)) {
    return SET_ERRNO(ERROR_FILE_NOT_FOUND, "No cached key for ACDS server: %s", acds_server);
  }
 
  // Load cached key using existing infrastructure
  return discovery_keys_load_file(cache_path, pubkey_out);
}

References ASCIICHAT_OK, discovery_keys_get_cache_path(), discovery_keys_load_file(), ERROR_FILE_NOT_FOUND, ERROR_INVALID_PARAM, platform_is_regular_file(), PLATFORM_MAX_PATH_LENGTH, and SET_ERRNO.

Referenced by discovery_keys_verify().

discovery_keys_load_file()

asciichat_error_t discovery_keys_load_file	(	const char *	file_path,
		uint8_t	pubkey_out[32]
	)

Load key from local file.

Loads a public key from a local file. Supports:

• OpenSSH format (.pub files)
• GPG ASCII-armored format (.asc, .gpg)
• GPG binary format

Parameters

file_path	Path to key file
pubkey_out	Ed25519 public key output (32 bytes)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 99 of file discovery_keys.c.

                                                                                          {
  if (!file_path || !pubkey_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL parameter in discovery_keys_load_file");
  }
 
  log_debug("Loading ACDS key from file: %s", file_path);
 
  // Use existing parse_public_key infrastructure which handles file paths
  public_key_t key;
  asciichat_error_t result = parse_public_key(file_path, &key);
  if (result != ASCIICHAT_OK) {
    return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to load ACDS key from file: %s", file_path);
  }
 
  memcpy(pubkey_out, key.key, 32);
  log_debug("Successfully loaded ACDS key from file: %s", file_path);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, file_path, public_key_t::key, log_debug, parse_public_key(), and SET_ERRNO.

Referenced by discovery_keys_load_cached().

discovery_keys_save_cached()

asciichat_error_t discovery_keys_save_cached	(	const char *	acds_server,
		const uint8_t	pubkey[32]
	)

Save key to cache.

Caches a public key for the given ACDS server.

Parameters

acds_server	ACDS server hostname
pubkey	Public key to cache (32 bytes)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 160 of file discovery_keys.c.

                                                                                                {
  if (!acds_server || !pubkey) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL parameter in discovery_keys_save_cached");
  }
 
  char cache_path[PLATFORM_MAX_PATH_LENGTH];
  asciichat_error_t result = discovery_keys_get_cache_path(acds_server, cache_path, sizeof(cache_path));
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  // Create cache directory if it doesn't exist
  char dir_path[PLATFORM_MAX_PATH_LENGTH];
  safe_snprintf(dir_path, sizeof(dir_path), "%s", cache_path);
 
  // Find the last path separator (handle both / and \ for cross-platform compatibility)
  char *last_sep = strrchr(dir_path, '\\');
  if (!last_sep) {
    last_sep = strrchr(dir_path, '/');
  }
 
  if (last_sep) {
    *last_sep = '\0';
    if (!platform_is_directory(dir_path)) {
      asciichat_error_t result = platform_mkdir(dir_path, 0700);
      if (result != ASCIICHAT_OK) {
        return SET_ERRNO(ERROR_FILE_OPERATION, "Failed to create ACDS key cache directory: %s", dir_path);
      }
    }
  }
 
  // Save key in OpenSSH public key format
  FILE *f = platform_fopen("file_stream", cache_path, "w");
  if (!f) {
    return SET_ERRNO_SYS(ERROR_FILE_OPERATION, "Failed to create cache file: %s", cache_path);
  }
 
  // Convert binary Ed25519 key to base64 for OpenSSH format
  char base64_key[128];
  sodium_bin2base64(base64_key, sizeof(base64_key), pubkey, 32, sodium_base64_VARIANT_ORIGINAL);
 
  fprintf(f, "ssh-ed25519 %s acds-cached-key\n", base64_key);
  fclose(f);
 
  log_debug("Cached ACDS key for server: %s", acds_server);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, discovery_keys_get_cache_path(), ERROR_FILE_OPERATION, ERROR_INVALID_PARAM, log_debug, platform_fopen(), platform_is_directory(), PLATFORM_MAX_PATH_LENGTH, platform_mkdir(), safe_snprintf(), SET_ERRNO, and SET_ERRNO_SYS.

Referenced by discovery_keys_verify().

discovery_keys_verify()

asciichat_error_t discovery_keys_verify	(	const char *	acds_server,
		const char *	key_spec,
		uint8_t	pubkey_out[32]
	)

Verify and load ACDS server public key.

This function handles all ACDS key verification scenarios:

Automatic Trust (discovery-service.ascii-chat.com only):

• If acds_server == "discovery-service.ascii-chat.com" and key_spec == NULL:
  • Downloads from ACDS_OFFICIAL_KEY_SSH_URL or ACDS_OFFICIAL_KEY_GPG_URL
  • Caches key locally
  • Trusts without user verification (first time)
  • Requires user verification if key changes

Explicit Key Specification:

• HTTPS URL: Downloads key from URL, caches it
• Local file: Loads key from file path
• github:user: Fetches SSH or GPG key from GitHub
• gitlab:user.gpg: Fetches GPG key from GitLab

Caching Behavior:

• Keys are cached in ~/.config/ascii-chat/acds_keys/<hostname>/
• Cache invalidation requires user confirmation (prevents MITM attacks)

Parameters

acds_server	ACDS server hostname (e.g., "acds.example.com")
key_spec	Key specification: NULL: automatic trust for discovery-service.ascii-chat.com only HTTPS URL: https://example.com/key.pub File path: /path/to/key.pub or ~/.ssh/server.pub GitHub: github:username GitLab: gitlab:username.gpg
pubkey_out	Ed25519 public key output (32 bytes)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 275 of file discovery_keys.c.

                                                                                                               {
  if (!acds_server || !pubkey_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL parameter in discovery_keys_verify");
  }
 
  uint8_t new_pubkey[32];
  asciichat_error_t result;
  bool is_official = is_official_server(acds_server);
 
  // ===========================================================================
  // Step 1: Obtain the public key
  // ===========================================================================
 
  if (!key_spec && is_official) {
    // Automatic trust for official server: try SSH key first, then GPG
    log_info("Attempting automatic HTTPS key trust for official ACDS server");
 
    public_key_t key;
    result = parse_public_key(ACDS_OFFICIAL_KEY_SSH_URL, &key);
    if (result != ASCIICHAT_OK) {
      log_debug("SSH key download failed, trying GPG key");
      result = parse_public_key(ACDS_OFFICIAL_KEY_GPG_URL, &key);
    }
 
    if (result != ASCIICHAT_OK) {
      return SET_ERRNO(ERROR_NETWORK, "Failed to download key from official ACDS server");
    }
 
    memcpy(new_pubkey, key.key, 32);
 
  } else if (!key_spec) {
    // No key_spec and not official server = error
    return SET_ERRNO(ERROR_INVALID_PARAM,
                     "Third-party ACDS servers require explicit --discovery-service-key configuration."
                     "Only %s has automatic trust.",
                     ACDS_OFFICIAL_SERVER);
 
  } else {
    // Use parse_public_key for all other cases (handles HTTPS, files, github:, gitlab:, etc.)
    public_key_t key;
    result = parse_public_key(key_spec, &key);
    if (result != ASCIICHAT_OK) {
      return SET_ERRNO(ERROR_CRYPTO_KEY, "Failed to load/download ACDS key from: %s", key_spec);
    }
 
    memcpy(new_pubkey, key.key, 32);
  }
 
  // ===========================================================================
  // Step 2: Check cache and handle key changes
  // ===========================================================================
 
  uint8_t cached_pubkey[32];
  result = discovery_keys_load_cached(acds_server, cached_pubkey);
 
  if (result == ASCIICHAT_OK) {
    // Cached key exists - compare
    if (memcmp(cached_pubkey, new_pubkey, 32) != 0) {
      // Key changed - require user verification
      result = discovery_keys_verify_change(acds_server, cached_pubkey, new_pubkey);
      if (result != ASCIICHAT_OK) {
        return result; // User rejected or error
      }
 
      // User accepted - update cache
      result = discovery_keys_save_cached(acds_server, new_pubkey);
      if (result != ASCIICHAT_OK) {
        log_warn("Failed to update cached key, continuing anyway");
      }
    } else {
      log_debug("ACDS key matches cached key for: %s", acds_server);
    }
 
  } else {
    // No cached key - save it for next time
    log_info("First connection to ACDS server: %s, caching key", acds_server);
    result = discovery_keys_save_cached(acds_server, new_pubkey);
    if (result != ASCIICHAT_OK) {
      log_warn("Failed to cache key, continuing anyway");
    }
  }
 
  // ===========================================================================
  // Step 3: Return verified key
  // ===========================================================================
 
  memcpy(pubkey_out, new_pubkey, 32);
  log_debug("ACDS key verification successful for: %s", acds_server);
  return ASCIICHAT_OK;
}

References ACDS_OFFICIAL_KEY_GPG_URL, ACDS_OFFICIAL_KEY_SSH_URL, ACDS_OFFICIAL_SERVER, ASCIICHAT_OK, discovery_keys_load_cached(), discovery_keys_save_cached(), discovery_keys_verify_change(), ERROR_CRYPTO_KEY, ERROR_INVALID_PARAM, ERROR_NETWORK, public_key_t::key, log_debug, log_info, log_warn, parse_public_key(), and SET_ERRNO.

Referenced by client_crypto_init().

discovery_keys_verify_change()

asciichat_error_t discovery_keys_verify_change	(	const char *	acds_server,
		const uint8_t	old_pubkey[32],
		const uint8_t	new_pubkey[32]
	)

Verify key change with user.

When a cached key doesn't match the newly downloaded/loaded key, prompts the user to verify the change.

Displays:

• Old key fingerprint (SHA256)
• New key fingerprint (SHA256)
• Warning about potential MITM attack
• Prompt: "Accept new key? (y/N): "

Parameters

acds_server	ACDS server hostname
old_pubkey	Previous cached key (32 bytes)
new_pubkey	New downloaded key (32 bytes)

Returns

ASCIICHAT_OK if user accepts, ERROR_USER_REJECTED if declined

Definition at line 233 of file discovery_keys.c.

                                                                             {
  if (!acds_server || !old_pubkey || !new_pubkey) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL parameter in discovery_keys_verify_change");
  }
 
  char old_fingerprint[65], new_fingerprint[65];
  compute_key_fingerprint(old_pubkey, old_fingerprint);
  compute_key_fingerprint(new_pubkey, new_fingerprint);
 
  const char *warning_msg = "\n"
                            "⚠️  WARNING: ACDS SERVER KEY HAS CHANGED\n"
                            "═══════════════════════════════════════════════════════════════\n"
                            "Server: %s\n"
                            "\n"
                            "Old key (SHA256): %s\n"
                            "New key (SHA256): %s\n"
                            "\n"
                            "This could indicate:\n"
                            "  1. The server operator rotated their key\n"
                            "  2. A man-in-the-middle attack is in progress\n"
                            "\n"
                            "Verify the new key fingerprint with the server operator before accepting.\n"
                            "═══════════════════════════════════════════════════════════════\n";
 
  // Log to both stderr (via log_warn) and file log
  log_warn(warning_msg, acds_server, old_fingerprint, new_fingerprint);
 
  // Ask user to confirm
  bool accepted = platform_prompt_yes_no("Accept new ACDS server key", false);
  if (!accepted) {
    return SET_ERRNO(ERROR_CRYPTO_VERIFICATION, "User rejected ACDS key change for: %s", acds_server);
  }
 
  log_info("User accepted ACDS key change for: %s", acds_server);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, compute_key_fingerprint(), ERROR_CRYPTO_VERIFICATION, ERROR_INVALID_PARAM, log_info, log_warn, platform_prompt_yes_no(), and SET_ERRNO.

Referenced by discovery_keys_verify().