client.h File Reference

Client-side handshake functions. More...

Go to the source code of this file.

Functions
Client Handshake Protocol
asciichat_error_t	crypto_handshake_client_key_exchange (crypto_handshake_context_t *ctx, acip_transport_t *transport, packet_type_t packet_type, const uint8_t *payload, size_t payload_len)
	Client: Process server's public key and send our public key.
asciichat_error_t	crypto_handshake_client_auth_response (crypto_handshake_context_t *ctx, acip_transport_t *transport, packet_type_t packet_type, const uint8_t *payload, size_t payload_len)
	Client: Process auth challenge and send response.
asciichat_error_t	crypto_handshake_client_complete (crypto_handshake_context_t *ctx, acip_transport_t *transport, packet_type_t packet_type, const uint8_t *payload, size_t payload_len)
	Client: Wait for handshake complete confirmation.

Detailed Description

Client-side handshake functions.

Definition in file include/ascii-chat/crypto/handshake/client.h.

Function Documentation

crypto_handshake_client_auth_response()

asciichat_error_t crypto_handshake_client_auth_response	(	crypto_handshake_context_t *	ctx,
		acip_transport_t *	transport,
		packet_type_t	packet_type,
		const uint8_t *	payload,
		size_t	payload_len )

Client: Process auth challenge and send response.

Parameters

ctx	Handshake context (must be in CRYPTO_HANDSHAKE_KEY_EXCHANGE state)
transport	ACIP transport to send on
packet_type	Packet type received (should be PACKET_TYPE_CRYPTO_AUTH_CHALLENGE or PACKET_TYPE_CRYPTO_HANDSHAKE_COMPLETE)
payload	Received packet payload
payload_len	Length of received payload

Returns

ASCIICHAT_OK on success, error code on failure

Client processes server's AUTH_CHALLENGE packet and sends AUTH_RESPONSE. Generates HMAC bound to shared secret using password or client key.

Note

Packet must be received by ACIP handler before calling this function

State transition: CRYPTO_HANDSHAKE_KEY_EXCHANGE -> CRYPTO_HANDSHAKE_AUTHENTICATING

Definition at line 600 of file lib/crypto/handshake/client.c.

                                                                            {
  ASCII_OTEL_SCOPE(CRYPTO_HANDSHAKE_CLIENT_AUTH_RESPONSE);
  if (!ctx || ctx->state != CRYPTO_HANDSHAKE_KEY_EXCHANGE) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Invalid state: ctx=%p, state=%d", ctx, ctx ? ctx->state : -1);
  }
  if (!transport) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "transport is NULL");
  }
 
  // Note: Packet already received by ACIP handler
  int result;
 
  // If server sent HANDSHAKE_COMPLETE, authentication was skipped (client has
  // no key)
  if (packet_type == PACKET_TYPE_CRYPTO_HANDSHAKE_COMPLETE) {
    ctx->state = CRYPTO_HANDSHAKE_READY;
    ctx->crypto_ctx.handshake_complete = true; // Mark crypto context as ready for rekeying
    log_debug("Crypto handshake completed successfully (no authentication required)");
    return ASCIICHAT_OK;
  }
 
  // If server sent AUTH_FAILED, client is not authorized
  if (packet_type == PACKET_TYPE_CRYPTO_AUTH_FAILED) {
    return SET_ERRNO(ERROR_CRYPTO, "Server rejected authentication - client key not authorized");
  }
 
  // Otherwise, verify packet type is AUTH_CHALLENGE
  if (packet_type != PACKET_TYPE_CRYPTO_AUTH_CHALLENGE) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL,
                     "Expected AUTH_CHALLENGE, HANDSHAKE_COMPLETE, or AUTH_FAILED, "
                     "got packet type %d",
                     packet_type);
  }
 
  // Validate packet size using session parameters
  asciichat_error_t validation_result =
      crypto_handshake_validate_packet_size(ctx, PACKET_TYPE_CRYPTO_AUTH_CHALLENGE, payload_len);
  if (validation_result != ASCIICHAT_OK) {
    return validation_result;
  }
 
  // Parse auth requirement flags
  uint8_t auth_flags = payload[0];
 
  // Copy nonce to local buffer before freeing payload
  // Use auth_challenge_size since that's what the server sent
  // Note: auth_challenge_size is uint8_t (max 255), buffer is 256 bytes, so always sufficient
  uint8_t nonce_buffer[HANDSHAKE_NONCE_PACKET_CAPACITY];
  memcpy(nonce_buffer, payload + 1, ctx->crypto_ctx.auth_challenge_size);
  const uint8_t *nonce = nonce_buffer;
 
  log_debug("Server auth requirements: password=%s, client_key=%s",
            (auth_flags & AUTH_REQUIRE_PASSWORD) ? "required" : "no",
            (auth_flags & AUTH_REQUIRE_CLIENT_KEY) ? "required" : "no");
 
  // Check if we can satisfy the server's authentication requirements
  bool has_password = ctx->crypto_ctx.has_password;
  bool has_client_key = (ctx->client_private_key.type == KEY_TYPE_ED25519);
  bool password_required = (auth_flags & AUTH_REQUIRE_PASSWORD);
  bool client_key_required = (auth_flags & AUTH_REQUIRE_CLIENT_KEY);
 
  // Provide specific error messages based on what's missing
  if (password_required && !has_password) {
    if (client_key_required && !has_client_key) {
      return SET_ERRNO(ERROR_CRYPTO, "Server requires both password and client key authentication. Please "
                                     "provide --password and --key to authenticate");
    }
    // Prompt for password interactively
    if (ctx->defer_password_prompt) {
      ctx->password_failure = AUTH_FAIL_PASSWORD_REQUIRED;
      return deferred_password_error("Server requires a password");
    }
    char prompted_password[PASSWORD_BUFFER_SIZE];
    if (prompt_password("Server password required - please enter password:", prompted_password,
                        sizeof(prompted_password)) != 0) {
      return SET_ERRNO(ERROR_CRYPTO, "Failed to read password");
    }
 
    // Derive password key from prompted password
    log_debug("Deriving key from prompted password");
    crypto_result_t crypto_result = crypto_derive_password_key(&ctx->crypto_ctx, prompted_password);
    sodium_memzero(prompted_password, sizeof(prompted_password));
 
    if (crypto_result != CRYPTO_OK) {
      return SET_ERRNO(ERROR_CRYPTO, "Failed to derive password key: %s", crypto_result_to_string(crypto_result));
    }
 
    // Mark that password auth is now available
    ctx->crypto_ctx.has_password = true;
    has_password = true; // Update flag for logic below
  }
 
  // Authentication response priority:
  // NOTE: Identity verification happens during KEY_EXCHANGE phase, not
  // AUTH_RESPONSE!
  // 1. If server requires password → MUST send HMAC (hmac_size bytes), error if no password
  // 2. Else if server requires identity (whitelist) → MUST send Ed25519 signature (signature_size bytes), error if no
  // key
  // 3. Else if client has password → send HMAC (optional password auth)
  // 4. Else if client has SSH key → send Ed25519 signature (optional identity
  // proof)
  // 5. Else → no authentication available
 
  // Clean up payload before any early returns
  if (password_required) {
    // Server requires password - HIGHEST PRIORITY
    // (Identity was already verified in KEY_EXCHANGE phase if whitelist is
    // enabled)
    if (!has_password) {
      return SET_ERRNO(ERROR_CRYPTO, "Server requires password authentication\n"
                                     "Please provide --password for this server");
    }
 
    result = send_password_auth_response(ctx, transport, nonce, "required password");
    if (result != ASCIICHAT_OK) {
      SET_ERRNO(ERROR_NETWORK, "Failed to send password auth response");
      return result;
    }
  } else if (client_key_required) {
    // Server requires client key (whitelist) - SECOND PRIORITY
    if (!has_client_key) {
      return SET_ERRNO(ERROR_CRYPTO, "Server requires client key authentication (whitelist)\n"
                                     "Please provide --key with your authorized Ed25519 key");
    }
 
    result = send_key_auth_response(ctx, transport, nonce, "required client key");
    if (result != ASCIICHAT_OK) {
      SET_ERRNO(ERROR_NETWORK, "Failed to send key auth response");
      return result;
    }
  } else if (has_password) {
    // No server requirements, but client has password → send HMAC + client
    // nonce (optional)
    result = send_password_auth_response(ctx, transport, nonce, "optional password");
    if (result != ASCIICHAT_OK) {
      SET_ERRNO(ERROR_NETWORK, "Failed to send password auth response");
      return result;
    }
  } else if (has_client_key) {
    // No server requirements, but client has SSH key → send Ed25519 signature +
    // client nonce (optional)
    result = send_key_auth_response(ctx, transport, nonce, "optional identity");
    if (result != ASCIICHAT_OK) {
      SET_ERRNO(ERROR_NETWORK, "Failed to send key auth response");
      return result;
    }
  } else {
    // No authentication method available
    // Continue without authentication (server will decide if this is
    // acceptable)
    log_debug("No authentication credentials provided - continuing without "
              "authentication");
  }
 
  ctx->state = CRYPTO_HANDSHAKE_AUTHENTICATING;
 
  return ASCIICHAT_OK;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, crypto_context_t::auth_challenge_size, AUTH_FAIL_PASSWORD_REQUIRED, AUTH_REQUIRE_CLIENT_KEY, AUTH_REQUIRE_PASSWORD, crypto_handshake_context_t::client_private_key, crypto_handshake_context_t::crypto_ctx, crypto_derive_password_key(), CRYPTO_HANDSHAKE_AUTHENTICATING, CRYPTO_HANDSHAKE_KEY_EXCHANGE, CRYPTO_HANDSHAKE_READY, crypto_handshake_validate_packet_size(), CRYPTO_OK, crypto_result_to_string(), crypto_handshake_context_t::defer_password_prompt, ERROR_CRYPTO, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_NETWORK, ERROR_NETWORK_PROTOCOL, crypto_context_t::handshake_complete, HANDSHAKE_NONCE_PACKET_CAPACITY, crypto_context_t::has_password, KEY_TYPE_ED25519, log_debug, PACKET_TYPE_CRYPTO_AUTH_CHALLENGE, PACKET_TYPE_CRYPTO_AUTH_FAILED, PACKET_TYPE_CRYPTO_HANDSHAKE_COMPLETE, PASSWORD_BUFFER_SIZE, crypto_handshake_context_t::password_failure, prompt_password(), SET_ERRNO, crypto_handshake_context_t::state, and private_key_t::type.

Referenced by acds_handshake_receive(), acip_security_receive(), and client_handle_auth_challenge().

crypto_handshake_client_complete()

asciichat_error_t crypto_handshake_client_complete	(	crypto_handshake_context_t *	ctx,
		acip_transport_t *	transport,
		packet_type_t	packet_type,
		const uint8_t *	payload,
		size_t	payload_len )

Client: Wait for handshake complete confirmation.

Parameters

ctx	Handshake context (must be in CRYPTO_HANDSHAKE_AUTHENTICATING state)
transport	ACIP transport (unused, for consistency)
packet_type	Packet type received (should be PACKET_TYPE_CRYPTO_SERVER_AUTH_RESP or PACKET_TYPE_CRYPTO_AUTH_FAILED)
payload	Received packet payload
payload_len	Length of received payload

Returns

ASCIICHAT_OK on success, error code on failure

Client processes server's SERVER_AUTH_RESP or AUTH_FAILED packet. After receiving, handshake is complete and encryption is ready.

Note

Packet must be received by ACIP handler before calling this function

State transition: CRYPTO_HANDSHAKE_AUTHENTICATING -> CRYPTO_HANDSHAKE_READY

Definition at line 761 of file lib/crypto/handshake/client.c.

                                                                       {
  ASCII_OTEL_SCOPE(CRYPTO_HANDSHAKE_CLIENT_COMPLETE);
  // Accept both KEY_EXCHANGE and AUTHENTICATING states for simple mode compatibility
  // In simple mode, server skips AUTH_CHALLENGE and sends HANDSHAKE_COMPLETE directly
  if (!ctx || (ctx->state != CRYPTO_HANDSHAKE_KEY_EXCHANGE && ctx->state != CRYPTO_HANDSHAKE_AUTHENTICATING)) {
    SET_ERRNO(ERROR_INVALID_STATE, "Invalid state: ctx=%p, state=%d", ctx, ctx ? ctx->state : -1);
    return ERROR_INVALID_STATE;
  }
  if (!transport) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "transport is NULL");
  }
 
  // Note: Packet already received by ACIP handler
  (void)transport; // Unused parameter (this function only receives, doesn't send)
 
  // Check packet type
  if (packet_type == PACKET_TYPE_CRYPTO_AUTH_FAILED) {
    // Parse the auth failure packet to get specific reasons
    if (payload_len >= sizeof(auth_failure_packet_t)) {
      auth_failure_packet_t *failure = (auth_failure_packet_t *)payload;
      const uint8_t password_flags = AUTH_FAIL_PASSWORD_REQUIRED | AUTH_FAIL_PASSWORD_INCORRECT;
      if (ctx->defer_password_prompt && failure->reason_flags && !(failure->reason_flags & ~password_flags)) {
        ctx->password_failure = failure->reason_flags;
        return deferred_password_error("Server rejected password");
      }
      NOTICE(DANGER, "AUTHENTICATION REJECTED", "%s%s%s%s%sConnection rejected.",
             failure->reason_flags & AUTH_FAIL_PASSWORD_INCORRECT ? "Incorrect password.\n" : "",
             failure->reason_flags & AUTH_FAIL_PASSWORD_REQUIRED ? "Password required: use --password.\n" : "",
             failure->reason_flags & AUTH_FAIL_CLIENT_KEY_REQUIRED ? "Client identity required: use --key.\n" : "",
             failure->reason_flags & AUTH_FAIL_CLIENT_KEY_REJECTED ? "Client key is not authorized by the server.\n"
                                                                   : "",
             failure->reason_flags & AUTH_FAIL_SIGNATURE_INVALID ? "Client signature verification failed.\n" : "");
      SET_ERRNO(ERROR_CRYPTO_AUTH, "Server rejected authentication:");
 
      if (failure->reason_flags & AUTH_FAIL_PASSWORD_INCORRECT) {
        SET_ERRNO(ERROR_CRYPTO_AUTH, "  - Incorrect password");
      }
      if (failure->reason_flags & AUTH_FAIL_PASSWORD_REQUIRED) {
        SET_ERRNO(ERROR_CRYPTO_AUTH, "  - Server requires a password (use --password)");
      }
      if (failure->reason_flags & AUTH_FAIL_CLIENT_KEY_REQUIRED) {
        SET_ERRNO(ERROR_CRYPTO_AUTH, "  - Server requires a whitelisted client key (use --key "
                                     "with your SSH key)");
      }
      if (failure->reason_flags & AUTH_FAIL_CLIENT_KEY_REJECTED) {
        SET_ERRNO(ERROR_CRYPTO_AUTH, "  - Your client key is not in the server's whitelist");
      }
      if (failure->reason_flags & AUTH_FAIL_SIGNATURE_INVALID) {
        SET_ERRNO(ERROR_CRYPTO_AUTH, "  - Client signature verification failed");
      }
 
      // Provide helpful guidance
      if (failure->reason_flags & (AUTH_FAIL_PASSWORD_INCORRECT | AUTH_FAIL_CLIENT_KEY_REQUIRED)) {
        if ((failure->reason_flags & AUTH_FAIL_PASSWORD_INCORRECT) &&
            (failure->reason_flags & AUTH_FAIL_CLIENT_KEY_REQUIRED)) {
          SET_ERRNO(ERROR_CRYPTO_AUTH, "Hint: Server requires BOTH correct password AND "
                                       "whitelisted key");
        } else if (failure->reason_flags & AUTH_FAIL_PASSWORD_INCORRECT) {
          SET_ERRNO(ERROR_CRYPTO_AUTH, "Hint: Check your password and try again");
        } else if (failure->reason_flags & AUTH_FAIL_CLIENT_KEY_REQUIRED) {
          SET_ERRNO(ERROR_CRYPTO_AUTH, "Hint: Provide your SSH key with --key ~/.ssh/id_ed25519");
        } else if (failure->reason_flags & AUTH_FAIL_CLIENT_KEY_REJECTED) {
          SET_ERRNO(ERROR_CRYPTO_AUTH, "Hint: Your key needs to be added to the server's whitelist");
        }
      }
    } else {
      NOTICE(DANGER, "AUTHENTICATION REJECTED",
             "Server rejected authentication (no details provided).\nConnection rejected.");
      SET_ERRNO(ERROR_CRYPTO_AUTH, "Server rejected authentication (no details provided)");
    }
    return SET_ERRNO(ERROR_CRYPTO_AUTH,
                     "Server authentication failed - incorrect HMAC"); // Special code for
                                                                       // auth failure - do
                                                                       // not retry
  }
 
  // Handle no-auth flow: server sends HANDSHAKE_COMPLETE directly
  if (packet_type == PACKET_TYPE_CRYPTO_HANDSHAKE_COMPLETE) {
    ctx->state = CRYPTO_HANDSHAKE_READY;
    ctx->crypto_ctx.handshake_complete = true;
    log_info("Handshake complete (no authentication required)");
    return ASCIICHAT_OK;
  }
 
  // Handle with-auth flow: server sends SERVER_AUTH_RESP after authentication
  if (packet_type != PACKET_TYPE_CRYPTO_SERVER_AUTH_RESP) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL,
                     "Expected HANDSHAKE_COMPLETE, SERVER_AUTH_RESPONSE, or AUTH_FAILED, got packet type %d",
                     packet_type);
  }
 
  // Verify server's HMAC for mutual authentication
  // Use ctx->crypto_ctx.hmac_size (negotiated during handshake) rather than SERVER_AUTH_RESPONSE_SIZE constant
  if (payload_len != ctx->crypto_ctx.hmac_size) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Invalid SERVER_AUTH_RESPONSE size: %zu bytes (expected %u)", payload_len,
                     ctx->crypto_ctx.hmac_size);
  }
 
  // Verify server's HMAC (binds to DH shared_secret to prevent MITM)
  if (!crypto_verify_auth_response(&ctx->crypto_ctx, ctx->client_challenge_nonce, payload)) {
    NOTICE(
        DANGER, "SERVER AUTHENTICATION FAILED",
        "The server returned an incorrect HMAC. This may indicate a man-in-the-middle attack.\nConnection rejected.");
    return SET_ERRNO(ERROR_CRYPTO_AUTH,
                     "Server authentication failed - incorrect HMAC"); // Authentication
                                                                       // failure - do not
                                                                       // retry
  }
  ctx->state = CRYPTO_HANDSHAKE_READY;
  ctx->crypto_ctx.handshake_complete = true;
  log_info("Server authentication successful - mutual authentication complete");
 
  return ASCIICHAT_OK;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, AUTH_FAIL_CLIENT_KEY_REJECTED, AUTH_FAIL_CLIENT_KEY_REQUIRED, AUTH_FAIL_PASSWORD_INCORRECT, AUTH_FAIL_PASSWORD_REQUIRED, AUTH_FAIL_SIGNATURE_INVALID, crypto_handshake_context_t::client_challenge_nonce, crypto_handshake_context_t::crypto_ctx, CRYPTO_HANDSHAKE_AUTHENTICATING, CRYPTO_HANDSHAKE_KEY_EXCHANGE, CRYPTO_HANDSHAKE_READY, crypto_verify_auth_response(), crypto_handshake_context_t::defer_password_prompt, ERROR_CRYPTO_AUTH, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_NETWORK_PROTOCOL, crypto_context_t::handshake_complete, crypto_context_t::hmac_size, log_info, NOTICE, PACKET_TYPE_CRYPTO_AUTH_FAILED, PACKET_TYPE_CRYPTO_HANDSHAKE_COMPLETE, PACKET_TYPE_CRYPTO_SERVER_AUTH_RESP, crypto_handshake_context_t::password_failure, auth_failure_packet_t::reason_flags, SET_ERRNO, and crypto_handshake_context_t::state.

Referenced by acds_handshake_receive(), acip_security_receive(), and client_handle_handshake_complete().

crypto_handshake_client_key_exchange()

asciichat_error_t crypto_handshake_client_key_exchange	(	crypto_handshake_context_t *	ctx,
		acip_transport_t *	transport,
		packet_type_t	packet_type,
		const uint8_t *	payload,
		size_t	payload_len )

Client: Process server's public key and send our public key.

Parameters

ctx	Handshake context (must be in CRYPTO_HANDSHAKE_INIT state)
transport	ACIP transport to send on
packet_type	Packet type received (should be PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT)
payload	Received packet payload
payload_len	Length of received payload

Returns

ASCIICHAT_OK on success, error code on failure

Client processes server's KEY_EXCHANGE_INIT packet and responds with KEY_EXCHANGE_RESP. Supports both simple and authenticated formats. Verifies server signature if present.

Note

Packet must be received by ACIP handler before calling this function

State transition: CRYPTO_HANDSHAKE_INIT -> CRYPTO_HANDSHAKE_KEY_EXCHANGE

Definition at line 47 of file lib/crypto/handshake/client.c.

                                                                           {
  ASCII_OTEL_SCOPE(CRYPTO_HANDSHAKE_CLIENT_KEY_EXCHANGE);
  if (!ctx || ctx->state != CRYPTO_HANDSHAKE_INIT) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Invalid state: ctx=%p, state=%d", (void *)ctx, ctx ? (int)ctx->state : -1);
  }
  if (!transport) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "transport is NULL");
  }
 
  // Note: Packet already received by ACIP handler
  int result;
 
  // Verify packet type
  if (packet_type != PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Expected KEY_EXCHANGE_INIT, got packet type %d", packet_type);
  }
 
  log_debug("CLIENT_KEY_EXCHANGE: Received packet with payload_len=%zu, kex_size=%u, auth_size=%u, sig_size=%u",
            payload_len, ctx->crypto_ctx.public_key_size, ctx->crypto_ctx.auth_public_key_size,
            ctx->crypto_ctx.signature_size);
 
  // Check payload size - only authenticated format supported
  // Authenticated: public_key_size + auth_public_key_size + signature_size bytes
  size_t expected_auth_size =
      ctx->crypto_ctx.public_key_size + ctx->crypto_ctx.auth_public_key_size + ctx->crypto_ctx.signature_size;
 
  // Use the crypto context's public key size to ensure compatibility.
  size_t key_size = sizeof(ctx->crypto_ctx.public_key);
  SAFE_MALLOC_DEFER_FREE(server_ephemeral_key, key_size, uint8_t *);
  if (!server_ephemeral_key) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate memory for server ephemeral key");
  }
  SAFE_MALLOC_DEFER_FREE(server_identity_key, ctx->crypto_ctx.auth_public_key_size, uint8_t *);
  SAFE_MALLOC_DEFER_FREE(server_signature, ctx->crypto_ctx.signature_size, uint8_t *);
 
  if (!server_identity_key || !server_signature) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate memory for server identity key or signature");
  }
 
  // Validate packet size using session parameters
  asciichat_error_t validation_result =
      crypto_handshake_validate_packet_size(ctx, PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT, payload_len);
  if (validation_result != ASCIICHAT_OK) {
    return validation_result;
  }
 
  // Check if server is using authenticated format (includes signature)
  // Must have signature_size > 0 to distinguish from simple ephemeral-only format
  // This covers both cases:
  // 1. With identity key: ephemeral + identity + signature
  // 2. Without identity key but with signature: ephemeral + 0 + signature
  if (ctx->crypto_ctx.signature_size > 0 && payload_len == expected_auth_size) {
    // Authenticated format:
    // [ephemeral:public_key_size][identity:auth_public_key_size][signature:signature_size]
    log_debug("Received authenticated KEY_EXCHANGE_INIT (%zu bytes)", expected_auth_size);
    memcpy(server_ephemeral_key, payload, ctx->crypto_ctx.public_key_size);
    memcpy(server_identity_key, payload + ctx->crypto_ctx.public_key_size, ctx->crypto_ctx.auth_public_key_size);
    memcpy(server_signature, payload + ctx->crypto_ctx.public_key_size + ctx->crypto_ctx.auth_public_key_size,
           ctx->crypto_ctx.signature_size);
 
    // Server is using client authentication
    ctx->server_uses_client_auth = true;
 
    // DEBUG: Print identity key received
    char hex_id[HEX_STRING_SIZE_32];
    for (int i = 0; i < ED25519_PUBLIC_KEY_SIZE; i++) {
      safe_snprintf(hex_id + i * 2, 3, "%02x", server_identity_key[i]);
    }
    hex_id[HEX_STRING_SIZE_32 - 1] = '\0';
    log_debug("Received identity key: %s", hex_id);
 
    // DEBUG: Print ephemeral key and signature
    char hex_eph[HEX_STRING_SIZE_32];
    for (int i = 0; i < ED25519_PUBLIC_KEY_SIZE; i++) {
      safe_snprintf(hex_eph + i * 2, 3, "%02x", server_ephemeral_key[i]);
    }
    hex_eph[HEX_STRING_SIZE_32 - 1] = '\0';
    log_debug("Received ephemeral key: %s", hex_eph);
 
    char hex_sig[HEX_STRING_SIZE_64];
    for (int i = 0; i < ED25519_SIGNATURE_SIZE; i++) {
      safe_snprintf(hex_sig + i * 2, 3, "%02x", server_signature[i]);
    }
    hex_sig[HEX_STRING_SIZE_64 - 1] = '\0';
    log_debug("Received signature: %s", hex_sig);
 
    // Verify signature: server identity signed the ephemeral key
    log_debug("Verifying server's signature over ephemeral key (already logged above)");
 
    // If client didn't specify --server-key, skip signature verification
    // (client doesn't care about server identity verification)
    if (!ctx->verify_server_key) {
      log_info("Skipping server signature verification (no --server-key specified)");
      NOTICE(DANGER, "UNVERIFIED SERVER IDENTITY",
             "Connection is encrypted but server identity is NOT verified (vulnerable to MITM)");
    } else {
      // Extract GPG key ID from expected_server_key if it's a GPG key (gpg:KEYID format)
      const char *gpg_key_id = NULL;
      if (ctx->expected_server_key[0] != '\0' && strncmp(ctx->expected_server_key, "gpg:", 4) == 0) {
        const char *key_id_start = ctx->expected_server_key + 4;
        size_t key_id_len = strlen(key_id_start);
        // Accept 8, 16, or 40 character GPG key IDs (short, long, or full fingerprint)
        if (key_id_len == 8 || key_id_len == 16 || key_id_len == 40) {
          gpg_key_id = key_id_start;
          log_debug("Using GPG key ID from --server-key for verification: %s", gpg_key_id);
        }
      }
 
      if (ed25519_verify_signature(server_identity_key, server_ephemeral_key, ctx->crypto_ctx.public_key_size,
                                   server_signature, gpg_key_id) != 0) {
        NOTICE(DANGER, "SERVER SIGNATURE INVALID",
               "The server identity signature could not be verified.\n"
               "Possible man-in-the-middle attack. Connection rejected.");
        return SET_ERRNO(ERROR_CRYPTO, "Server signature verification FAILED - rejecting connection. "
                                       "This indicates: Server's identity key does not "
                                       "match its ephemeral key, Potential man-in-the-middle attack, "
                                       "Corrupted or malicious server");
      }
      log_debug("Server signature verified successfully");
    }
 
    // Verify server identity against a browser-provided raw key before falling
    // back to the native file, URL, and key-list parser.
    if (ctx->verify_server_key && ctx->expected_server_key_bytes_set) {
      if (sodium_memcmp(server_identity_key, ctx->expected_server_key_bytes, ED25519_PUBLIC_KEY_SIZE) != 0) {
        NOTICE(DANGER, "SERVER IDENTITY KEY MISMATCH",
               "The server key does not match the browser verification key.\nConnection rejected.");
        return SET_ERRNO(ERROR_CRYPTO_VERIFICATION,
                         "Server identity key does not match the active browser verification key");
      }
      log_info("Server identity key verified against active browser key");
    } else if (ctx->verify_server_key && strlen(ctx->expected_server_key) > 0) {
      // Parse ALL expected server keys (github:/gitlab: may have multiple keys)
      public_key_t expected_keys[MAX_CLIENTS];
      size_t num_expected_keys = 0;
      if (parse_public_keys(ctx->expected_server_key, expected_keys, &num_expected_keys, MAX_CLIENTS) != 0 ||
          num_expected_keys == 0) {
        return SET_ERRNO(ERROR_CONFIG,
                         "Failed to parse expected server key: %s. Check that "
                         "--server-key value is valid (ssh-ed25519 "
                         "format, github:username, or hex)",
                         ctx->expected_server_key);
      }
 
      // Compare server's IDENTITY key against ALL expected keys (match any one)
      // This supports users with multiple SSH keys (e.g., different machines)
      bool key_matched = false;
      for (size_t i = 0; i < num_expected_keys; i++) {
        if (sodium_memcmp(server_identity_key, expected_keys[i].key, ED25519_PUBLIC_KEY_SIZE) == 0) {
          key_matched = true;
          log_debug("Server identity key matched expected key %zu/%zu", i + 1, num_expected_keys);
          break;
        }
      }
 
      if (!key_matched) {
        NOTICE(DANGER, "SERVER IDENTITY KEY MISMATCH",
               "The server key does not match --server-key: %s.\n"
               "Possible man-in-the-middle attack. Do not connect until the server identity is verified.",
               ctx->expected_server_key);
        return SET_ERRNO(ERROR_CRYPTO,
                         "Server identity key mismatch - potential MITM attack! "
                         "Expected key(s) from: %s (checked %zu keys), Server presented a different key "
                         "than specified with --server-key, DO NOT CONNECT to this "
                         "server - likely man-in-the-middle attack!",
                         ctx->expected_server_key, num_expected_keys);
      }
      log_info("Server identity key verified against --server-key (%zu key(s) checked)", num_expected_keys);
    }
 
    // Note: Server IP resolution now handled by caller (TCP transport layer)
    // For WebSocket/WebRTC transports, server_ip should be set by the transport
    // before handshake begins. TCP clients will use the legacy wrapper which
    // handles this.
    if (ctx->server_ip[0] == '\0') {
      log_debug("Server IP not set - skipping known_hosts verification (non-TCP transport)");
    } else {
      log_debug("Server IP already set: %s", ctx->server_ip);
    }
 
    // Check known_hosts for this server (if we have server IP and port)
    // Check if known_hosts verification should be skipped
    bool skip_known_hosts = false;
    const char *env_skip = platform_getenv("ASCII_CHAT_INSECURE_NO_HOST_IDENTITY_CHECK");
    if (env_skip && strcmp(env_skip, STR_ONE) == 0) {
      log_warn(
          "Skipping known_hosts checking for authenticated connection (ASCII_CHAT_INSECURE_NO_HOST_IDENTITY_CHECK=1)");
      skip_known_hosts = true;
    }
#ifndef NDEBUG
    // In debug builds, also skip for Claude Code (LLM automation can't do interactive prompts)
    else if (platform_getenv("CLAUDECODE")) {
      log_warn("Skipping known_hosts checking (CLAUDECODE set in debug build)");
      skip_known_hosts = true;
    }
#endif
 
    if (!ctx->addressless_transport && !skip_known_hosts && ctx->server_ip[0] != '\0' && ctx->server_port > 0) {
      uint8_t stored_key[ED25519_PUBLIC_KEY_SIZE];
      bool has_stored_key = false;
      asciichat_error_t known_host_result =
          check_known_host_with_key(ctx->server_ip, ctx->server_port, server_identity_key, stored_key, &has_stored_key);
      if (known_host_result == ERROR_CRYPTO_VERIFICATION) {
        // Key mismatch - MITM attack detected! Prompt user for confirmation
        log_error("SECURITY: Server key does NOT match known_hosts entry!\n"
                  "This indicates a possible man-in-the-middle attack!");
        if (!display_mitm_warning(ctx->server_ip, ctx->server_port, has_stored_key ? stored_key : NULL,
                                  server_identity_key)) {
          // User declined to continue - ABORT connection for security
 
          return SET_ERRNO(ERROR_CRYPTO_VERIFICATION,
                           "SECURITY: Connection aborted - server key mismatch (possible MITM attack)");
        }
        // User accepted the risk - continue with connection
        NOTICE(DANGER, "HOST KEY CHANGE ACCEPTED",
               "SECURITY WARNING: User accepted MITM risk - continuing with connection");
      } else if (known_host_result == ASCIICHAT_OK) {
        // Unknown host (first connection) - prompt user to verify fingerprint
        if (!prompt_unknown_host(ctx->server_ip, ctx->server_port, server_identity_key)) {
          // User declined to add host - ABORT connection
 
          return SET_ERRNO(ERROR_CRYPTO, "User declined to verify unknown host");
        }
 
        // User accepted - add to known_hosts
        if (add_known_host(ctx->server_ip, ctx->server_port, server_identity_key) != ASCIICHAT_OK) {
          return SET_ERRNO(ERROR_CONFIG,
                           "CRITICAL SECURITY ERROR: Failed to create known_hosts "
                           "file! This is a security vulnerability - the "
                           "program cannot track known hosts. Please check file "
                           "permissions and ensure the program can write to: %s",
                           get_known_hosts_path());
        }
        log_debug("Server host added to known_hosts successfully");
      } else if (known_host_result == 1) {
        // Key matches - connection is secure!
        log_info("Server host key verified from known_hosts - connection secure");
      } else {
        // Unexpected error code from check_known_host
 
        return SET_ERRNO(known_host_result, "SECURITY: known_hosts verification failed with error code %d",
                         known_host_result);
      }
    }
    public_key_t identity = {.type = KEY_TYPE_ED25519};
    memcpy(identity.key, server_identity_key, sizeof(identity.key));
    key_identity_announce(
        ctx->verify_server_key ? "VERIFIED SERVER PUBLIC IDENTITY" : "UNVERIFIED SERVER PUBLIC IDENTITY", &identity);
  } else if (payload_len == ctx->crypto_ctx.public_key_size) {
    if (ctx->verify_server_key) {
      return SET_ERRNO(ERROR_CRYPTO_AUTH, "Server omitted the required identity key");
    }
    // Simple format: just ephemeral key (no identity key)
    log_debug("Received simple KEY_EXCHANGE_INIT (%zu bytes) - server has no "
              "identity key",
              payload_len);
    memcpy(server_ephemeral_key, payload, ctx->crypto_ctx.public_key_size);
 
    // Clear identity key and signature for simple format
    memset(server_identity_key, 0, ctx->crypto_ctx.auth_public_key_size);
    memset(server_signature, 0, ctx->crypto_ctx.signature_size);
 
    // Server is not using client authentication in simple mode
    ctx->server_uses_client_auth = false;
 
    log_debug("Received ephemeral key (simple format)");
 
    if (!ctx->addressless_transport) {
      // SECURITY: For servers without identity keys, we implement a different security model:
      // 1. Verify IP address matches known_hosts entry
      // 2. Always require user confirmation (no silent connections)
      // 3. Store server fingerprint for future verification
 
      if (ctx->server_ip[0] == '\0' || ctx->server_port <= 0) {
        return SET_ERRNO(ERROR_CRYPTO, "Server IP or port not set, cannot check known_hosts");
      }
 
      // Check if this server was previously connected to (IP verification)
      bool skip_known_hosts = false;
      asciichat_error_t known_host_result = ASCIICHAT_OK;
      const char *env_skip_known_hosts_checking = platform_getenv("ASCII_CHAT_INSECURE_NO_HOST_IDENTITY_CHECK");
      if (env_skip_known_hosts_checking && strcmp(env_skip_known_hosts_checking, STR_ONE) == 0) {
        log_warn("Skipping known_hosts checking. This is a security vulnerability.");
        skip_known_hosts = true;
      }
#ifndef NDEBUG
      // In debug builds, also skip for Claude Code (LLM automation can't do interactive prompts)
      else if (platform_getenv("CLAUDECODE")) {
        log_warn("Skipping known_hosts checking (CLAUDECODE set in debug build).");
        skip_known_hosts = true;
      }
#endif
      else {
        known_host_result = check_known_host_no_identity(ctx->server_ip, ctx->server_port);
      }
 
      if (skip_known_hosts || known_host_result == 1) {
        // Server IP is known and verified - allow connection without warnings
        log_info("SECURITY: Server IP %s:%u is known (no-identity entry found) - connection verified", ctx->server_ip,
                 ctx->server_port);
      } else if (known_host_result == ASCIICHAT_OK) {
        // Server IP is unknown - require user confirmation
        NOTICE(DANGER, "UNVERIFIED SERVER IDENTITY",
               "SECURITY: Unknown server IP %s:%u with no identity key\n"
               "This connection is vulnerable to man-in-the-middle attacks\n"
               "Anyone can intercept your connection and read your data",
               ctx->server_ip, ctx->server_port);
 
        if (!prompt_unknown_host_no_identity(ctx->server_ip, ctx->server_port)) {
          return SET_ERRNO(ERROR_CRYPTO, "User declined to connect to unknown server without identity key");
        }
 
        // User accepted - add to known_hosts as no-identity entry
        // For servers without identity keys, pass zero key to indicate no-identity
        uint8_t zero_key[ZERO_KEY_SIZE] = {0};
        if (add_known_host(ctx->server_ip, ctx->server_port, zero_key) != ASCIICHAT_OK) {
          return SET_ERRNO(ERROR_CONFIG,
                           "CRITICAL SECURITY ERROR: Failed to create known_hosts "
                           "file! This is a security vulnerability - the "
                           "program cannot track known hosts. Please check file "
                           "permissions and ensure the program can write to: %s",
                           get_known_hosts_path());
        }
        log_debug("Server host added to known_hosts successfully");
      } else if (known_host_result == ERROR_CRYPTO_VERIFICATION) {
        // Server previously had identity key but now has none - potential security issue
        NOTICE(DANGER, "SERVER IDENTITY REMOVED",
               "SECURITY: Server previously had identity key but now has none - potential security issue");
 
        return SET_ERRNO(ERROR_CRYPTO_VERIFICATION, "Server key configuration changed - potential security issue");
      } else {
        // Other error checking known_hosts (e.g., ERROR_INVALID_PARAM)
 
        return SET_ERRNO(ERROR_CRYPTO, "Failed to verify server IP address");
      }
    }
  } else {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL,
                     "Invalid KEY_EXCHANGE_INIT size: %zu bytes (expected %zu or "
                     "%zu). This indicates: Protocol violation "
                     "or incompatible server version, Potential man-in-the-middle "
                     "attack, Network corruption",
                     payload_len, expected_auth_size, ctx->crypto_ctx.public_key_size);
    // retry
  }
 
  // Set peer's public key (EPHEMERAL X25519) - this also derives the shared secret
  crypto_result_t crypto_result = crypto_set_peer_public_key(&ctx->crypto_ctx, server_ephemeral_key);
  if (crypto_result != CRYPTO_OK) {
    return SET_ERRNO(ERROR_CRYPTO, "Failed to set peer public key and derive shared secret: %s",
                     crypto_result_to_string(crypto_result));
  }
 
  // Determine if client has an identity key
  bool client_has_identity_key = (ctx->client_private_key.type == KEY_TYPE_ED25519);
 
  // Send authenticated response if server has identity key (auth_public_key_size > 0)
  // OR if server requires client authentication (require_client_auth)
  // Note: server_uses_client_auth is set when server has identity key, but we should
  // send authenticated response when server has identity key regardless of client auth requirement
  bool server_has_identity = (ctx->crypto_ctx.auth_public_key_size > 0 && ctx->crypto_ctx.signature_size > 0);
  bool server_requires_auth = server_has_identity || ctx->require_client_auth;
 
  if (server_requires_auth || client_has_identity_key) {
    // Send authenticated packet:
    // [ephemeral:kex_size][identity:auth_size][signature:sig_size][gpg_key_id_len:1][gpg_key_id:0-16]
    // Use Ed25519 sizes since client has Ed25519 key
    size_t ed25519_pubkey_size = ED25519_PUBLIC_KEY_SIZE; // Ed25519 public key is always 32 bytes
    size_t ed25519_sig_size = ED25519_SIGNATURE_SIZE;     // Ed25519 signature is always 64 bytes
    size_t response_size = ctx->crypto_ctx.public_key_size + ed25519_pubkey_size + ed25519_sig_size;
 
    // Check if client has a GPG key ID to send
    uint8_t gpg_key_id_len = 0;
    if (ctx->client_gpg_key_id[0] != '\0') {
      gpg_key_id_len = (uint8_t)strlen(ctx->client_gpg_key_id);
      if (gpg_key_id_len > 40) {
        gpg_key_id_len = 40; // Truncate to max length (full fingerprint)
      }
      response_size += 1 + gpg_key_id_len; // 1 byte for length + key ID
    } else {
      response_size += 1; // Just the length byte (0)
    }
 
    SAFE_MALLOC_DEFER_FREE(key_response, response_size, uint8_t *);
    defer(sodium_memzero(key_response, response_size));
    size_t offset = 0;
 
    // Copy ephemeral key
    memcpy(key_response + offset, ctx->crypto_ctx.public_key,
           ctx->crypto_ctx.public_key_size); // X25519 ephemeral for encryption
    offset += ctx->crypto_ctx.public_key_size;
 
    if (client_has_identity_key) {
      // Client has identity key - send it with signature
      memcpy(key_response + offset, ctx->client_private_key.public_key, ed25519_pubkey_size); // Ed25519 identity
      offset += ed25519_pubkey_size;
 
      // Sign ephemeral key with client identity key
      if (ed25519_sign_message(&ctx->client_private_key, ctx->crypto_ctx.public_key, ctx->crypto_ctx.public_key_size,
                               key_response + offset) != 0) {
        return SET_ERRNO(ERROR_CRYPTO, "Failed to sign client ephemeral key");
      }
      offset += ed25519_sig_size;
    } else {
      // Client has no identity key - send null identity and null signature
      memset(key_response + offset, 0, ed25519_pubkey_size); // Null identity
      offset += ed25519_pubkey_size;
      memset(key_response + offset, 0, ed25519_sig_size); // Null signature
      offset += ed25519_sig_size;
    }
 
    // Append GPG key ID length
    key_response[offset] = gpg_key_id_len;
    offset += 1;
 
    // Append GPG key ID if present
    if (gpg_key_id_len > 0) {
      memcpy(key_response + offset, ctx->client_gpg_key_id, gpg_key_id_len);
      offset += gpg_key_id_len;
      log_debug("Including client GPG key ID in KEY_EXCHANGE_RESPONSE: %.*s", gpg_key_id_len, ctx->client_gpg_key_id);
    }
 
    result = packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_KEY_EXCHANGE_RESP, key_response, response_size, 0);
    if (result != 0) {
      return SET_ERRNO(ERROR_NETWORK, "Failed to send KEY_EXCHANGE_RESPONSE packet");
    }
 
  } else {
    // Send X25519 encryption key only to server (no identity key)
    // Format: [X25519 pubkey (kex_size)] = kex_size bytes total
    result = packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_KEY_EXCHANGE_RESP, ctx->crypto_ctx.public_key,
                                       ctx->crypto_ctx.public_key_size, 0);
    if (result != 0) {
      return SET_ERRNO(ERROR_NETWORK, "Failed to send KEY_EXCHANGE_RESPONSE packet");
    }
  }
 
  ctx->state = CRYPTO_HANDSHAKE_KEY_EXCHANGE;
 
  return ASCIICHAT_OK;
}

References add_known_host(), crypto_handshake_context_t::addressless_transport, ASCII_OTEL_SCOPE, ASCIICHAT_OK, crypto_context_t::auth_public_key_size, check_known_host_no_identity(), check_known_host_with_key(), crypto_handshake_context_t::client_gpg_key_id, crypto_handshake_context_t::client_private_key, crypto_handshake_context_t::crypto_ctx, CRYPTO_HANDSHAKE_INIT, CRYPTO_HANDSHAKE_KEY_EXCHANGE, crypto_handshake_validate_packet_size(), CRYPTO_OK, crypto_result_to_string(), crypto_set_peer_public_key(), display_mitm_warning(), ED25519_PUBLIC_KEY_SIZE, ed25519_sign_message(), ED25519_SIGNATURE_SIZE, ed25519_verify_signature(), ERROR_CONFIG, ERROR_CRYPTO, ERROR_CRYPTO_AUTH, ERROR_CRYPTO_VERIFICATION, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, ERROR_NETWORK, ERROR_NETWORK_PROTOCOL, crypto_handshake_context_t::expected_server_key, crypto_handshake_context_t::expected_server_key_bytes, crypto_handshake_context_t::expected_server_key_bytes_set, get_known_hosts_path(), HEX_STRING_SIZE_32, HEX_STRING_SIZE_64, public_key_t::key, key_identity_announce(), KEY_TYPE_ED25519, log_debug, log_error, log_info, log_warn, MAX_CLIENTS, NOTICE, packet_send_via_transport(), PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT, PACKET_TYPE_CRYPTO_KEY_EXCHANGE_RESP, parse_public_keys(), platform_getenv(), prompt_unknown_host(), prompt_unknown_host_no_identity(), crypto_context_t::public_key, private_key_t::public_key, crypto_context_t::public_key_size, crypto_handshake_context_t::require_client_auth, SAFE_MALLOC_DEFER_FREE, safe_snprintf(), crypto_handshake_context_t::server_ip, crypto_handshake_context_t::server_port, crypto_handshake_context_t::server_uses_client_auth, SET_ERRNO, crypto_context_t::signature_size, crypto_handshake_context_t::state, STR_ONE, private_key_t::type, crypto_handshake_context_t::verify_server_key, and ZERO_KEY_SIZE.

Referenced by acds_handshake_receive(), acip_security_receive(), and client_handle_key_exchange_init().