Welcome to little lamb

Code » limb » release » tree

[release] / src / doc / ccpl.h / ccpl_init.3.md 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
% limb manual
% ccpl_init(3)
% limb 0.1.0
% 2023-07-24

# NAME

ccpl\_init, ccpl\_aad, ccpl\_crypt, ccpl\_encrypt, ccpl\_decrypt, ccpl\_final -
encrypt/decrypt data using the ChaCha20-Poly1305 algorithm

# SYNOPSIS

    #include <limb/ccpl.h>

```pre hl
void ccpl_init(void *<em>key</em>, void *<em>nonce</em>, void *<em>ctx</em>)
int ccpl_aad(const void *<em>data</em>, size_t <em>dlen</em>, void *<em>ctx</em>)
void ccpl_crypt(void *<em>dst</em>, const void *<em>data</em>, size_t <em>dlen</em>, int <em>encrypt</em>, void *<em>ctx</em>)
void ccpl_encrypt(void *<em>dst</em>, const void *<em>data</em>, size_t <em>dlen</em>, void *<em>ctx</em>)
void ccpl_decrypt(void *<em>dst</em>, const void *<em>data</em>, size_t <em>dlen</em>, void *<em>ctx</em>)
void ccpl_final(void *<em>dst</em>, void *<em>ctx</em>)
```

# DESCRIPTION

The `ccpl_init`() function initializes the given ccpl context pointed by `ctx`
to encrypt/decrypt data using the ChaCha20-Poly1305 authenticated encryption
with additional data (AEAD) algorithm.

This implementation is conform to [RFC 8439][rfc8439], as such the key pointed
to by `key` must be 256bit/32 bytes long, and the nonce pointed.by `nonce` must
be 96bit/12 bytes long.

In order to be secure, the given `nonce` must be different for each invocation
with the same `key`.

Limitations of message length are the same as described in [chacha20_init](3),
however an additional limitation, specific to this combined algorithm, also
applies, and brings the maximum size of both the additional data and the
encrypted data to 2^64 bytes each.

[rfc8439]: https://datatracker.ietf.org/doc/html/rfc8439

First, the `ccpl_aad`() function must be used to feed additional data pointed by
`data` of length `dlen` into the ccpl context pointed by `ctx`. Such data will
not be encrypted, but will be covered by the authentication code generated using
the Poly1305 algorithm.
You can call this function as many times as needed.

Then, the `ccpl_crypt`() function can be used to either encrypt or decrypt data
pointed by `data` of length `dlen` into the memory pointed by `dst` (which must
be able to store `dlen` bytes).

As with [chacha20_crypt](3) it is possible to use the same memory area for both
`data` and `dst`, and have it processed in-place.

Though the data processing is the same for encrypting and decrypting using the
ChaCha20 cipher, a difference is made regarding the Poly1305 MAC, as it is
always the /encrypted/ data that must be fed into it.
This is why the argument `encrypt` is needed, and must be a set to 1 when
encrypting data (thus feeding it to Poly1305 /after/ processing through
the ChaCha20 cipher), and set to 0 when decrypting data (thus feeding it to
Poly1305 /before/ processing through the ChaCha20 cipher).

All calls must be either of encrypting or decrypting, mixing both is invalid.
However, you can call the function (with the same value for `encrypt`) as many
times as needed.

As a convenience, the `ccpl_encrypt`() and `ccpl_decrypt`() macros are provided.

! Additional Data First
! It is required that all additional data - fed through the `ccpl_aad`()
! function - be fed into the ccpl `ctx` /before/ any call is made to
! `ccpl_crypt`().

The `ccpl_final`() function stores the computed Poly1305-based MAC from `ctx`
in binary form into `dst`, which must be able to store 16 bytes.

When decrypting data, the stored MAC should be compared to the one accompanying
the data. If bitwise identical, both the decrypted data and the additional data
fed into the ccpl `ctx` have been authenticated.

# RETURN VALUE

The `ccpl_aad`() function returns 1 on success, and 0 on failure. The only
possible failure case is if a call to `ccpl_crypt`() has already been made for
the same context.

# SEE ALSO

[chacha20_init](3), [poly1305_init](3)