From bc249689934af3bd25d81fd0e0d8ff5f35cbfccb Mon Sep 17 00:00:00 2001 From: Frank Denis Date: Fri, 20 Jun 2014 00:07:12 -0700 Subject: [PATCH] Document ChaCha20Poly1305 --- README.markdown | 54 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/README.markdown b/README.markdown index 4f0c84fe..d9470a4e 100644 --- a/README.markdown +++ b/README.markdown @@ -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,