# `./fio-stl/152 chacha20poly1305.h`

7 public symbols.

### Functions

#### `fio_chacha20_poly1305_enc`

```c
void fio_chacha20_poly1305_enc(void *restrict mac, void *restrict data, size_t len, const void *ad, /* additional data */ size_t adlen, const void *key, const void *nonce)
```

Performs an in-place encryption of `data` using ChaCha20 with additional
data, producing a 16 byte message authentication code (MAC) using Poly1305.

* `key`    MUST point to a 256 bit long memory address (32 Bytes).
* `nonce` MUST point to a  96 bit long memory address (12 Bytes).
* `ad`     MAY be omitted, will NOT be encrypted.
* `data`   MAY be omitted, WILL be encrypted.
* `mac`    MUST point to a buffer with (at least) 16 available bytes.

_Symbol type:_ `function`

#### `fio_chacha20_poly1305_dec`

```c
int fio_chacha20_poly1305_dec(void *restrict mac, void *restrict data, size_t len, const void *ad, /* additional data */ size_t adlen, const void *key, const void *nonce)
```

Performs an in-place decryption of `data` using ChaCha20 after authenticating
the message authentication code (MAC) using Poly1305.

* `key`    MUST point to a 256 bit long memory address (32 Bytes).
* `nonce` MUST point to a  96 bit long memory address (12 Bytes).
* `ad`     MAY be omitted ONLY IF originally omitted.
* `data`   MAY be omitted, WILL be decrypted.
* `mac`    MUST point to a buffer where the 16 byte MAC is placed.

Returns `-1` on error (authentication failed).

_Symbol type:_ `function`

#### `fio_xchacha20_poly1305_enc`

```c
void fio_xchacha20_poly1305_enc(void *restrict mac, void *restrict data, size_t len, const void *ad, /* additional data */ size_t adlen, const void *key, const void *nonce)
```

Performs an in-place encryption of `data` using XChaCha20 with additional
data, producing a 16 byte message authentication code (MAC) using Poly1305.

XChaCha20 uses a 192-bit (24 byte) nonce, making it safe to use with
randomly-generated nonces without risk of nonce collision.

* `key`    MUST point to a 256 bit long memory address (32 Bytes).
* `nonce`  MUST point to a 192 bit long memory address (24 Bytes).
* `ad`     MAY be omitted, will NOT be encrypted.
* `data`   MAY be omitted, WILL be encrypted.
* `mac`    MUST point to a buffer with (at least) 16 available bytes.

_Symbol type:_ `function`

#### `fio_xchacha20_poly1305_dec`

```c
int fio_xchacha20_poly1305_dec(void *restrict mac, void *restrict data, size_t len, const void *ad, /* additional data */ size_t adlen, const void *key, const void *nonce)
```

Performs an in-place decryption of `data` using XChaCha20 after
authenticating the message authentication code (MAC) using Poly1305.

* `key`    MUST point to a 256 bit long memory address (32 Bytes).
* `nonce`  MUST point to a 192 bit long memory address (24 Bytes).
* `ad`     MAY be omitted ONLY IF originally omitted.
* `data`   MAY be omitted, WILL be decrypted.
* `mac`    MUST point to a buffer where the 16 byte MAC is placed.

Returns `-1` on error (authentication failed).

_Symbol type:_ `function`

#### `fio_xchacha20`

```c
void fio_xchacha20(void *restrict data, size_t len, const void *key, const void *nonce, uint32_t counter)
```

Performs an in-place encryption/decryption of `data` using XChaCha20.

XChaCha20 uses a 192-bit (24 byte) nonce, making it safe to use with
randomly-generated nonces without risk of nonce collision.

* `key`     MUST point to a 256 bit long memory address (32 Bytes).
* `nonce`   MUST point to a 192 bit long memory address (24 Bytes).
* `counter` is the block counter, usually 0 unless `data` is mid-cyphertext.

_Symbol type:_ `function`

#### `fio_chacha20`

```c
void fio_chacha20(void *restrict data, size_t len, const void *key, const void *nonce, uint32_t counter)
```

Performs an in-place encryption/decryption of `data` using ChaCha20.

* `key`    MUST point to a 256 bit long memory address (32 Bytes).
* `nonce` MUST point to a  96 bit long memory address (12 Bytes).
* `counter` is the block counter, usually 1 unless `data` is mid-cyphertext.

_Symbol type:_ `function`

#### `fio_poly1305_auth`

```c
void fio_poly1305_auth(void *restrict mac_dest, void *restrict message, size_t len, const void *ad, size_t ad_len, const void *key256bits)
```

Given a Poly1305 256bit (32 byte) key, writes the authentication code for the
poly message and additional data into `mac_dest`.

* `mac_dest` MUST point to a buffer with (at least) 16 available bytes.
* `message`  MAY be omitted.
* `ad`       MAY be omitted (additional data).
* `key`      MUST point to a 256 bit long memory address (32 Bytes).

_Symbol type:_ `function`

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