Welcome to little lamb

Code » limb » master » tree

[master] / src / doc / chacha20.h / chacha20_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
% limb manual
% chacha20_init(3)
% limb 0.1.0
% 2023-07-24

# NAME

chacha20\_init, chacha20\_crypt, chacha20\_clear, chacha20 - encrypt/decrypt a
message using ChaCha20 cipher

# SYNOPSIS

    #include <limb/chacha20.h>

```pre hl
void chacha20_init(const void *<em>key</em>, const void *<em>nonce</em>, void *<em>ctx</em>)
void chacha20_crypt(void *<em>dst</em>, const void *<em>msg</em>, size_t <em>mlen</em>, void *<em>ctx</em>)

void chacha20_clear(void *<em>ctx</em>)
void chacha20(void *<em>dst</em>, const void *<em>key</em>, const void *<em>nonce</em>, const void *<em>msg</em>, size_t <em>mlen</em>)
```

# DESCRIPTION

The `chacha20_init`() function initializes the given chacha20 context `ctx` to
encrypt/decrypt a message using the ChaCha20 cipher.

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 to by `nonce`
must be 96bit/12 bytes long.

However, it also conforms to the [original description][chacha20] by Daniel J.
Bernstein, as long as the given nonce has its first 32bit/4 bytes set to zero.

In the former case, the message length shall not be more than 2^38 bytes. In
the later case, the message length shall not be more than 2^70 bytes.

[rfc8439]: https://datatracker.ietf.org/doc/html/rfc8439
[chacha20]: https://cr.yp.to/chacha/chacha-20080128.pdf


The `chacha20_crypt`() function processed the `mlen` bytes pointed to by `msg`,
encrypting or decrypting them (it's the same operation : plain text will be
encrypted, encrypted data will be decrypted back into plain text, assuming the
same `key` and `nonce` are used of course.) into the memory pointed to by `dst`
(which must be at least `mlen` bytes long).

It is possible to use the same memory area for both `msg` and `dst`, and have it
processed in-place. The function can be called as many times as needed.

The `chacha20_clear`() function simply clears the memory behind the `ctx`
context. In order to process another message, one can simply call
`chacha20_init`() on a previously used context without the need to clear it
first.

The `chacha20`() function can be used as convenience if the entire message can
be stored in a continuous memory area, to encrypt/decrypt it in a single call.

# SEE ALSO

[ccpl_init](3)