kevin/libsodium
1
Fork 0
mirror of https://github.com/jedisct1/libsodium.git synced 2024-12-19 10:05:05 -07:00
Code Releases Wiki Activity

Document ChaCha20Poly1305

Browse Source
This commit is contained in:
Frank Denis 2014-06-20 00:07:12 -07:00
parent 5e89fc9303
commit bc24968993
1 changed files with 54 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
README.markdown
View File

@ -360,6 +360,60 @@ The plaintext password should be locked in memory using
`sodium_mlock()` and immediately zeroed out and unlocked after this
function returns, using `sodium_munlock()`.
## ChaCha20Poly1305
Sodium supports the ChaCha20Poly1305 Authenticated Encryption with
Additional Data (AEAD) construction, as documented in the
[nir-cfrg-chacha20-poly1305-04](http://tools.ietf.org/html/draft-nir-cfrg-chacha20-poly1305-04)
draft.
int crypto_secretbox_chacha20poly1305_ad(unsigned char *c,
const unsigned char *m,
unsigned long long mlen,
const unsigned char *ad,
unsigned long long adlen,
const unsigned char *n,
const unsigned char *k);
This function encrypts the message `m` of length `mlen` with the key
`k` (whose size is `crypto_secretbox_chacha20poly1305_KEYBYTES` bytes)
and nonce `n` (whose size is `crypto_secretbox_chacha20poly1305_NONCEBYTES`).
`c` must be at least `mlen + crypto_secretbox_chacha20poly1305_ZEROBYTES` long.
The function fills the first bytes of `c` with a tag authenticating both the
encrypted message and additional data `ad` whose length is `adlen` bytes.
The output of the previous function can be verified and decrypted using:
int crypto_secretbox_chacha20poly1305_ad_open(unsigned char *m,
const unsigned char *c,
unsigned long long clen,
const unsigned char *ad,
unsigned long long adlen,
const unsigned char *n,
const unsigned char *k);
`clen` is the length of the ciphertext, as generated by the previous
function: it is equal to the length of the plaintext message +
`crypto_secretbox_chacha20poly1305_ZEROBYTES`.
If the MAC can be verified, the plaintext is copied to `m` and the
function returns `0`.
If the verification fails, the function returns `-1`.
The length of the additional data can be `0`. Alternatively, the
`crypto_secretbox_chacha20poly1305()` and
`crypto_secretbox_chacha20poly1305_open()` variants can be used.
In order to be consistent with the `secretbox` API, the MAC is stored
*before* the encrypted message. This differs from the
draft on ChaCha20 and Poly1305 for IETF protocols, which stores the
MAC *after* the encrypted message.
However, the MAC is computed using the same algorithm, and can be
moved after message if interoperability with other implementations is required.
## Constants available as functions
In addition to constants for key sizes, output sizes and block sizes,