C · Noise Keys

Noise Keys

#include <ucall/types.h> 1.0.0-rc.1 · 60202332

XX and IK servers authenticate clients; KK clients connect to a separately configured peer, and a KK server interface names its preknown initiator in noise_peer_key. ucall_noise_key_generate() draws a static keypair from the operating system’s entropy, reporting ucall_status_io_k when it is refused, and ucall_noise_key_derive() recovers the public key of a stored private key.

API

Types

ucall_security_tSecurity modes for UCall server and client.
types.h:190 ↗
enum ucall_security_t

Noise protocol pattern to use for handshake. Supported values:

  • XX: Full mutual authentication (both parties authenticate during handshake).
  • IK: Client knows server's public key in advance (Identity Known).
  • KK: Both parties know each other's public keys (Known Known).

Values

ucall_security_none_kNo encryption, plain TCP/IP.
ucall_security_noise_xx_kTrust on first use - no pre-shared keys needed.
ucall_security_noise_ik_kClient knows server's public key in advance.
ucall_security_noise_kk_kBoth know each other's public keys in advance.

Notes

Use http+noise:// or ws+noise:// URL schemes to enable Noise transport.

See also

https://noiseprotocol.org/noise.html for pattern specifications.

ucall_noise_key_tNoise protocol key (32 bytes for Curve25519).
types.h:206 ↗
typedef ucall_byte_t ucall_noise_key_t[32];
ucall_peer_authorizer_tDecides whether a peer presenting a given static key may proceed past the handshake.
types.h:326 ↗
typedef ucall_status_t(*) ucall_peer_authorizer_t(ucall_noise_key_t const *peer_static_key, void *context);

Required for ucall_security_noise_xx_k, where keys are learned during the handshake rather than known in advance. Called after the key is authenticated, before any payload. Returning ucall_status_success_k admits the peer.

Statuses

Functions

ucall_noise_key_generateDraws a fresh static keypair for noise_private_key fields and peer authorizers.
types.h:396 ↗
void ucall_noise_key_generate(ucall_noise_key_generate_t *arguments);

Both outputs are zeroed unless the call succeeds.

Parameters

outcomeucall_outcome_t *The verb's status, listed on the verb.
private_keyucall_noise_key_t *Output for the secret scalar, drawn from the operating system's entropy.
public_keyucall_noise_key_t *Output for the Curve25519 public key matching private_key.

Notes

Thread-safe.

Statuses

ucall_noise_key_deriveDerives the public key of a stored private key, as peer authorizers compare it.
types.h:420 ↗
void ucall_noise_key_derive(ucall_noise_key_derive_t *arguments);

Parameters

outcomeucall_outcome_t *Output for the outcome.
private_keyucall_noise_key_t const *The secret scalar, as noise_private_key fields take it.
public_keyucall_noise_key_t *Output for the Curve25519 public key, which peers see during the handshake.

Notes

Thread-safe.

Statuses