# Noise Keys

> UCall for C

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.

`#include <ucall/types.h>`

## ucall_security_t

Security modes for UCall server and client.

```c
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).

- `ucall_security_none_k`: No encryption, plain TCP/IP.
- `ucall_security_noise_xx_k`: Trust on first use - no pre-shared keys needed.
- `ucall_security_noise_ik_k`: Client knows server's public key in advance.
- `ucall_security_noise_kk_k`: Both 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](https://noiseprotocol.org/noise.html) for pattern specifications.

## ucall_noise_key_t

Noise protocol key (32 bytes for Curve25519).

```c
typedef ucall_byte_t ucall_noise_key_t[32];
```

## ucall_peer_authorizer_t

Decides whether a peer presenting a given static key may proceed past the handshake.

```c
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`](#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`](https://www.unum.cloud/docs/ucall/c/errors.md#ucall_status_success_k) admits the peer.

Statuses: - [`ucall_status_peer_rejected_k`](https://www.unum.cloud/docs/ucall/c/errors.md#ucall_status_peer_rejected_k) The plain refusal. Any other status refuses the peer too, and becomes the connection's outcome.

## ucall_noise_key_generate

Draws a fresh static keypair for `noise_private_key` fields and peer authorizers.

```c
void ucall_noise_key_generate(ucall_noise_key_generate_t *arguments);
```

Both outputs are zeroed unless the call succeeds.

- `outcome`: The verb's status, listed on the verb.
- `private_key`: Output for the secret scalar, drawn from the operating system's entropy.
- `public_key`: Output for the Curve25519 public key matching `private_key`.

Notes: __Thread-safe__.

Statuses: - [`ucall_status_invalid_argument_k`](https://www.unum.cloud/docs/ucall/c/errors.md#ucall_status_invalid_argument_k) An output is `NULL`.

## ucall_noise_key_derive

Derives the public key of a stored private key, as peer authorizers compare it.

```c
void ucall_noise_key_derive(ucall_noise_key_derive_t *arguments);
```

- `outcome`: Output for the outcome.
- `private_key`: The secret scalar, as `noise_private_key` fields take it.
- `public_key`: Output for the Curve25519 public key, which peers see during the handshake.

Notes: __Thread-safe__.

Statuses: - [`ucall_status_invalid_argument_k`](https://www.unum.cloud/docs/ucall/c/errors.md#ucall_status_invalid_argument_k) The `private_key` or the `public_key` output is `NULL`.