strings.h File Reference

Go to the source code of this file.

Macros
#define	SESSION_STRING_MAX_LEN   38
	Maximum length of a session string (without null terminator)
#define	SESSION_STRING_BUFFER_SIZE   (SESSION_STRING_MAX_LEN + 1)
	Buffer size needed for session string storage (with null terminator) Used for static character array declarations.
#define	ACDS_MAX_UNIQUE_SESSIONS   (2500LL * 5000LL * 5000LL)
	Maximum number of unique session strings that can be generated.

Functions
asciichat_error_t	acds_string_generate (char *output, size_t output_size)
	Generate random session string.
asciichat_error_t	acds_string_init (void)
	Initialize session string system with cached word validation.
bool	is_session_string (const char *str)
	Check if a string is a valid session string.
void	acds_strings_destroy (void)
	Cleanup function for session string cache Called by asciichat_shared_destroy() during library cleanup. Safe to call multiple times (idempotent).

Macro Definition Documentation

ACDS_MAX_UNIQUE_SESSIONS

#define ACDS_MAX_UNIQUE_SESSIONS   (2500LL * 5000LL * 5000LL)

Maximum number of unique session strings that can be generated.

Calculated from wordlist entropy: 2500 adjectives × 5000 nouns × 5000 nouns = 62,500,000,000 combinations

Definition at line 46 of file discovery/strings.h.

SESSION_STRING_BUFFER_SIZE

#define SESSION_STRING_BUFFER_SIZE   (SESSION_STRING_MAX_LEN + 1)

Buffer size needed for session string storage (with null terminator) Used for static character array declarations.

Definition at line 38 of file discovery/strings.h.

SESSION_STRING_MAX_LEN

#define SESSION_STRING_MAX_LEN   38

Maximum length of a session string (without null terminator)

Calculated from longest words:

• Longest adjective: 12 chars (e.g., "affectionate")
• Longest noun: 12 chars (e.g., "acquaintance")
• Format: adjective-noun-noun = 12 + 1 + 12 + 1 + 12 = 38 chars

Definition at line 32 of file discovery/strings.h.

Function Documentation

acds_string_generate()

asciichat_error_t acds_string_generate	(	char *	output,
		size_t	output_size
	)

Generate random session string.

Parameters

output	Output buffer for session string
output_size	Size of output buffer (should be at least SESSION_STRING_BUFFER_SIZE bytes)

Returns

ASCIICHAT_OK on success, error code otherwise

Generates strings in format: adjective-noun-noun Example: "affectionate-acquaintance-acquaintance" (38 characters max)

Use acds_string_get_max_length() to get the maximum possible length. Entropy: 2500 adjectives * 5000 nouns * 5000 nouns = 62.5 billion combinations

Definition at line 222 of file discovery/strings.c.

                                                                         {
  if (!output || output_size < SESSION_STRING_BUFFER_SIZE) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "output buffer must be at least %zu bytes",
                     (size_t)SESSION_STRING_BUFFER_SIZE);
  }
 
  // libsodium is guaranteed to be initialized by acds_string_init() before this is called
  // No need to call sodium_init() again (redundant initialization removed)
 
  // Pick random adjective
  uint32_t adj_idx = randombytes_uniform((uint32_t)adjectives_count);
  const char *adj = adjectives[adj_idx];
 
  // Pick two random nouns
  uint32_t noun1_idx = randombytes_uniform((uint32_t)nouns_count);
  uint32_t noun2_idx = randombytes_uniform((uint32_t)nouns_count);
  const char *noun1 = nouns[noun1_idx];
  const char *noun2 = nouns[noun2_idx];
 
  // Format: adjective-noun-noun
  int written = safe_snprintf(output, output_size, "%s-%s-%s", adj, noun1, noun2);
  if (written < 0 || (size_t)written >= output_size) {
    return SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Session string too long for buffer");
  }
 
  log_dev("Generated session string: %s", output);
  return ASCIICHAT_OK;
}

References adjectives, adjectives_count, ASCIICHAT_OK, ERROR_BUFFER_OVERFLOW, ERROR_INVALID_PARAM, log_dev, nouns, nouns_count, safe_snprintf(), SESSION_STRING_BUFFER_SIZE, and SET_ERRNO.

Referenced by database_session_create(), and options_preset_unified().

acds_string_init()

asciichat_error_t acds_string_init

(

void

)

Initialize session string system with cached word validation.

Returns

ASCIICHAT_OK on success, error code otherwise

Initializes the random number generator and caches adjectives/nouns in a hashtable for fast validation. Must be called before acds_string_generate() and before any is_session_string() validation calls.

Uses libsodium's randombytes for cryptographically secure randomness. Cleans up cached data on program exit via atexit() handler.

Definition at line 218 of file discovery/strings.c.

                                         {
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK.

acds_strings_destroy()

void acds_strings_destroy

(

void

)

Cleanup function for session string cache Called by asciichat_shared_destroy() during library cleanup. Safe to call multiple times (idempotent).

Definition at line 53 of file discovery/strings.c.

                                {
  // Shutdown if initialized
  if (!lifecycle_shutdown(&g_cache_lc)) {
    return; // Not initialized
  }
 
  // Cleanup adjectives cache
  word_cache_entry_t *adj_entry, *adj_tmp;
  HASH_ITER(hh, g_adjectives_cache, adj_entry, adj_tmp) {
    HASH_DEL(g_adjectives_cache, adj_entry);
    SAFE_FREE(adj_entry->word);
    SAFE_FREE(adj_entry);
  }
  g_adjectives_cache = NULL;
 
  // Cleanup nouns cache
  word_cache_entry_t *noun_entry, *noun_tmp;
  HASH_ITER(hh, g_nouns_cache, noun_entry, noun_tmp) {
    HASH_DEL(g_nouns_cache, noun_entry);
    SAFE_FREE(noun_entry->word);
    SAFE_FREE(noun_entry);
  }
  g_nouns_cache = NULL;
 
  log_dev("Session string word cache cleaned up");
}

References lifecycle_shutdown(), log_dev, SAFE_FREE, and word_cache_entry_t::word.

Referenced by asciichat_shared_destroy().

is_session_string()

bool is_session_string

(

const char *

str

)

Check if a string is a valid session string.

Parameters

str	String to validate

Returns

true if valid session string (adjective-noun-noun format), false otherwise

A valid session string must:

• Be in format: adjective-noun-noun
• Contain exactly 3 words separated by exactly 2 hyphens
• Have each word be a real adjective or noun from cached wordlists
• Contain only lowercase ASCII letters and hyphens
• Be 5-47 characters long
• Not start or end with hyphen
• Not contain consecutive hyphens

This function validates against the cached wordlists populated by acds_string_init(). Non-session inputs return false without setting an error. Internal failures set errno.

Definition at line 251 of file discovery/strings.c.

                                        {
  if (!str || str[0] == '\0') {
    return false;
  }
 
  size_t len = strlen(str);
 
  // Check length bounds (min 4, max defined by SESSION_STRING_MAX_LEN)
  if (len < 4 || len > SESSION_STRING_MAX_LEN) {
    return false;
  }
 
  // Session strings must be ASCII-only (homograph attack prevention)
  if (!utf8_is_ascii_only(str)) {
    return false;
  }
 
  // Get compiled regex (lazy initialization)
  pcre2_code *regex = session_format_regex_get();
  if (!regex) {
    SET_ERRNO(ERROR_INTERNAL, "Session string PCRE2 regex failed to initialize");
    return false;
  }
 
  // Validate format using PCRE2 regex
  pcre2_match_data *match_data = pcre2_match_data_create_from_pattern(regex, NULL);
  if (!match_data) {
    log_error("Failed to allocate match data for session string regex");
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate match data");
    return false;
  }
 
  int match_result = pcre2_jit_match(regex, (PCRE2_SPTR8)str, len, 0, 0, match_data, NULL);
 
  pcre2_match_data_free(match_data);
 
  if (match_result < 0) {
    if (match_result != PCRE2_ERROR_NOMATCH) {
      SET_ERRNO(ERROR_INTERNAL, "Session string PCRE2 matching failed: %d", match_result);
    }
    return false;
  }
 
  // Extract the three words by finding hyphens
  // Format is guaranteed to be: word-word-word where each word is 2-12 lowercase letters
  const char *hyphen1 = strchr(str, '-');
  if (!hyphen1) {
    return false;
  }
 
  const char *hyphen2 = strchr(hyphen1 + 1, '-');
  if (!hyphen2) {
    return false;
  }
 
  // Extract three words
  size_t adj_len = hyphen1 - str;
  size_t noun1_len = hyphen2 - hyphen1 - 1;
  size_t noun2_len = len - (hyphen2 - str) - 1;
 
  if (adj_len >= 32 || noun1_len >= 32 || noun2_len >= 32) {
    return false;
  }
 
  char adj[32], noun1[32], noun2[32];
  memcpy(adj, str, adj_len);
  adj[adj_len] = '\0';
  memcpy(noun1, hyphen1 + 1, noun1_len);
  noun1[noun1_len] = '\0';
  memcpy(noun2, hyphen2 + 1, noun2_len);
  noun2[noun2_len] = '\0';
 
  // Lazy initialization: build validation caches on first use
  // call_once ensures thread-safe exactly-once execution
  build_validation_caches();
  // If initialization fails silently (logs warning), hashtables will be empty
  // and validation will fail, which is safe behavior
 
  // Validate first word is an adjective
  word_cache_entry_t *adj_entry = NULL;
  HASH_FIND_STR(g_adjectives_cache, adj, adj_entry);
  if (!adj_entry) {
    return false;
  }
 
  // Validate second and third words are nouns
  word_cache_entry_t *noun_entry1 = NULL;
  HASH_FIND_STR(g_nouns_cache, noun1, noun_entry1);
  if (!noun_entry1) {
    return false;
  }
 
  word_cache_entry_t *noun_entry2 = NULL;
  HASH_FIND_STR(g_nouns_cache, noun2, noun_entry2);
  if (!noun_entry2) {
    return false;
  }
 
  log_dev("Valid session string: %s", str);
  return true;
}

References ERROR_INTERNAL, ERROR_MEMORY, log_dev, log_error, SESSION_STRING_MAX_LEN, SET_ERRNO, and utf8_is_ascii_only().

Referenced by database_session_create(), discover_session_parallel(), and parse_client_address().