bind static method

Future<PQSecureServer> bind(
  1. Object address,
  2. int port, {
  3. required SigningKeyPair identity,
  4. required String serverId,
  5. ClientAuthorizer? authorizeClient,
  6. PostQuantumCryptoEngine? engine,
  7. PQSecureChannelOptions options = const PQSecureChannelOptions(),
  8. void onHandshakeError(
    1. PQSecureChannelException error
    )?,
  9. int maxPendingHandshakes = 64,
  10. int maxIdleConnections = 1024,
  11. int backlog = 0,
  12. bool shared = false,
})

Binds to address:port (port 0 picks a free port) and starts accepting connections.

Two limits keep a flood of connections from exhausting the server:

  • maxIdleConnections caps connections that have not yet sent a ClientHello. Connections over the cap are closed at once. Idle connections cost only a socket.
  • maxPendingHandshakes caps handshakes past the ClientHello, the point where the server starts signing. A ClientHello over the cap is refused as busy.

The client must send each handshake message within options.stepTimeout (10 s by default). A client that goes silent, before or after its ClientHello, therefore frees its slot quickly. A slot is held until the handshake's work really stops, including a slow authorizeClient.

onHandshakeError receives every refused handshake; an error it throws is ignored. The other parameters are those of PQSecureChannel.accept.

Implementation

static Future<PQSecureServer> bind(
  Object address,
  int port, {
  required SigningKeyPair identity,
  required String serverId,
  ClientAuthorizer? authorizeClient,
  PostQuantumCryptoEngine? engine,
  PQSecureChannelOptions options = const PQSecureChannelOptions(),
  void Function(PQSecureChannelException error)? onHandshakeError,
  int maxPendingHandshakes = 64,
  int maxIdleConnections = 1024,
  int backlog = 0,
  bool shared = false,
}) async {
  if (maxPendingHandshakes < 1 || maxIdleConnections < 1) {
    throw const InvalidInputException(
      'maxPendingHandshakes and maxIdleConnections must be >= 1',
    );
  }
  final e = engine ?? PostQuantumCryptoEngine();
  final socket = await ServerSocket.bind(
    address,
    port,
    backlog: backlog,
    shared: shared,
  );
  final channels = StreamController<PQSecureChannel>();
  final server = PQSecureServer._(
    socket,
    channels,
    maxPendingHandshakes,
    maxIdleConnections,
  );
  socket.listen(
    (client) => server._handshake(
      client,
      identity: identity,
      serverId: serverId,
      authorizeClient: authorizeClient,
      engine: e,
      options: options,
      onHandshakeError: onHandshakeError,
    ),
    // An accept error (for example EMFILE under a connection flood) must
    // not crash the process: the listener keeps accepting.
    onError: (Object _) {},
    onDone: () => unawaited(channels.close()),
  );
  channels.onCancel = server.close;
  return server;
}