server.h File Reference

Server-side handshake functions. More...

Go to the source code of this file.

Functions
Server Handshake Protocol
asciichat_error_t	crypto_handshake_server_start (crypto_handshake_context_t *ctx, acip_transport_t *transport)
	Server: Start crypto handshake by sending public key.
asciichat_error_t	crypto_handshake_server_send_parameters (crypto_handshake_context_t *ctx, acip_transport_t *transport)
	Server: Send CRYPTO_PARAMETERS and set handshake context sizes.
asciichat_error_t	crypto_handshake_server_auth_challenge (crypto_handshake_context_t *ctx, acip_transport_t *transport, packet_type_t packet_type, const uint8_t *payload, size_t payload_len)
	Server: Process client's public key and send auth challenge.
asciichat_error_t	crypto_handshake_server_complete (crypto_handshake_context_t *ctx, acip_transport_t *transport, packet_type_t packet_type, const uint8_t *payload, size_t payload_len)
	Server: Process auth response and complete handshake.

Detailed Description

Server-side handshake functions.

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

Function Documentation

crypto_handshake_server_auth_challenge()

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

Server: Process client's public key and send auth challenge.

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_KEY_EXCHANGE_RESP or PACKET_TYPE_CRYPTO_NO_ENCRYPTION)
payload	Received packet payload
payload_len	Length of received payload

Returns

ASCIICHAT_OK on success, error code on failure

Server processes client's KEY_EXCHANGE_RESP packet and sends AUTH_CHALLENGE. Computes shared secret and generates authentication challenge nonce.

Note

Packet must be received by ACIP handler before calling this function

State transition: CRYPTO_HANDSHAKE_KEY_EXCHANGE -> CRYPTO_HANDSHAKE_AUTHENTICATING

Definition at line 173 of file lib/crypto/handshake/server.c.

                                                                             {
  ASCII_OTEL_SCOPE(CRYPTO_HANDSHAKE_SERVER_AUTH_CHALLENGE);
  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;
 
  // Check if client sent NO_ENCRYPTION response
  if (packet_type == PACKET_TYPE_CRYPTO_NO_ENCRYPTION) {
 
    // Send AUTH_FAILED to inform client (though they already know)
    auth_failure_packet_t failure = {0};
    failure.reason_flags = 0; // No specific auth failure, just encryption mismatch
    int send_result =
        packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_AUTH_FAILED, &failure, sizeof(failure), 0);
    if (send_result != 0) {
      return SET_ERRNO(ERROR_NETWORK, "Failed to send AUTH_FAILED packet");
    }
 
    return SET_ERRNO(ERROR_CRYPTO, "SECURITY: Client sent NO_ENCRYPTION response - encryption mode "
                                   "mismatch. Server requires encryption, but "
                                   "client has --no-encrypt. Use matching encryption settings on "
                                   "both client and server");
  }
 
  // Verify packet type
  if (packet_type != PACKET_TYPE_CRYPTO_KEY_EXCHANGE_RESP) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Expected KEY_EXCHANGE_RESPONSE, got packet type %d", packet_type);
  }
 
  // Verify payload size - client can send either simple or authenticated format
  // Simple: kex_public_key_size bytes
  // Authenticated: public_key_size + client_auth_key_size + client_sig_size bytes
  size_t simple_size = ctx->crypto_ctx.public_key_size;
  // Ed25519 public key is always 32 bytes
  // Ed25519 signature is always 64 bytes
  size_t authenticated_size = ctx->crypto_ctx.public_key_size + ED25519_PUBLIC_KEY_SIZE + ED25519_SIGNATURE_SIZE;
 
  bool client_sent_identity = false;
  const size_t identity_size = ED25519_PUBLIC_KEY_SIZE;
  const size_t signature_size = ED25519_SIGNATURE_SIZE;
  SAFE_MALLOC_DEFER_FREE(client_ephemeral_key, ctx->crypto_ctx.public_key_size, uint8_t *);
  SAFE_MALLOC_DEFER_FREE(client_identity_key, identity_size, uint8_t *);
  SAFE_MALLOC_DEFER_FREE(client_signature, signature_size, uint8_t *);
 
  if (!client_ephemeral_key || !client_identity_key || !client_signature) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate memory for client keys");
  }
 
  // Validate packet size using session parameters
  asciichat_error_t validation_result =
      crypto_handshake_validate_packet_size(ctx, PACKET_TYPE_CRYPTO_KEY_EXCHANGE_RESP, payload_len);
  if (validation_result != ASCIICHAT_OK) {
    // Payload ownership remains with caller
 
    return validation_result;
  }
 
  // Handle both authenticated and non-authenticated responses
  // authenticated_size is now a minimum - packet may be larger with GPG key ID
  if (payload_len >= authenticated_size) {
    // Authenticated format (may have optional GPG key ID):
    // [ephemeral:kex_size][identity:auth_size][signature:sig_size][gpg_key_id_len:1][gpg_key_id:0-16]
    memcpy(client_ephemeral_key, payload, ctx->crypto_ctx.public_key_size);
    memcpy(client_identity_key, payload + ctx->crypto_ctx.public_key_size, ED25519_PUBLIC_KEY_SIZE);
    memcpy(client_signature, payload + ctx->crypto_ctx.public_key_size + ED25519_PUBLIC_KEY_SIZE,
           ED25519_SIGNATURE_SIZE);
    client_sent_identity = true;
    ctx->client_sent_identity = true;
 
    // Extract GPG key ID if present
    const char *client_gpg_key_id = NULL;
    char gpg_key_id_buffer[GPG_FINGERPRINT_HEX_BUFFER_SIZE] = {0};
    size_t gpg_offset = ctx->crypto_ctx.public_key_size + ED25519_PUBLIC_KEY_SIZE + ED25519_SIGNATURE_SIZE;
    if (payload_len > gpg_offset) {
      uint8_t gpg_key_id_len = payload[gpg_offset];
      if (gpg_key_id_len > 0 && gpg_key_id_len <= 40 && payload_len >= gpg_offset + 1 + gpg_key_id_len) {
        memcpy(gpg_key_id_buffer, payload + gpg_offset + 1, gpg_key_id_len);
        gpg_key_id_buffer[gpg_key_id_len] = '\0';
        client_gpg_key_id = gpg_key_id_buffer;
        log_debug("Extracted client GPG key ID from KEY_EXCHANGE_RESPONSE: %s", client_gpg_key_id);
      }
    }
 
    // Check if client sent a null identity key (all zeros)
    bool client_has_null_identity = true;
    for (size_t i = 0; i < ED25519_PUBLIC_KEY_SIZE; i++) {
      if (client_identity_key[i] != 0) {
        client_has_null_identity = false;
        break;
      }
    }
 
    if (client_has_null_identity) {
      // Client has no identity key - this is allowed for servers without client authentication
      log_debug("Client sent null identity key - no client authentication required");
      client_sent_identity = false;
      ctx->client_sent_identity = false;
      NOTICE(WARNING, "UNVERIFIED CLIENT IDENTITY", "Client connected without identity authentication");
    } else {
      // Client has a real identity key
      // If server didn't specify --client-keys, skip signature verification
      // (server doesn't care about client identity verification)
      if (!ctx->require_client_auth) {
        log_info("Skipping client signature verification (no --client-keys specified)");
        NOTICE(WARNING, "UNVERIFIED CLIENT IDENTITY", "Connection is encrypted but client identity is NOT verified");
      } else {
        // Verify client's signature
        log_debug("Verifying client's signature");
        // Pass client's GPG key ID if available
        if (ed25519_verify_signature(client_identity_key, client_ephemeral_key, ctx->crypto_ctx.public_key_size,
                                     client_signature, client_gpg_key_id) != 0) {
          // Send AUTH_FAILED with specific reason
          auth_failure_packet_t failure = {0};
          failure.reason_flags = AUTH_FAIL_SIGNATURE_INVALID;
          int send_result =
              packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_AUTH_FAILED, &failure, sizeof(failure), 0);
          if (send_result != 0) {
            return SET_ERRNO(ERROR_NETWORK, "Failed to send AUTH_FAILED packet");
          }
 
          return SET_ERRNO(ERROR_CRYPTO, "Client signature verification FAILED - rejecting connection");
        }
      }
    }
 
    // Store the verified client identity for whitelist checking (only if client has identity)
    if (client_sent_identity) {
      ctx->client_ed25519_key.type = KEY_TYPE_ED25519;
      memcpy(ctx->client_ed25519_key.key, client_identity_key, ctx->crypto_ctx.public_key_size);
    }
  } else if (payload_len == simple_size) {
    // Non-authenticated format: [ephemeral:public_key_size] only
    log_debug("Client sent non-authenticated response (%zu bytes)", payload_len);
    memcpy(client_ephemeral_key, payload, ctx->crypto_ctx.public_key_size);
    client_sent_identity = false;
    ctx->client_sent_identity = false;
    NOTICE(WARNING, "UNVERIFIED CLIENT IDENTITY", "Client connected without identity authentication");
  } else {
    // Payload ownership remains with caller
 
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL,
                     "Invalid client key response size: %zu bytes (expected %zu for "
                     "authenticated or %zu for simple)",
                     payload_len, authenticated_size, simple_size);
  }
 
  // Extract pointers for compatibility with existing code
  const uint8_t *client_x25519 = client_ephemeral_key;
  const uint8_t *client_ed25519 = client_sent_identity ? client_identity_key : NULL;
 
  // Check client Ed25519 key against whitelist if client provided one and
  // whitelist is enabled
  if (client_sent_identity && ctx->require_client_auth && ctx->client_whitelist && ctx->num_whitelisted_clients > 0) {
    bool key_found = false;
 
    // Debug: print client's Ed25519 identity key
    char client_ed25519_hex[HEX_STRING_SIZE_32];
    for (int i = 0; i < ED25519_PUBLIC_KEY_SIZE; i++) {
      safe_snprintf(client_ed25519_hex + i * 2, 3, "%02x", client_ed25519[i]);
    }
    log_debug("Client Ed25519 identity key: %s", client_ed25519_hex);
 
    // Compare against whitelist (direct Ed25519 comparison - no conversion!)
    for (size_t i = 0; i < ctx->num_whitelisted_clients; i++) {
      // Debug: print whitelist Ed25519 key
      char whitelist_ed25519_hex[HEX_STRING_SIZE_32];
      for (int j = 0; j < ED25519_PUBLIC_KEY_SIZE; j++) {
        safe_snprintf(whitelist_ed25519_hex + j * 2, 3, "%02x", ctx->client_whitelist[i].key[j]);
      }
      log_debug("Whitelist[%zu] Ed25519 key: %s", i, whitelist_ed25519_hex);
 
      // Direct comparison of Ed25519 keys (constant-time to prevent timing
      // attacks)
      if (sodium_memcmp(client_ed25519, ctx->client_whitelist[i].key, ED25519_PUBLIC_KEY_SIZE) == 0) {
        key_found = true;
        ctx->client_ed25519_key_verified = true;
 
        // Store the client's Ed25519 key for signature verification
        memcpy(&ctx->client_ed25519_key, &ctx->client_whitelist[i], sizeof(public_key_t));
 
        log_debug("Client Ed25519 key authorized (whitelist entry %zu)", i);
        if (strlen(ctx->client_whitelist[i].comment) > 0) {
          log_info("Client identity: %s", ctx->client_whitelist[i].comment);
        }
        break;
      }
    }
 
    if (!key_found) {
      SET_ERRNO(ERROR_CRYPTO_AUTH, "Client Ed25519 key not in whitelist - rejecting connection");
      // Don't send AUTH_FAILED here - wait until server_complete
      // Just mark that the key was rejected
      ctx->client_ed25519_key_verified = false;
    }
  } else if (client_sent_identity) {
    // No whitelist checking - just store the client's Ed25519 key for later
    // (Already stored at line 313-314, but keep this for clarity)
    // Discovery can require proof of identity without restricting which identities may join.
    // require_client_auth ensured that the signature was verified above.
    ctx->client_ed25519_key_verified = ctx->require_client_auth && ctx->allow_unlisted_client_identity;
  }
 
  // Set peer's X25519 encryption key - this also derives the shared secret
  crypto_result_t crypto_result = crypto_set_peer_public_key(&ctx->crypto_ctx, client_x25519);
  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));
  }
 
  // Do authentication challenge if client provided identity key OR server
  // requires password
  if (client_sent_identity || ctx->crypto_ctx.has_password || ctx->require_client_auth) {
    // Generate nonce and store it in the context
    crypto_result = crypto_generate_nonce(ctx->crypto_ctx.auth_nonce);
    if (crypto_result != CRYPTO_OK) {
      return SET_ERRNO(ERROR_CRYPTO, "Failed to generate nonce: %s", crypto_result_to_string(crypto_result));
    }
 
    // Prepare AUTH_CHALLENGE packet: 1 byte flags + auth_challenge_size byte nonce
    size_t challenge_packet_size = AUTH_CHALLENGE_FLAGS_SIZE + ctx->crypto_ctx.auth_challenge_size;
    uint8_t challenge_packet[1 + HMAC_SHA256_SIZE]; // Maximum size buffer
    uint8_t auth_flags = 0;
 
    // Set flags based on server requirements
    if (ctx->crypto_ctx.has_password) {
      auth_flags |= AUTH_REQUIRE_PASSWORD;
    }
    if (ctx->require_client_auth) {
      auth_flags |= AUTH_REQUIRE_CLIENT_KEY;
    }
 
    challenge_packet[0] = auth_flags;
    memcpy(challenge_packet + 1, ctx->crypto_ctx.auth_nonce, ctx->crypto_ctx.auth_challenge_size);
 
    // Send AUTH_CHALLENGE with flags + nonce (challenge_packet_size bytes)
    result = packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_AUTH_CHALLENGE, challenge_packet,
                                       challenge_packet_size, 0);
    if (result != 0) {
      return SET_ERRNO(ERROR_NETWORK, "Failed to send AUTH_CHALLENGE packet");
    }
 
    ctx->state = CRYPTO_HANDSHAKE_AUTHENTICATING;
  } else {
    // No authentication needed - skip to completion
    log_debug("Skipping authentication (no password and client has no identity key)");
 
    // Send HANDSHAKE_COMPLETE immediately
    result = packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_HANDSHAKE_COMPLETE, NULL, 0, 0);
    if (result != 0) {
      return SET_ERRNO(ERROR_NETWORK, "Failed to send HANDSHAKE_COMPLETE packet");
    }
 
    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)");
  }
 
  return ASCIICHAT_OK;
}

References crypto_handshake_context_t::allow_unlisted_client_identity, ASCII_OTEL_SCOPE, ASCIICHAT_OK, AUTH_CHALLENGE_FLAGS_SIZE, crypto_context_t::auth_challenge_size, AUTH_FAIL_SIGNATURE_INVALID, crypto_context_t::auth_nonce, AUTH_REQUIRE_CLIENT_KEY, AUTH_REQUIRE_PASSWORD, crypto_handshake_context_t::client_ed25519_key, crypto_handshake_context_t::client_ed25519_key_verified, crypto_handshake_context_t::client_sent_identity, crypto_handshake_context_t::client_whitelist, public_key_t::comment, crypto_handshake_context_t::crypto_ctx, crypto_generate_nonce(), CRYPTO_HANDSHAKE_AUTHENTICATING, CRYPTO_HANDSHAKE_KEY_EXCHANGE, CRYPTO_HANDSHAKE_READY, crypto_handshake_validate_packet_size(), CRYPTO_OK, crypto_result_to_string(), crypto_set_peer_public_key(), ED25519_PUBLIC_KEY_SIZE, ED25519_SIGNATURE_SIZE, ed25519_verify_signature(), ERROR_CRYPTO, ERROR_CRYPTO_AUTH, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, ERROR_NETWORK, ERROR_NETWORK_PROTOCOL, GPG_FINGERPRINT_HEX_BUFFER_SIZE, crypto_context_t::handshake_complete, crypto_context_t::has_password, HEX_STRING_SIZE_32, HMAC_SHA256_SIZE, public_key_t::key, KEY_TYPE_ED25519, log_debug, log_info, NOTICE, crypto_handshake_context_t::num_whitelisted_clients, packet_send_via_transport(), PACKET_TYPE_CRYPTO_AUTH_CHALLENGE, PACKET_TYPE_CRYPTO_AUTH_FAILED, PACKET_TYPE_CRYPTO_HANDSHAKE_COMPLETE, PACKET_TYPE_CRYPTO_KEY_EXCHANGE_RESP, PACKET_TYPE_CRYPTO_NO_ENCRYPTION, crypto_context_t::public_key_size, auth_failure_packet_t::reason_flags, crypto_handshake_context_t::require_client_auth, SAFE_MALLOC_DEFER_FREE, safe_snprintf(), SET_ERRNO, crypto_handshake_context_t::state, and public_key_t::type.

Referenced by acip_security_receive(), and network_negotiation_receive().

crypto_handshake_server_complete()

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

Server: Process auth response and complete handshake.

Parameters

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

Returns

ASCIICHAT_OK on success, error code on failure

Server processes client's AUTH_RESPONSE packet and sends SERVER_AUTH_RESP. Verifies authentication HMAC or signature and completes handshake.

Note

Packet must be received by ACIP handler before calling this function

State transition: CRYPTO_HANDSHAKE_AUTHENTICATING -> CRYPTO_HANDSHAKE_READY

Definition at line 441 of file lib/crypto/handshake/server.c.

                                                                       {
  ASCII_OTEL_SCOPE(CRYPTO_HANDSHAKE_SERVER_COMPLETE);
  if (!ctx || ctx->state != CRYPTO_HANDSHAKE_AUTHENTICATING) {
    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;
 
  // Verify packet type
  if (packet_type != PACKET_TYPE_CRYPTO_AUTH_RESPONSE) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Expected AUTH_RESPONSE, got packet type %d", packet_type);
  }
 
  // Verify password if required
  if (ctx->crypto_ctx.has_password) {
    // Validate packet size using session parameters
    asciichat_error_t validation_result =
        crypto_handshake_validate_packet_size(ctx, PACKET_TYPE_CRYPTO_AUTH_RESPONSE, payload_len);
    if (validation_result != ASCIICHAT_OK) {
      return validation_result;
    }
 
    // Ensure shared secret is derived before password verification
    // This is critical for password HMAC verification which binds to the shared secret
    if (!ctx->crypto_ctx.key_exchange_complete) {
      SET_ERRNO(ERROR_CRYPTO, "Password authentication failed - key exchange not complete");
 
      // Send AUTH_FAILED with specific reason
      auth_failure_packet_t failure = {0};
      failure.reason_flags = AUTH_FAIL_PASSWORD_INCORRECT;
      if (ctx->require_client_auth) {
        failure.reason_flags |= AUTH_FAIL_CLIENT_KEY_REQUIRED;
      }
      packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_AUTH_FAILED, &failure, sizeof(failure), 0);
      return ERROR_NETWORK;
    }
 
    // Verify password HMAC (binds to DH shared_secret to prevent MITM)
    log_debug("Verifying password HMAC: has_password=%d, key_exchange_complete=%d", ctx->crypto_ctx.has_password,
              ctx->crypto_ctx.key_exchange_complete);
    if (!payload) {
      SET_ERRNO(ERROR_INVALID_PARAM, "Payload is NULL in password authentication");
      return ERROR_CRYPTO;
    }
    if (!crypto_verify_auth_response(&ctx->crypto_ctx, ctx->crypto_ctx.auth_nonce, payload)) {
      log_debug("Password HMAC verification failed");
      // Enhanced error message when both password and whitelist are required
      if (ctx->require_client_auth) {
        SET_ERRNO(ERROR_CRYPTO,
                  "Password authentication failed - incorrect password (server also requires whitelisted client key)");
      } else {
        SET_ERRNO(ERROR_CRYPTO, "Password authentication failed - incorrect password");
      }
 
      // Send AUTH_FAILED with specific reason
      auth_failure_packet_t failure = {0};
      failure.reason_flags = AUTH_FAIL_PASSWORD_INCORRECT;
      if (ctx->require_client_auth) {
        failure.reason_flags |= AUTH_FAIL_CLIENT_KEY_REQUIRED;
      }
      packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_AUTH_FAILED, &failure, sizeof(failure), 0);
      return ERROR_NETWORK;
    }
 
    // Extract client challenge nonce for mutual authentication
    // Use ctx->crypto_ctx.hmac_size and ctx->crypto_ctx.auth_challenge_size (negotiated during handshake)
    memcpy(ctx->client_challenge_nonce, payload + ctx->crypto_ctx.hmac_size, ctx->crypto_ctx.auth_challenge_size);
    log_info("Password authentication successful");
  } else {
    // Ed25519 signature auth (payload format: signature + client_nonce + gpg_key_id_len + gpg_key_id)
    size_t expected_min_signature_size =
        ctx->crypto_ctx.signature_size + ctx->crypto_ctx.auth_challenge_size + 1; // +1 for gpg_key_id_len byte
    size_t expected_password_size = ctx->crypto_ctx.hmac_size + ctx->crypto_ctx.auth_challenge_size;
    if (!payload) {
      SET_ERRNO(ERROR_INVALID_PARAM, "Payload is NULL in signature authentication");
      return ERROR_CRYPTO;
    }
    if (payload_len >= expected_min_signature_size) {
      // Signature + client nonce + optional GPG key ID - VERIFY the signature on the challenge nonce
      const uint8_t *signature = payload;
      const uint8_t *client_nonce = payload + ctx->crypto_ctx.signature_size;
 
      // Extract GPG key ID if present
      size_t gpg_offset = ctx->crypto_ctx.signature_size + ctx->crypto_ctx.auth_challenge_size;
      uint8_t gpg_key_id_len = payload[gpg_offset];
      const char *client_gpg_key_id = NULL;
      char gpg_key_id_buffer[GPG_FINGERPRINT_HEX_BUFFER_SIZE] = {0};
 
      if (gpg_key_id_len > 0 && gpg_key_id_len <= 40) {
        // Validate packet has enough bytes for GPG key ID
        if (payload_len >= gpg_offset + 1 + gpg_key_id_len) {
          memcpy(gpg_key_id_buffer, payload + gpg_offset + 1, gpg_key_id_len);
          gpg_key_id_buffer[gpg_key_id_len] = '\0';
          client_gpg_key_id = gpg_key_id_buffer;
          log_debug("Extracted client GPG key ID from AUTH_RESPONSE: %s", client_gpg_key_id);
        }
      }
 
      // Actually verify the Ed25519/GPG signature on the challenge nonce
      // This was missing, allowing authentication bypass
      if (ctx->client_ed25519_key_verified) {
        // Use unified verification function that handles both Ed25519 and GPG keys
        // This matches the KEY_EXCHANGE verification path
        log_debug("Verifying %s signature on challenge nonce",
                  ctx->client_ed25519_key.type == KEY_TYPE_GPG ? "GPG" : "Ed25519");
 
        asciichat_error_t verify_result = ed25519_verify_signature(
            ctx->client_ed25519_key.key, ctx->crypto_ctx.auth_nonce, ctx->crypto_ctx.auth_challenge_size, signature,
            client_gpg_key_id // GPG key ID for fallback verification
        );
 
        if (verify_result != ASCIICHAT_OK) {
          auth_failure_packet_t failure = {0};
          failure.reason_flags = AUTH_FAIL_CLIENT_KEY_REJECTED;
          SET_ERRNO(ERROR_CRYPTO_AUTH, "%s signature verification failed on challenge nonce",
                    ctx->client_ed25519_key.type == KEY_TYPE_GPG ? "GPG" : "Ed25519");
          packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_AUTH_FAILED, &failure, sizeof(failure), 0);
          return ERROR_CRYPTO_AUTH;
        }
        log_debug("%s signature on challenge nonce verified successfully",
                  ctx->client_ed25519_key.type == KEY_TYPE_GPG ? "GPG" : "Ed25519");
      }
 
      memcpy(ctx->client_challenge_nonce, client_nonce, ctx->crypto_ctx.auth_challenge_size);
    } else if (payload_len == expected_password_size) {
      // Just client nonce (legacy or password-only mode without password enabled)
      // Use ctx->crypto_ctx.hmac_size and ctx->crypto_ctx.auth_challenge_size (negotiated during handshake)
      memcpy(ctx->client_challenge_nonce, payload + ctx->crypto_ctx.hmac_size, ctx->crypto_ctx.auth_challenge_size);
    } else {
      // Validate packet size using session parameters
      asciichat_error_t validation_result =
          crypto_handshake_validate_packet_size(ctx, PACKET_TYPE_CRYPTO_AUTH_RESPONSE, payload_len);
      if (validation_result != ASCIICHAT_OK) {
        return validation_result;
      }
    }
  }
 
  // Verify client key if required (whitelist)
  if (ctx->require_client_auth) {
    if (!ctx->client_ed25519_key_verified) {
      // Send AUTH_FAILED with specific reason
      auth_failure_packet_t failure = {0};
 
      // Check if client provided a key but it wasn't in whitelist
      if (ctx->client_sent_identity) {
        SET_ERRNO(ERROR_CRYPTO_AUTH, "Client key authentication failed - your key is not in the server's whitelist");
        failure.reason_flags = AUTH_FAIL_CLIENT_KEY_REJECTED;
      } else {
        SET_ERRNO(ERROR_CRYPTO_AUTH, "Client key authentication failed - client did not provide a key");
        failure.reason_flags = AUTH_FAIL_CLIENT_KEY_REQUIRED;
      }
 
      if (ctx->crypto_ctx.has_password) {
        // Password was verified, but key was not
        SET_ERRNO(ERROR_CRYPTO_AUTH, "Note: Password was correct, but client key is required");
      }
      packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_AUTH_FAILED, &failure, sizeof(failure), 0);
      return ERROR_NETWORK;
    }
    log_info("Client key authentication successful (whitelist verified)");
    if (strlen(ctx->client_ed25519_key.comment) > 0) {
      log_info("Authenticated client: %s", ctx->client_ed25519_key.comment);
    }
  }
 
  // Send SERVER_AUTH_RESPONSE with server's HMAC for mutual authentication
  // Bind to DH shared_secret to prevent MITM (even if attacker knows password)
  // Allocate buffer using negotiated hmac_size (should match AUTH_HMAC_SIZE)
  uint8_t server_hmac[HMAC_SHA256_SIZE]; // Maximum size, actual size is ctx->hmac_size
  crypto_result_t crypto_result =
      crypto_compute_auth_response(&ctx->crypto_ctx, ctx->client_challenge_nonce, server_hmac);
  if (crypto_result != CRYPTO_OK) {
    SET_ERRNO(ERROR_CRYPTO, "Failed to compute server HMAC for mutual authentication: %s",
              crypto_result_to_string(crypto_result));
    return ERROR_NETWORK;
  }
 
  log_debug("Sending SERVER_AUTH_RESPONSE packet with server HMAC (%u bytes) "
            "for mutual authentication",
            ctx->crypto_ctx.hmac_size);
  result = packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_SERVER_AUTH_RESP, server_hmac,
                                     ctx->crypto_ctx.hmac_size, 0);
  if (result != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_NETWORK, "Failed to send SERVER_AUTH_RESPONSE packet");
    return ERROR_NETWORK;
  }
 
  ctx->state = CRYPTO_HANDSHAKE_READY;
  ctx->crypto_ctx.handshake_complete = true;
  log_debug("Crypto handshake completed successfully (mutual authentication)");
 
  return ASCIICHAT_OK;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, crypto_context_t::auth_challenge_size, AUTH_FAIL_CLIENT_KEY_REJECTED, AUTH_FAIL_CLIENT_KEY_REQUIRED, AUTH_FAIL_PASSWORD_INCORRECT, crypto_context_t::auth_nonce, crypto_handshake_context_t::client_challenge_nonce, crypto_handshake_context_t::client_ed25519_key, crypto_handshake_context_t::client_ed25519_key_verified, crypto_handshake_context_t::client_sent_identity, public_key_t::comment, crypto_compute_auth_response(), crypto_handshake_context_t::crypto_ctx, CRYPTO_HANDSHAKE_AUTHENTICATING, CRYPTO_HANDSHAKE_READY, crypto_handshake_validate_packet_size(), CRYPTO_OK, crypto_result_to_string(), crypto_verify_auth_response(), ed25519_verify_signature(), ERROR_CRYPTO, ERROR_CRYPTO_AUTH, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_NETWORK, ERROR_NETWORK_PROTOCOL, GPG_FINGERPRINT_HEX_BUFFER_SIZE, crypto_context_t::handshake_complete, crypto_context_t::has_password, HMAC_SHA256_SIZE, crypto_context_t::hmac_size, public_key_t::key, crypto_context_t::key_exchange_complete, KEY_TYPE_GPG, log_debug, log_info, packet_send_via_transport(), PACKET_TYPE_CRYPTO_AUTH_FAILED, PACKET_TYPE_CRYPTO_AUTH_RESPONSE, PACKET_TYPE_CRYPTO_SERVER_AUTH_RESP, auth_failure_packet_t::reason_flags, crypto_handshake_context_t::require_client_auth, SET_ERRNO, crypto_context_t::signature_size, crypto_handshake_context_t::state, and public_key_t::type.

Referenced by acip_security_receive(), and network_negotiation_receive().

crypto_handshake_server_send_parameters()

asciichat_error_t crypto_handshake_server_send_parameters	(	crypto_handshake_context_t *	ctx,
		acip_transport_t *	transport )

Server: Send CRYPTO_PARAMETERS and set handshake context sizes.

Parameters

ctx	Handshake context
transport	ACIP transport to send on

Returns

ASCIICHAT_OK on success, error code on failure

Must be called before crypto_handshake_server_start(). Builds crypto parameters based on server state (identity key presence), sends them to the client, and updates context sizes to match.

TCP server path calls this indirectly via its own negotiation in src/server/crypto.c (which customizes parameters based on client capabilities). WebSocket and discovery-service paths call this directly.

<X25519 key exchange (Curve25519)

<Ed25519 authentication (Edwards-curve signatures)

<No authentication (plaintext mode)

<XSalsa20-Poly1305 authenticated encryption

<No encryption (plaintext mode)

Definition at line 28 of file lib/crypto/handshake/server.c.

                                                                                       {
  if (!ctx || !transport) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, transport=%p", (void *)ctx, (void *)transport);
  }
 
  bool has_identity_key = (ctx->server_private_key.type == KEY_TYPE_ED25519);
 
  crypto_parameters_packet_t params;
  memset(&params, 0, sizeof(params));
 
  params.selected_kex = KEX_ALGO_X25519;
  params.selected_auth = has_identity_key ? AUTH_ALGO_ED25519 : AUTH_ALGO_NONE;
  params.selected_cipher = ctx->crypto_ctx.encrypt_data ? CIPHER_ALGO_XSALSA20_POLY1305 : CIPHER_ALGO_NONE;
  params.verification_enabled = ctx->require_client_auth ? 1 : 0;
  params.kex_public_key_size = ctx->crypto_ctx.public_key_size;
  params.shared_secret_size = CRYPTO_SHARED_KEY_SIZE;
  params.nonce_size = XSALSA20_NONCE_SIZE;
  params.mac_size = POLY1305_MAC_SIZE;
  params.hmac_size = 32; // SHA256 output size
 
  if (has_identity_key) {
    params.auth_public_key_size = ED25519_PUBLIC_KEY_SIZE;
    params.signature_size = ED25519_SIGNATURE_SIZE;
  }
 
  // Set context sizes to match what we send (host byte order)
  crypto_handshake_set_parameters(ctx, &params);
 
  // Convert to network byte order for the wire
  params.kex_public_key_size = htons(params.kex_public_key_size);
  params.auth_public_key_size = htons(params.auth_public_key_size);
  params.signature_size = htons(params.signature_size);
  params.shared_secret_size = htons(params.shared_secret_size);
 
  int result =
      packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_PARAMETERS, (uint8_t *)&params, sizeof(params), 0);
  if (result != ASCIICHAT_OK) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to send CRYPTO_PARAMETERS packet");
  }
 
  log_debug("[HANDSHAKE] CRYPTO_PARAMETERS sent: auth=%s, cipher=XSALSA20_POLY1305",
            has_identity_key ? "ED25519" : "NONE");
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, AUTH_ALGO_ED25519, AUTH_ALGO_NONE, crypto_parameters_packet_t::auth_public_key_size, CIPHER_ALGO_NONE, CIPHER_ALGO_XSALSA20_POLY1305, crypto_handshake_context_t::crypto_ctx, crypto_handshake_set_parameters(), CRYPTO_SHARED_KEY_SIZE, ED25519_PUBLIC_KEY_SIZE, ED25519_SIGNATURE_SIZE, crypto_context_t::encrypt_data, ERROR_INVALID_PARAM, ERROR_NETWORK, crypto_parameters_packet_t::hmac_size, KEX_ALGO_X25519, crypto_parameters_packet_t::kex_public_key_size, KEY_TYPE_ED25519, log_debug, crypto_parameters_packet_t::mac_size, crypto_parameters_packet_t::nonce_size, packet_send_via_transport(), PACKET_TYPE_CRYPTO_PARAMETERS, POLY1305_MAC_SIZE, crypto_context_t::public_key_size, crypto_handshake_context_t::require_client_auth, crypto_parameters_packet_t::selected_auth, crypto_parameters_packet_t::selected_cipher, crypto_parameters_packet_t::selected_kex, crypto_handshake_context_t::server_private_key, SET_ERRNO, crypto_parameters_packet_t::shared_secret_size, crypto_parameters_packet_t::signature_size, private_key_t::type, crypto_parameters_packet_t::verification_enabled, and XSALSA20_NONCE_SIZE.

Referenced by acip_security_receive(), and network_negotiation_receive().

crypto_handshake_server_start()

asciichat_error_t crypto_handshake_server_start	(	crypto_handshake_context_t *	ctx,
		acip_transport_t *	transport )

Server: Start crypto handshake by sending public key.

Parameters

ctx	Handshake context (must be in CRYPTO_HANDSHAKE_INIT state)
transport	ACIP transport to send on

Returns

ASCIICHAT_OK on success, error code on failure

Server initiates handshake by sending KEY_EXCHANGE_INIT packet. Supports both simple and authenticated formats based on server identity key.

Note

Packet formats:

• Simple: [ephemeral_key:public_key_size] (when server has no identity key)
• Authenticated: [ephemeral_key:public_key_size][identity_key:auth_public_key_size][signature:signature_size] (when server has Ed25519 identity key)

State transition: CRYPTO_HANDSHAKE_INIT -> CRYPTO_HANDSHAKE_KEY_EXCHANGE

Definition at line 75 of file lib/crypto/handshake/server.c.

                                                                                                              {
  ASCII_OTEL_SCOPE(CRYPTO_HANDSHAKE_SERVER_START);
  log_debug("[HANDSHAKE_START] ctx=%p, transport=%p", (void *)ctx, (void *)transport);
 
  if (!ctx || ctx->state != CRYPTO_HANDSHAKE_INIT) {
    log_error("[HANDSHAKE_START] FAILED: Invalid state - ctx=%p, state=%d", (void *)ctx, ctx ? (int)ctx->state : -1);
    return SET_ERRNO(ERROR_INVALID_STATE, "Invalid state: ctx=%p, state=%d", (void *)ctx, ctx ? (int)ctx->state : -1);
  }
  log_debug("[HANDSHAKE_START] State check OK: state=%d (CRYPTO_HANDSHAKE_INIT)", ctx->state);
 
  int result;
 
  // Caller is responsible for sending CRYPTO_PARAMETERS and calling
  // crypto_handshake_set_parameters() before this function. This function
  // only handles KEY_EXCHANGE_INIT.
 
  // Calculate packet size based on negotiated crypto parameters
  size_t expected_packet_size =
      ctx->crypto_ctx.public_key_size + ctx->crypto_ctx.auth_public_key_size + ctx->crypto_ctx.signature_size;
 
  log_debug("SERVER_KEY_EXCHANGE: kex_size=%u, auth_size=%u, sig_size=%u, expected_size=%zu",
            ctx->crypto_ctx.public_key_size, ctx->crypto_ctx.auth_public_key_size, ctx->crypto_ctx.signature_size,
            expected_packet_size);
 
  // Check if we have an identity key to send authenticated packet
  if (ctx->server_private_key.type == KEY_TYPE_ED25519) {
    // Extended packet format:
    // [ephemeral_key:kex_size][identity_key:auth_size][signature:sig_size]
    uint8_t *extended_packet;
    extended_packet = SAFE_MALLOC(expected_packet_size, uint8_t *);
    if (!extended_packet) {
      return SET_ERRNO(ERROR_MEMORY, "Failed to allocate memory for extended packet");
    }
 
    // Copy ephemeral public key
    memcpy(extended_packet, ctx->crypto_ctx.public_key, ctx->crypto_ctx.public_key_size);
 
    // Copy identity public key
    memcpy(extended_packet + ctx->crypto_ctx.public_key_size, ctx->server_public_key.key,
           ctx->crypto_ctx.auth_public_key_size);
 
    // DEBUG: Print identity key being sent
    char hex[HEX_STRING_SIZE_32];
    for (int i = 0; i < ED25519_PUBLIC_KEY_SIZE; i++) {
      safe_snprintf(hex + i * 2, 3, "%02x", ctx->server_public_key.key[i]);
    }
    hex[HEX_STRING_SIZE_32 - 1] = '\0';
 
    // Sign the ephemeral key with our identity key
    log_debug("Signing ephemeral key with server identity key");
 
    // Log key details in debug mode
    char hex_ephemeral[HEX_STRING_SIZE_32], hex_identity[CRYPTO_HANDSHAKE_SERVER_HEX_IDENTITY_BUFFER_SIZE];
    for (int i = 0; i < 32; i++) {
      safe_snprintf(hex_ephemeral + i * 2, 3, "%02x", ctx->crypto_ctx.public_key[i]);
      safe_snprintf(hex_identity + i * 2, 3, "%02x", ctx->server_public_key.key[i]);
    }
    hex_ephemeral[64] = hex_identity[64] = '\0';
    log_debug("SERVER: Ephemeral key (32 bytes): %s", hex_ephemeral);
    log_debug("SERVER: Identity public key: %s", hex_identity);
 
    if (ed25519_sign_message(&ctx->server_private_key, ctx->crypto_ctx.public_key, ctx->crypto_ctx.public_key_size,
                             extended_packet + ctx->crypto_ctx.public_key_size +
                                 ctx->crypto_ctx.auth_public_key_size) != 0) {
      SAFE_FREE(extended_packet);
      return SET_ERRNO(ERROR_CRYPTO, "Failed to sign ephemeral key with identity key");
    }
 
    log_debug("Sending authenticated KEY_EXCHANGE_INIT (%zu bytes: ephemeral + "
              "identity + signature)",
              expected_packet_size);
    log_debug("[HANDSHAKE_START] Calling packet_send_via_transport(type=%d, payload_len=%zu, 0)...",
              PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT, expected_packet_size);
    result = packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT, extended_packet,
                                       expected_packet_size, 0);
    log_debug("[HANDSHAKE_START] packet_send_via_transport returned %d", result);
    SAFE_FREE(extended_packet);
  } else {
    // No identity key - send just the ephemeral key
    log_debug("Sending simple KEY_EXCHANGE_INIT (%zu bytes: ephemeral key only)", ctx->crypto_ctx.public_key_size);
    log_debug("[HANDSHAKE_START] Calling packet_send_via_transport(type=%d, payload_len=%zu, 0)...",
              PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT, ctx->crypto_ctx.public_key_size);
    result = packet_send_via_transport(transport, PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT, ctx->crypto_ctx.public_key,
                                       ctx->crypto_ctx.public_key_size, 0);
    log_debug("[HANDSHAKE_START] packet_send_via_transport returned %d", result);
  }
 
  if (result != ASCIICHAT_OK) {
    log_error("[HANDSHAKE_START] FAILED: packet_send returned %d", result);
    return SET_ERRNO(ERROR_NETWORK, "Failed to send KEY_EXCHANGE_INIT packet");
  }
  log_debug("[HANDSHAKE_START] ===== SUCCESS: KEY_EXCHANGE_INIT sent =====");
 
  ctx->state = CRYPTO_HANDSHAKE_KEY_EXCHANGE;
 
  return ASCIICHAT_OK;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, crypto_context_t::auth_public_key_size, crypto_handshake_context_t::crypto_ctx, CRYPTO_HANDSHAKE_INIT, CRYPTO_HANDSHAKE_KEY_EXCHANGE, CRYPTO_HANDSHAKE_SERVER_HEX_IDENTITY_BUFFER_SIZE, ED25519_PUBLIC_KEY_SIZE, ed25519_sign_message(), ERROR_CRYPTO, ERROR_INVALID_STATE, ERROR_MEMORY, ERROR_NETWORK, HEX_STRING_SIZE_32, public_key_t::key, KEY_TYPE_ED25519, log_debug, log_error, packet_send_via_transport(), PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT, crypto_context_t::public_key, crypto_context_t::public_key_size, SAFE_FREE, SAFE_MALLOC, safe_snprintf(), crypto_handshake_context_t::server_private_key, crypto_handshake_context_t::server_public_key, SET_ERRNO, crypto_context_t::signature_size, crypto_handshake_context_t::state, and private_key_t::type.

Referenced by acip_security_receive(), and network_negotiation_receive().