# `./fio-stl/154 ed25519.h`

13 public symbols.

### Macros

#### `FIO_X25519_CIPHERTEXT_LEN`

```c
#define FIO_X25519_CIPHERTEXT_LEN(message_len) ((message_len) + 48)
```

Returns the ciphertext length for a given plaintext length.
Ciphertext = ephemeral_pk (32) + mac (16) + encrypted_message (message_len)

_Symbol type:_ `macro`

#### `FIO_X25519_PLAINTEXT_LEN`

```c
#define FIO_X25519_PLAINTEXT_LEN(ciphertext_len)   \
  ((ciphertext_len) > 48 ? ((ciphertext_len)-48) : 0)
```

Returns the plaintext length for a given ciphertext length.
Returns 0 if ciphertext_len < 48 (invalid ciphertext).

_Symbol type:_ `macro`

### Functions

#### `fio_ed25519_keypair`

```c
void fio_ed25519_keypair(uint8_t secret_key[32], uint8_t public_key[32])
```

Generates a new random Ed25519 key pair.

The secret key must be kept secret and securely erased when no longer
needed. The public key can be freely shared.

_Symbol type:_ `function`

#### `fio_ed25519_public_key`

```c
void fio_ed25519_public_key(uint8_t public_key[32], const uint8_t secret_key[32])
```

Derives the public key from an Ed25519 secret key.

Useful when the secret key is loaded from storage and the public key
needs to be recomputed.

_Symbol type:_ `function`

#### `fio_ed25519_sign`

```c
int fio_ed25519_sign(uint8_t signature[64], const void *message, size_t len, const uint8_t secret_key[32], const uint8_t public_key[32])
```

Signs a message using Ed25519.

The signature is 64 bytes and is deterministic (same message + key = same
signature).

_Symbol type:_ `function`

#### `fio_ed25519_verify`

```c
int fio_ed25519_verify(const uint8_t signature[64], const void *message, size_t len, const uint8_t public_key[32])
```

Verifies an Ed25519 signature.

Returns 0 on success (valid signature), -1 on failure (invalid signature).

_Symbol type:_ `function`

#### `fio_x25519_keypair`

```c
void fio_x25519_keypair(uint8_t secret_key[32], uint8_t public_key[32])
```

Generates a new random X25519 key pair.

The secret key must be kept secret. The public key can be shared with
the other party for key exchange.

_Symbol type:_ `function`

#### `fio_x25519_public_key`

```c
void fio_x25519_public_key(uint8_t public_key[32], const uint8_t secret_key[32])
```

Derives the public key from an X25519 secret key.

This performs scalar multiplication of the secret key with the base point.

_Symbol type:_ `function`

#### `fio_x25519_shared_secret`

```c
int fio_x25519_shared_secret(uint8_t shared_secret[32], const uint8_t secret_key[32], const uint8_t their_public_key[32])
```

Computes a shared secret using X25519 (ECDH).

Both parties compute the same shared secret:
  shared = X25519(my_secret, their_public)

The shared secret should be passed through a KDF (e.g., HKDF with SHA-256)
before being used as an encryption key.

Returns 0 on success, -1 on failure (e.g., if their_public is a low-order
point, which would result in an all-zero shared secret).

_Symbol type:_ `function`

#### `fio_ed25519_sk_to_x25519`

```c
void fio_ed25519_sk_to_x25519(uint8_t x_secret_key[32], const uint8_t ed_secret_key[32])
```

Converts an Ed25519 secret key to an X25519 secret key.

This allows using an Ed25519 signing key for X25519 key exchange.

_Symbol type:_ `function`

#### `fio_ed25519_pk_to_x25519`

```c
void fio_ed25519_pk_to_x25519(uint8_t x_public_key[32], const uint8_t ed_public_key[32])
```

Converts an Ed25519 public key to an X25519 public key.

This allows encrypting to someone who has only shared their Ed25519
signing public key.

_Symbol type:_ `function`

#### `fio_x25519_encrypt`

```c
int fio_x25519_encrypt(uint8_t *ciphertext, const void *message, size_t message_len, fio_crypto_enc_fn encryption_function, const uint8_t recipient_pk[32])
```

Encrypts a message using the recipient's X25519 public key.

The ciphertext includes:
- 32 bytes: ephemeral public key (for key agreement)
- 16 bytes: authentication tag (MAC)
- N bytes:  encrypted message

Total ciphertext size = message_len + 48 bytes

**Parameters:**
- `ciphertext` - Output buffer (must be at least message_len + 48 bytes)
- `message` - The plaintext message to encrypt
- `message_len` - Length of the message
- `encryption_function` - Encryption function (fio_chacha20_poly1305_enc)
- `recipient_pk` - The recipient's X25519 public key (32 bytes)

**Returns:**
- 0 on success, -1 on failure

_Symbol type:_ `function`

#### `fio_x25519_decrypt`

```c
int fio_x25519_decrypt(uint8_t *plaintext, const uint8_t *ciphertext, size_t ciphertext_len, fio_crypto_dec_fn decryption_function, const uint8_t recipient_sk[32])
```

Decrypts a message using the recipient's X25519 secret key.

**Parameters:**
- `plaintext` - Output buffer (must be at least ciphertext_len - 48 bytes)
- `ciphertext` - The ciphertext (ephemeral_pk || mac || encrypted_data)
- `ciphertext_len` - Length of the ciphertext (must be >= 48)
- `decryption_function` - Decryption function (fio_chacha20_poly1305_dec)
- `recipient_sk` - The recipient's X25519 secret key (32 bytes)

**Returns:**
- 0 on success, -1 on failure (authentication failed or invalid input)

_Symbol type:_ `function`

-----------------------------------------------------