acds_client.h File Reference

ACIP client-side protocol library and ACDS client connection API. More...

Go to the source code of this file.

Data Structures
struct	acds_client_config_t
	ACDS client connection configuration. More...
struct	acds_client_t
	ACDS client connection handle. More...
struct	acds_session_create_params_t
	Session creation request parameters. More...
struct	acds_session_create_result_t
	Session creation result. More...
struct	acds_session_lookup_result_t
	Session lookup result. More...
struct	acds_session_join_params_t
	Session join parameters. More...
struct	acds_session_join_result_t
	Session join result. More...

Typedefs
typedef bool(*	parallel_connect_should_exit_fn) (void *user_data)

Functions
asciichat_error_t	acds_client_connect (acds_client_t *client, const acds_client_config_t *config)
	Connect to ACDS server.
void	acds_client_disconnect (acds_client_t *client)
	Disconnect from ACDS server.
asciichat_error_t	acds_session_create (acds_client_t *client, const acds_session_create_params_t *params, acds_session_create_result_t *result)
	Create a new session on the discovery server.
asciichat_error_t	acds_session_lookup (acds_client_t *client, const char *session_string, acds_session_lookup_result_t *result)
	Look up session by string.
asciichat_error_t	acds_session_join (acds_client_t *client, const acds_session_join_params_t *params, acds_session_join_result_t *result)
	Join an existing session.
asciichat_error_t	acds_sign_session_create (const uint8_t identity_seckey[64], uint64_t timestamp, uint8_t capabilities, uint8_t max_participants, uint8_t signature_out[64])
	Sign a SESSION_CREATE message.
asciichat_error_t	acds_verify_session_create (const uint8_t identity_pubkey[32], uint64_t timestamp, uint8_t capabilities, uint8_t max_participants, const uint8_t signature[64])
	Verify SESSION_CREATE signature.
asciichat_error_t	acds_sign_session_join (const uint8_t identity_seckey[64], uint64_t timestamp, const char *session_string, uint8_t signature_out[64])
	Sign a SESSION_JOIN message.
asciichat_error_t	acds_verify_session_join (const uint8_t identity_pubkey[32], uint64_t timestamp, const char *session_string, const uint8_t signature[64])
	Verify SESSION_JOIN signature.
bool	acds_validate_timestamp (uint64_t timestamp_ms, uint32_t window_seconds)
	Check if timestamp is within acceptable window.
void	acds_client_config_init_defaults (acds_client_config_t *config)
	Initialize ACDS client configuration with defaults.

Detailed Description

ACIP client-side protocol library and ACDS client connection API.

Definition in file acds_client.h.

Typedef Documentation

parallel_connect_should_exit_fn

typedef bool(* parallel_connect_should_exit_fn) (void *user_data)

Definition at line 106 of file acds_client.h.

Function Documentation

acds_client_config_init_defaults()

void acds_client_config_init_defaults

(

acds_client_config_t *

config

)

Initialize ACDS client configuration with defaults.

Sets default values:

• server_address: "127.0.0.1"
• server_port: 27225
• timeout_ms: 5000

Parameters

config

Configuration to initialize

Definition at line 111 of file acds_client.c.

                                                                    {
  if (!config) {
    return;
  }
 
  memset(config, 0, sizeof(*config));
  SAFE_STRNCPY(config->server_address, "127.0.0.1", sizeof(config->server_address));
  config->server_port = ACIP_DISCOVERY_DEFAULT_PORT;
  config->timeout_ms = 5 * MS_PER_SEC_INT;
}

References ACIP_DISCOVERY_DEFAULT_PORT, MS_PER_SEC_INT, SAFE_STRNCPY, acds_client_config_t::server_address, acds_client_config_t::server_port, and acds_client_config_t::timeout_ms.

Referenced by client_crypto_init().

acds_client_connect()

asciichat_error_t acds_client_connect	(	acds_client_t *	client,
		const acds_client_config_t *	config
	)

Connect to ACDS server.

Establishes TCP connection to the discovery server.

Parameters

client	Client handle (output)
config	Connection configuration

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 126 of file acds_client.c.

                                                                                                 {
  if (!client || !config) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "client or config is NULL");
  }
 
  memset(client, 0, sizeof(*client));
  memcpy(&client->config, config, sizeof(acds_client_config_t));
  client->socket = INVALID_SOCKET_VALUE;
  client->connected = false;
 
  // Resolve server address (supports both hostnames and IP addresses, IPv4 and IPv6)
  struct addrinfo hints;
  struct addrinfo *result = NULL;
  memset(&hints, 0, sizeof(hints));
  hints.ai_family = AF_UNSPEC;     // IPv4 or IPv6
  hints.ai_socktype = SOCK_STREAM; // TCP
 
  char port_str[16];
  safe_snprintf(port_str, sizeof(port_str), "%d", config->server_port);
 
  log_debug("ACDS: Resolving address '%s:%s'...", config->server_address, port_str);
  int gai_result = getaddrinfo(config->server_address, port_str, &hints, &result);
  if (gai_result != 0) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to resolve server address '%s': %s", config->server_address,
                     gai_strerror(gai_result));
  }
  log_debug("ACDS: Address resolved successfully");
  freeaddrinfo(result);
 
  // Use parallel_connect to attempt IPv4 and IPv6 connections concurrently
  parallel_connect_config_t pconn_config = {
      .hostname = config->server_address,
      .port = config->server_port,
      .timeout_ms = config->timeout_ms,
      .should_exit_callback = config->should_exit_callback,
      .callback_data = config->callback_data,
  };
 
  asciichat_error_t pconn_result = parallel_connect(&pconn_config, &client->socket);
  if (pconn_result == ASCIICHAT_OK) {
    client->connected = true;
 
    client->transport = acip_tcp_transport_create("acds_client_transport", client->socket, NULL);
    if (!client->transport) {
      socket_close(client->socket);
      client->socket = INVALID_SOCKET_VALUE;
      client->connected = false;
      return SET_ERRNO(ERROR_NETWORK, "Failed to create ACDS transport");
    }
 
    asciichat_error_t handshake_result = acds_client_handshake(client);
    if (handshake_result != ASCIICHAT_OK) {
      acip_transport_destroy(client->transport);
      client->transport = NULL;
      socket_close(client->socket);
      client->socket = INVALID_SOCKET_VALUE;
      client->connected = false;
      return handshake_result;
    }
 
    /* Register ACDS client with named registry */
    char acds_name[64];
    snprintf(acds_name, sizeof(acds_name), "acds_client:%s:%d", config->server_address, config->server_port);
    NAMED_REGISTER(client, acds_name, "acds_client_t", "0x%tx", NULL);
 
    log_info("Connected to ACDS server at %s:%d", config->server_address, config->server_port);
    return ASCIICHAT_OK;
  }
 
  return pconn_result;
}

References acip_tcp_transport_create(), acip_transport_destroy(), ASCIICHAT_OK, acds_client_config_t::callback_data, acds_client_t::config, acds_client_t::connected, ERROR_INVALID_PARAM, ERROR_NETWORK, parallel_connect_config_t::hostname, INVALID_SOCKET_VALUE, log_debug, log_info, NAMED_REGISTER, parallel_connect(), safe_snprintf(), acds_client_config_t::server_address, acds_client_config_t::server_port, SET_ERRNO, acds_client_config_t::should_exit_callback, acds_client_t::socket, socket_close(), acds_client_config_t::timeout_ms, and acds_client_t::transport.

Referenced by client_crypto_init().

acds_client_disconnect()

void acds_client_disconnect

(

acds_client_t *

client

)

Disconnect from ACDS server.

Closes the connection and cleans up resources.

Parameters

client

Client handle

Definition at line 198 of file acds_client.c.

                                                   {
  if (!client) {
    return;
  }
 
  if (client->socket != INVALID_SOCKET_VALUE) {
    if (client->transport) {
      acip_transport_destroy(client->transport);
      client->transport = NULL;
    }
    crypto_handshake_destroy(&client->handshake_ctx);
    socket_close(client->socket);
    client->socket = INVALID_SOCKET_VALUE;
  }
 
  client->connected = false;
  log_debug("Disconnected from ACDS server");
}

References acip_transport_destroy(), acds_client_t::connected, crypto_handshake_destroy(), acds_client_t::handshake_ctx, INVALID_SOCKET_VALUE, log_debug, acds_client_t::socket, socket_close(), and acds_client_t::transport.

Referenced by client_crypto_init().

acds_session_create()

asciichat_error_t acds_session_create	(	acds_client_t *	client,
		const acds_session_create_params_t *	params,
		acds_session_create_result_t *	result
	)

Create a new session on the discovery server.

Sends SESSION_CREATE packet and receives SESSION_CREATED response.

Parameters

client	Connected ACDS client
params	Session creation parameters
result	Session creation result (output)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 221 of file acds_client.c.

                                                                            {
  if (!client || !params || !result) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  if (!client->connected) {
    return SET_ERRNO(ERROR_NETWORK, "Not connected to ACDS server");
  }
 
  // Build SESSION_CREATE payload
  acip_session_create_t req;
  memset(&req, 0, sizeof(req));
 
  memcpy(req.identity_pubkey, params->identity_pubkey, 32);
 
  // Sign the request: type || timestamp || capabilities
  uint64_t timestamp = (uint64_t)time(NULL) * 1000; // Unix ms
  req.timestamp = timestamp;
  req.capabilities = params->capabilities;
  req.max_participants = params->max_participants;
 
  // Generate Ed25519 signature for identity verification
  asciichat_error_t sign_result = acds_sign_session_create(params->identity_seckey, timestamp, params->capabilities,
                                                           params->max_participants, req.signature);
  if (sign_result != ASCIICHAT_OK) {
    return SET_ERRNO(ERROR_CRYPTO, "Failed to sign SESSION_CREATE request");
  }
 
  req.has_password = params->has_password ? 1 : 0;
  if (params->has_password) {
    // Hash password with Argon2id using libsodium
    // crypto_pwhash_str produces a null-terminated ASCII string
    if (crypto_pwhash_str((char *)req.password_hash, params->password, strlen(params->password),
                          crypto_pwhash_OPSLIMIT_INTERACTIVE, crypto_pwhash_MEMLIMIT_INTERACTIVE) != 0) {
      return SET_ERRNO(ERROR_CRYPTO, "Failed to hash password (out of memory)");
    }
  } else {
    memset(req.password_hash, 0, sizeof(req.password_hash));
  }
 
  req.reserved_string_len = 0; // Auto-generate
  if (params->reserved_string && params->reserved_string[0] != '\0') {
    req.reserved_string_len = strlen(params->reserved_string);
    // Variable part would follow here (not implemented yet)
  }
 
  // Server connection information
  SAFE_STRNCPY(req.server_address, params->server_address, sizeof(req.server_address));
  req.server_port = params->server_port;
 
  // IP disclosure policy
  // Auto-detection: If password is set, IP will be revealed after verification
  // If no password, require explicit opt-in via acds_expose_ip
  req.expose_ip_publicly = params->acds_expose_ip ? 1 : 0;
 
  // Session type (Direct TCP or WebRTC)
  req.session_type = params->session_type;
 
  // Multi-key protocol: set to single-key mode (total_keys=0 for backward compatibility, or =1 for new protocol)
  // For now, using legacy single-key mode (total_keys=0, key_index=0)
  req.total_keys = 0; // Legacy mode: server knows this is single-key
  req.key_index = 0;  // Not used in legacy mode
 
  // Send SESSION_CREATE packet
  asciichat_error_t send_result = send_packet(client->socket, PACKET_TYPE_ACIP_SESSION_CREATE, &req, sizeof(req));
  if (send_result != ASCIICHAT_OK) {
    return send_result;
  }
 
  log_debug("Sent SESSION_CREATE request");
  log_debug("★ ACDS_CLIENT: About to receive SESSION_CREATED on socket %d", client->socket);
 
  // Receive SESSION_CREATED response
  packet_type_t resp_type;
  void *resp_payload = NULL;
  size_t resp_size = 0;
 
  int recv_result = receive_packet(client->socket, &resp_type, &resp_payload, &resp_size);
  log_debug("★ ACDS_CLIENT: receive_packet returned %d", recv_result);
  if (recv_result < 0) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to receive SESSION_CREATED response");
  }
 
  // Check response type
  if (resp_type != PACKET_TYPE_ACIP_SESSION_CREATED) {
    if (resp_type == PACKET_TYPE_ERROR_MESSAGE || resp_type == PACKET_TYPE_ACIP_ERROR) {
      log_error("Session creation failed: server returned error packet");
      buffer_pool_free(NULL, resp_payload, resp_size);
      return SET_ERRNO(ERROR_NETWORK, "Session creation failed");
    }
    buffer_pool_free(NULL, resp_payload, resp_size);
    return SET_ERRNO(ERROR_NETWORK, "Unexpected response type: 0x%02X", resp_type);
  }
 
  // Parse SESSION_CREATED response
  if (resp_size < sizeof(acip_session_created_t)) {
    buffer_pool_free(NULL, resp_payload, resp_size);
    return SET_ERRNO(ERROR_NETWORK, "SESSION_CREATED response too small: %zu bytes", resp_size);
  }
 
  acip_session_created_t *resp = (acip_session_created_t *)resp_payload;
 
  // Copy session string (null-terminate)
  size_t string_len = resp->session_string_len < sizeof(result->session_string) - 1
                          ? resp->session_string_len
                          : sizeof(result->session_string) - 1;
  memcpy(result->session_string, resp->session_string, string_len);
  result->session_string[string_len] = '\0';
 
  memcpy(result->session_id, resp->session_id, 16);
  result->expires_at = resp->expires_at;
 
  log_info("Session created: %s (expires at %llu)", result->session_string, (unsigned long long)result->expires_at);
 
  buffer_pool_free(NULL, resp_payload, resp_size);
  return ASCIICHAT_OK;
}

References acds_session_create_params_t::acds_expose_ip, acds_sign_session_create(), acip_session_create_t, acip_session_created_t, ASCIICHAT_OK, buffer_pool_free(), acds_session_create_params_t::capabilities, acds_client_t::connected, ERROR_CRYPTO, ERROR_INVALID_PARAM, ERROR_NETWORK, acds_session_create_result_t::expires_at, acds_session_create_params_t::has_password, acds_session_create_params_t::identity_pubkey, acds_session_create_params_t::identity_seckey, log_debug, log_error, log_info, acds_session_create_params_t::max_participants, PACKET_TYPE_ACIP_ERROR, PACKET_TYPE_ACIP_SESSION_CREATE, PACKET_TYPE_ACIP_SESSION_CREATED, PACKET_TYPE_ERROR_MESSAGE, acds_session_create_params_t::password, receive_packet(), acds_session_create_params_t::reserved_string, SAFE_STRNCPY, send_packet(), acds_session_create_params_t::server_address, acds_session_create_params_t::server_port, acds_session_create_result_t::session_id, acds_session_create_result_t::session_string, acds_session_create_params_t::session_type, SET_ERRNO, and acds_client_t::socket.

acds_session_join()

asciichat_error_t acds_session_join	(	acds_client_t *	client,
		const acds_session_join_params_t *	params,
		acds_session_join_result_t *	result
	)

Join an existing session.

Sends SESSION_JOIN packet and receives SESSION_JOINED response.

Parameters

client	Connected ACDS client
params	Join parameters
result	Join result (output)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 417 of file acds_client.c.

                                                                        {
  if (!client || !params || !result) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  if (!client->connected) {
    return SET_ERRNO(ERROR_NETWORK, "Not connected to ACDS server");
  }
 
  // Build SESSION_JOIN payload
  acip_session_join_t req;
  memset(&req, 0, sizeof(req));
 
  req.session_string_len = strlen(params->session_string);
  if (req.session_string_len >= sizeof(req.session_string)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Session string too long");
  }
 
  memcpy(req.session_string, params->session_string, req.session_string_len);
  memcpy(req.identity_pubkey, params->identity_pubkey, 32);
 
  // Sign the request: type || timestamp || session_string
  uint64_t timestamp = (uint64_t)time(NULL) * 1000;
  req.timestamp = timestamp;
 
  // Generate Ed25519 signature for identity verification
  asciichat_error_t sign_result =
      acds_sign_session_join(params->identity_seckey, timestamp, params->session_string, req.signature);
  if (sign_result != ASCIICHAT_OK) {
    return SET_ERRNO(ERROR_CRYPTO, "Failed to sign SESSION_JOIN request");
  }
 
  req.has_password = params->has_password ? 1 : 0;
  if (params->has_password) {
    SAFE_STRNCPY(req.password, params->password, sizeof(req.password));
  }
 
  // Send SESSION_JOIN packet
  asciichat_error_t send_result = send_packet(client->socket, PACKET_TYPE_ACIP_SESSION_JOIN, &req, sizeof(req));
  if (send_result != ASCIICHAT_OK) {
    return send_result;
  }
 
  log_debug("Sent SESSION_JOIN request for '%s'", params->session_string);
 
  // Receive SESSION_JOINED response
  packet_type_t resp_type;
  void *resp_payload = NULL;
  size_t resp_size = 0;
 
  int recv_result = receive_packet(client->socket, &resp_type, &resp_payload, &resp_size);
  if (recv_result < 0) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to receive SESSION_JOINED response");
  }
 
  if (resp_type != PACKET_TYPE_ACIP_SESSION_JOINED) {
    buffer_pool_free(NULL, resp_payload, resp_size);
    return SET_ERRNO(ERROR_NETWORK, "Unexpected response type: 0x%02X", resp_type);
  }
 
  if (resp_size < sizeof(acip_session_joined_t)) {
    buffer_pool_free(NULL, resp_payload, resp_size);
    return SET_ERRNO(ERROR_NETWORK, "SESSION_JOINED response too small");
  }
 
  acip_session_joined_t *resp = (acip_session_joined_t *)resp_payload;
 
  // Copy result
  result->success = resp->success != 0;
  if (result->success) {
    memcpy(result->participant_id, resp->participant_id, 16);
    memcpy(result->session_id, resp->session_id, 16);
    // Server connection information (ONLY revealed after successful authentication)
    result->session_type = resp->session_type;
    SAFE_STRNCPY(result->server_address, resp->server_address, sizeof(result->server_address));
    result->server_port = resp->server_port;
    log_info("Joined session successfully (participant ID: %02x%02x..., server=%s:%d, type=%s)",
             result->participant_id[0], result->participant_id[1], result->server_address, result->server_port,
             result->session_type == SESSION_TYPE_WEBRTC ? "WebRTC" : "DirectTCP");
  } else {
    result->error_code = resp->error_code;
    size_t msg_len = strnlen(resp->error_message, sizeof(resp->error_message));
    if (msg_len >= sizeof(result->error_message)) {
      msg_len = sizeof(result->error_message) - 1;
    }
    memcpy(result->error_message, resp->error_message, msg_len);
    result->error_message[msg_len] = '\0';
    log_warn("Failed to join session: %s (code %d)", result->error_message, result->error_code);
  }
 
  buffer_pool_free(NULL, resp_payload, resp_size);
  return ASCIICHAT_OK;
}

References acds_sign_session_join(), acip_session_join_t, acip_session_joined_t, ASCIICHAT_OK, buffer_pool_free(), acds_client_t::connected, acds_session_join_result_t::error_code, ERROR_CRYPTO, ERROR_INVALID_PARAM, acds_session_join_result_t::error_message, ERROR_NETWORK, acds_session_join_params_t::has_password, acds_session_join_params_t::identity_pubkey, acds_session_join_params_t::identity_seckey, log_debug, log_info, log_warn, PACKET_TYPE_ACIP_SESSION_JOIN, PACKET_TYPE_ACIP_SESSION_JOINED, acds_session_join_result_t::participant_id, acds_session_join_params_t::password, receive_packet(), SAFE_STRNCPY, send_packet(), acds_session_join_result_t::server_address, acds_session_join_result_t::server_port, acds_session_join_result_t::session_id, acds_session_join_params_t::session_string, acds_session_join_result_t::session_type, SESSION_TYPE_WEBRTC, SET_ERRNO, acds_client_t::socket, and acds_session_join_result_t::success.

acds_session_lookup()

asciichat_error_t acds_session_lookup	(	acds_client_t *	client,
		const char *	session_string,
		acds_session_lookup_result_t *	result
	)

Look up session by string.

Sends SESSION_LOOKUP packet and receives SESSION_INFO response.

Parameters

client	Connected ACDS client
session_string	Session string to look up
result	Lookup result (output)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 340 of file acds_client.c.

                                                                            {
  if (!client || !session_string || !result) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  if (!client->connected) {
    return SET_ERRNO(ERROR_NETWORK, "Not connected to ACDS server");
  }
 
  // Build SESSION_LOOKUP payload
  acip_session_lookup_t req;
  memset(&req, 0, sizeof(req));
 
  req.session_string_len = strlen(session_string);
  if (req.session_string_len >= sizeof(req.session_string)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Session string too long");
  }
 
  memcpy(req.session_string, session_string, req.session_string_len);
 
  // Send SESSION_LOOKUP packet
  asciichat_error_t send_result = send_packet(client->socket, PACKET_TYPE_ACIP_SESSION_LOOKUP, &req, sizeof(req));
  if (send_result != ASCIICHAT_OK) {
    return send_result;
  }
 
  log_debug("Sent SESSION_LOOKUP request for '%s'", session_string);
 
  // Receive SESSION_INFO response
  packet_type_t resp_type;
  void *resp_payload = NULL;
  size_t resp_size = 0;
 
  int recv_result = receive_packet(client->socket, &resp_type, &resp_payload, &resp_size);
  if (recv_result < 0) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to receive SESSION_INFO response");
  }
 
  if (resp_type != PACKET_TYPE_ACIP_SESSION_INFO) {
    buffer_pool_free(NULL, resp_payload, resp_size);
    return SET_ERRNO(ERROR_NETWORK, "Unexpected response type: 0x%02X", resp_type);
  }
 
  if (resp_size < sizeof(acip_session_info_t)) {
    buffer_pool_free(NULL, resp_payload, resp_size);
    return SET_ERRNO(ERROR_NETWORK, "SESSION_INFO response too small");
  }
 
  acip_session_info_t *resp = (acip_session_info_t *)resp_payload;
 
  // Copy result
  result->found = resp->found != 0;
  if (result->found) {
    memcpy(result->session_id, resp->session_id, 16);
    memcpy(result->host_pubkey, resp->host_pubkey, 32);
    result->capabilities = resp->capabilities;
    result->max_participants = resp->max_participants;
    result->current_participants = resp->current_participants;
    result->has_password = resp->has_password != 0;
    result->created_at = resp->created_at;
    result->expires_at = resp->expires_at;
    result->require_server_verify = resp->require_server_verify != 0;
    result->require_client_verify = resp->require_client_verify != 0;
 
    log_info("Session found: %s (%d/%d participants, password=%s, policies: server_verify=%d client_verify=%d)",
             session_string, result->current_participants, result->max_participants,
             result->has_password ? "required" : "not required", result->require_server_verify,
             result->require_client_verify);
  } else {
    log_info("Session not found: %s", session_string);
  }
 
  buffer_pool_free(NULL, resp_payload, resp_size);
  return ASCIICHAT_OK;
}

References acip_session_info_t, acip_session_lookup_t, ASCIICHAT_OK, buffer_pool_free(), acds_session_lookup_result_t::capabilities, acds_client_t::connected, acds_session_lookup_result_t::created_at, acds_session_lookup_result_t::current_participants, ERROR_INVALID_PARAM, ERROR_NETWORK, ERROR_NOT_SUPPORTED, acds_session_lookup_result_t::expires_at, acds_session_lookup_result_t::found, acds_session_lookup_result_t::has_password, acds_session_lookup_result_t::host_pubkey, log_debug, log_info, acds_session_lookup_result_t::max_participants, PACKET_TYPE_ACIP_SESSION_INFO, PACKET_TYPE_ACIP_SESSION_LOOKUP, receive_packet(), acds_session_lookup_result_t::require_client_verify, acds_session_lookup_result_t::require_server_verify, send_packet(), acds_session_lookup_result_t::session_id, SET_ERRNO, and acds_client_t::socket.

Referenced by client_crypto_init().

acds_sign_session_create()

asciichat_error_t acds_sign_session_create	(	const uint8_t	identity_seckey[64],
		uint64_t	timestamp,
		uint8_t	capabilities,
		uint8_t	max_participants,
		uint8_t	signature_out[64]
	)

Sign a SESSION_CREATE message.

Computes Ed25519 signature over: type || timestamp || capabilities || max_participants

Parameters

identity_seckey	Ed25519 secret key (64 bytes)
timestamp	Unix milliseconds timestamp
capabilities	Capabilities bitfield
max_participants	Maximum participants (1-8)
signature_out	Output buffer for signature (64 bytes)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 516 of file acds_client.c.

                                                                                                {
  if (!identity_seckey || !signature_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL parameter to acds_sign_session_create");
  }
 
  // Build message: type (1 byte) || timestamp (8 bytes) || capabilities (1 byte) || max_participants (1 byte)
  uint8_t message[11];
  message[0] = (uint8_t)PACKET_TYPE_ACIP_SESSION_CREATE;
 
  // Convert timestamp to network byte order and pack into message
  uint64_t timestamp_net = HOST_TO_NET_U64(timestamp);
  memcpy(&message[1], &timestamp_net, sizeof(timestamp_net));
 
  message[9] = capabilities;
  message[10] = max_participants;
 
  // Sign using Ed25519
  if (crypto_sign_detached(signature_out, NULL, message, sizeof(message), identity_seckey) != 0) {
    return SET_ERRNO(ERROR_CRYPTO, "Ed25519 signature generation failed");
  }
 
  log_debug("Generated SESSION_CREATE signature (timestamp=%llu, caps=%u, max=%u)", (unsigned long long)timestamp,
            capabilities, max_participants);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO, ERROR_INVALID_PARAM, HOST_TO_NET_U64, log_debug, PACKET_TYPE_ACIP_SESSION_CREATE, and SET_ERRNO.

Referenced by acds_session_create().

acds_sign_session_join()

asciichat_error_t acds_sign_session_join	(	const uint8_t	identity_seckey[64],
		uint64_t	timestamp,
		const char *	session_string,
		uint8_t	signature_out[64]
	)

Sign a SESSION_JOIN message.

Computes Ed25519 signature over: type || timestamp || session_string

Parameters

identity_seckey	Ed25519 secret key (64 bytes)
timestamp	Unix milliseconds timestamp
session_string	Session string (null-terminated)
signature_out	Output buffer for signature (64 bytes)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 572 of file acds_client.c.

                                                                                                {
  if (!identity_seckey || !session_string || !signature_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL parameter to acds_sign_session_join");
  }
 
  size_t session_len = strlen(session_string);
  if (session_len > 48) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Session string too long (max 48 chars)");
  }
 
  // Build message: type (1 byte) || timestamp (8 bytes) || session_string (variable length)
  uint8_t message[1 + 8 + 48];
  message[0] = (uint8_t)PACKET_TYPE_ACIP_SESSION_JOIN;
 
  // Convert timestamp to network byte order and pack into message
  uint64_t timestamp_net = HOST_TO_NET_U64(timestamp);
  memcpy(&message[1], &timestamp_net, sizeof(timestamp_net));
 
  // Copy session string (copy exactly session_len bytes, no null terminator in signature)
  memcpy(&message[9], session_string, session_len);
 
  size_t message_len = 9 + session_len;
 
  // Sign using Ed25519
  if (crypto_sign_detached(signature_out, NULL, message, message_len, identity_seckey) != 0) {
    return SET_ERRNO(ERROR_CRYPTO, "Ed25519 signature generation failed");
  }
 
  log_debug("Generated SESSION_JOIN signature (timestamp=%llu, session='%s')", (unsigned long long)timestamp,
            session_string);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO, ERROR_INVALID_PARAM, HOST_TO_NET_U64, log_debug, PACKET_TYPE_ACIP_SESSION_JOIN, and SET_ERRNO.

Referenced by acds_session_join().

acds_validate_timestamp()

bool acds_validate_timestamp	(	uint64_t	timestamp_ms,
		uint32_t	window_seconds
	)

Check if timestamp is within acceptable window.

Validates timestamp is recent (within window_seconds of current time) and not in the future.

Parameters

timestamp_ms	Unix milliseconds timestamp
window_seconds	Acceptable age window (e.g., 300 for 5 minutes)

Returns

true if timestamp is valid, false if too old or in the future

Definition at line 641 of file acds_client.c.

                                                                             {
  uint64_t now_ms = time_ns_to_ms(time_get_realtime_ns());
  uint64_t window_ms = (uint64_t)window_seconds * 1000;
 
  if (timestamp_ms > now_ms + 60000) {
    int64_t skew = (int64_t)timestamp_ms - (int64_t)now_ms;
    log_warn("Timestamp is in the future: %llu > %llu (skew: %lld ms)", (unsigned long long)timestamp_ms,
             (unsigned long long)now_ms, (long long)skew);
    return false;
  }
 
  uint64_t min_valid_timestamp = (now_ms >= window_ms) ? (now_ms - window_ms) : 0;
  if (timestamp_ms < min_valid_timestamp) {
    int64_t age = (int64_t)now_ms - (int64_t)timestamp_ms;
    log_warn("Timestamp is too old: %llu < %llu (age: %lld ms, max: %u seconds)", (unsigned long long)timestamp_ms,
             (unsigned long long)min_valid_timestamp, (long long)age, window_seconds);
    return false;
  }
 
  int64_t age = (int64_t)now_ms - (int64_t)timestamp_ms;
  log_debug("Timestamp validation passed (age: %lld ms, window: %u seconds)", (long long)age, window_seconds);
  return true;
}

References log_debug, log_warn, and time_get_realtime_ns().

acds_verify_session_create()

asciichat_error_t acds_verify_session_create	(	const uint8_t	identity_pubkey[32],
		uint64_t	timestamp,
		uint8_t	capabilities,
		uint8_t	max_participants,
		const uint8_t	signature[64]
	)

Verify SESSION_CREATE signature.

Verifies Ed25519 signature matches the message fields.

Parameters

identity_pubkey	Ed25519 public key (32 bytes)
timestamp	Unix milliseconds timestamp
capabilities	Capabilities bitfield
max_participants	Maximum participants
signature	Signature to verify (64 bytes)

Returns

ASCIICHAT_OK if valid, ERROR_CRYPTO_VERIFY_FAILED if invalid

Definition at line 544 of file acds_client.c.

                                                                          {
  if (!identity_pubkey || !signature) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL parameter to acds_verify_session_create");
  }
 
  // Build message: type (1 byte) || timestamp (8 bytes) || capabilities (1 byte) || max_participants (1 byte)
  uint8_t message[11];
  message[0] = (uint8_t)PACKET_TYPE_ACIP_SESSION_CREATE;
 
  // Convert timestamp to network byte order and pack into message
  uint64_t timestamp_net = HOST_TO_NET_U64(timestamp);
  memcpy(&message[1], &timestamp_net, sizeof(timestamp_net));
 
  message[9] = capabilities;
  message[10] = max_participants;
 
  // Verify using Ed25519
  if (crypto_sign_verify_detached(signature, message, sizeof(message), identity_pubkey) != 0) {
    log_warn("SESSION_CREATE signature verification failed");
    return SET_ERRNO(ERROR_CRYPTO_VERIFICATION, "Invalid SESSION_CREATE signature");
  }
 
  log_debug("SESSION_CREATE signature verified successfully");
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO_VERIFICATION, ERROR_INVALID_PARAM, HOST_TO_NET_U64, log_debug, log_warn, PACKET_TYPE_ACIP_SESSION_CREATE, and SET_ERRNO.

acds_verify_session_join()

asciichat_error_t acds_verify_session_join	(	const uint8_t	identity_pubkey[32],
		uint64_t	timestamp,
		const char *	session_string,
		const uint8_t	signature[64]
	)

Verify SESSION_JOIN signature.

Verifies Ed25519 signature matches the message fields.

Parameters

identity_pubkey	Ed25519 public key (32 bytes)
timestamp	Unix milliseconds timestamp
session_string	Session string (null-terminated)
signature	Signature to verify (64 bytes)

Returns

ASCIICHAT_OK if valid, ERROR_CRYPTO_VERIFY_FAILED if invalid

Definition at line 607 of file acds_client.c.

                                                                                                    {
  if (!identity_pubkey || !session_string || !signature) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL parameter to acds_verify_session_join");
  }
 
  size_t session_len = strlen(session_string);
  if (session_len > 48) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Session string too long (max 48 chars)");
  }
 
  // Build message: type (1 byte) || timestamp (8 bytes) || session_string (variable length)
  uint8_t message[1 + 8 + 48];
  message[0] = (uint8_t)PACKET_TYPE_ACIP_SESSION_JOIN;
 
  // Convert timestamp to network byte order and pack into message
  uint64_t timestamp_net = HOST_TO_NET_U64(timestamp);
  memcpy(&message[1], &timestamp_net, sizeof(timestamp_net));
 
  // Copy session string (copy exactly session_len bytes, no null terminator in signature)
  memcpy(&message[9], session_string, session_len);
 
  size_t message_len = 9 + session_len;
 
  // Verify using Ed25519
  if (crypto_sign_verify_detached(signature, message, message_len, identity_pubkey) != 0) {
    log_warn("SESSION_JOIN signature verification failed");
    return SET_ERRNO(ERROR_CRYPTO_VERIFICATION, "Invalid SESSION_JOIN signature");
  }
 
  log_debug("SESSION_JOIN signature verified successfully");
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_CRYPTO_VERIFICATION, ERROR_INVALID_PARAM, HOST_TO_NET_U64, log_debug, log_warn, PACKET_TYPE_ACIP_SESSION_JOIN, and SET_ERRNO.