From: Loup Vaillant Date: Sun, 15 Jan 2023 17:56:42 +0000 (+0100) Subject: Update crypto_aead_*() documentation X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=7e1f3a72c1d0a9544e3039b1fe44bfa12d40c398;p=Monocypher.git Update crypto_aead_*() documentation --- diff --git a/doc/man/man3/crypto_aead_init_djb.3monocypher b/doc/man/man3/crypto_aead_init_djb.3monocypher new file mode 120000 index 0000000..52fef1a --- /dev/null +++ b/doc/man/man3/crypto_aead_init_djb.3monocypher @@ -0,0 +1 @@ +crypto_aead_lock.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_aead_init_ietf.3monocypher b/doc/man/man3/crypto_aead_init_ietf.3monocypher new file mode 120000 index 0000000..52fef1a --- /dev/null +++ b/doc/man/man3/crypto_aead_init_ietf.3monocypher @@ -0,0 +1 @@ +crypto_aead_lock.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_lock.3monocypher b/doc/man/man3/crypto_aead_lock.3monocypher similarity index 59% rename from doc/man/man3/crypto_lock.3monocypher rename to doc/man/man3/crypto_aead_lock.3monocypher index 5d3ce48..95497dc 100644 --- a/doc/man/man3/crypto_lock.3monocypher +++ b/doc/man/man3/crypto_aead_lock.3monocypher @@ -8,7 +8,7 @@ .\" .\" ---------------------------------------------------------------------------- .\" -.\" Copyright (c) 2017-2019 Loup Vaillant +.\" Copyright (c) 2017-2019, 2023 Loup Vaillant .\" Copyright (c) 2017-2018 Michael Savage .\" Copyright (c) 2017, 2019-2022 Fabio Scotoni .\" All rights reserved. @@ -40,7 +40,7 @@ .\" .\" ---------------------------------------------------------------------------- .\" -.\" Written in 2017-2022 by Loup Vaillant, Michael Savage and Fabio Scotoni +.\" Written in 2017-2023 by Loup Vaillant, Michael Savage and Fabio Scotoni .\" .\" To the extent possible under law, the author(s) have dedicated all copyright .\" and related neighboring rights to this software to the public domain @@ -50,7 +50,7 @@ .\" with this software. If not, see .\" .\" -.Dd February 13, 2022 +.Dd January 15, 2023 .Dt CRYPTO_LOCK 3MONOCYPHER .Os .Sh NAME @@ -63,38 +63,58 @@ .In monocypher.h .Ft void .Fo crypto_lock -.Fa "uint8_t mac[16]" .Fa "uint8_t *cipher_text" +.Fa "uint8_t mac[16]" .Fa "const uint8_t key[32]" .Fa "const uint8_t nonce[24]" +.Fa "const uint8_t *ad" +.Fa "size_t ad_size" .Fa "const uint8_t *plain_text" .Fa "size_t text_size" .Fc .Ft int .Fo crypto_unlock .Fa "uint8_t *plain_text" +.Fa "const uint8_t mac[16]" .Fa "const uint8_t key[32]" .Fa "const uint8_t nonce[24]" -.Fa "const uint8_t mac[16]" +.Fa "const uint8_t *ad" +.Fa "size_t ad_size" .Fa "const uint8_t *cipher_text" .Fa "size_t text_size" .Fc .Ft void -.Fo crypto_lock_aead -.Fa "uint8_t mac[16]" -.Fa "uint8_t *cipher_text" +.Fo crypto_aead_init_x +.Fa "crypto_aead_ctx *ctx" .Fa "const uint8_t key[32]" .Fa "const uint8_t nonce[24]" +.Fc +.Ft void +.Fo crypto_aead_init_djb +.Fa "crypto_aead_ctx *ctx" +.Fa "const uint8_t key[32]" +.Fa "const uint8_t nonce[8]" +.Fc +.Ft void +.Fo crypto_aead_init_ietf +.Fa "crypto_aead_ctx *ctx" +.Fa "const uint8_t key[32]" +.Fa "const uint8_t nonce[12]" +.Fc +.Ft void +.Fo crypto_aead_write +.Fa "crypto_aead_ctx *ctx" +.Fa "uint8_t *cipher_text" +.Fa "uint8_t mac[16]" .Fa "const uint8_t *ad" .Fa "size_t ad_size" .Fa "const uint8_t *plain_text" .Fa "size_t text_size" .Fc .Ft int -.Fo crypto_unlock_aead +.Fo crypto_aead_read +.Fa "crypto_aead_ctx *ctx" .Fa "uint8_t *plain_text" -.Fa "const uint8_t key[32]" -.Fa "const uint8_t nonce[24]" .Fa "const uint8_t mac[16]" .Fa "const uint8_t *ad" .Fa "size_t ad_size" @@ -102,10 +122,10 @@ .Fa "size_t text_size" .Fc .Sh DESCRIPTION -.Fn crypto_lock +.Fn crypto_aead_lock encrypts and authenticates a plaintext. It can be decrypted by -.Fn crypto_unlock . +.Fn crypto_aead_unlock . The arguments are: .Bl -tag -width Ds .It Fa key @@ -118,7 +138,7 @@ password-based key derivation or even meeting physically. See .Xr crypto_x25519 3monocypher -for a bulding block for a key exchange protocol and +for a building block for a key exchange protocol and .Xr crypto_argon2i 3monocypher for password-based key derivation. .It Fa nonce @@ -135,6 +155,17 @@ See .Xr intro 3monocypher about random number generation (use your operating system's random number generator). +.Pp +Note: +.Fn crypto_aead_init_djb +and +.Fn crypto_aead_init_ietf +use shorter nonces +(8 and 12 bytes respectively), +which +.Em cannot +be selected at random without risking a catastrophic reuse. +For those shorter nonces, use a counter instead. .It Fa mac A 16-byte .Em message authentication code @@ -143,6 +174,19 @@ This guarantee cannot be upheld if a nonce has been reused with the session key because doing so allows the attacker to learn the authentication key associated with that nonce. The MAC is intended to be sent along with the ciphertext. +.It Fa ad +Additional data to authenticate. +It will +.Em not +be encrypted. +This is used to authenticate relevant data that cannot be encrypted. +May be +.Dv NULL +if +.Fa ad_size +is zero. +.It Fa ad_size +Length of the additional data, in bytes. .It Fa plain_text The secret message. Its contents will be kept hidden from attackers. @@ -168,53 +212,76 @@ and arguments may point to the same buffer for in-place encryption. Otherwise, the buffers they point to must not overlap. .Pp -.Fn crypto_unlock +.Fn crypto_aead_unlock first checks the integrity of an encrypted message. If it has been corrupted, -.Fn crypto_unlock -returns -1 immediately. -Otherwise, it decrypts the message then returns zero. +.Fn crypto_aead_unlock +does nothing and returns -1 immediately. +Otherwise it decrypts the message then returns zero. .Em Always check the return value . +.Ss Incremental interface +For long messages that may not fit in memory, +first initialise a context with +.Fn crypto_aead_init_x , +then encrypt each chunk with +.Fn crypto_aead_write. +The receiving end will initialise its own context with +.Fn crypto_aead_init_x , +then decrypt each chunk with +.Fn crypto_aead_read. .Pp -.Fn crypto_lock_aead +Just like +.Fn crypto_aead_unlock , +.Fn crypto_aead_read +first checks the integrity of the encrypted chunk, +then returns -1 immediately if it has been corrupted. +Otherwise it decrypts the chunk then returns zero. +.Em Always check the return value . +.Pp +The encryption key is changed between each chunk, +providing a symmetric ratchet that enforces the order of the messages. +Attackers cannot reorder chunks without +.Fn crypto_aead_read +noticing. +.Sy Truncation however is not detected . +You must detect the last chunk manually. +Possible methods include using +.Fa ad +to mark the last chunk differently, +prefixing all plaintext messages with a marking byte +(and use a different marking byte for the last chunk), +or sending the total message size up front and encode the remaining size +in +.Fa ad . +Once the last chunk is sent or received, wipe the context with +.Xr crypto_wipe 3monocypher . +.Pp +.Fn crypto_aead_init_djb and -.Fn crypto_unlock_aead +.Fn crypto_aead_init_ietf are variants of -.Fn crypto_lock -and -.Fn crypto_unlock , -permitting additional data. -Additional data is authenticated but -.Em not -encrypted. -This is used to authenticate relevant data that cannot be encrypted. -The arguments are: -.Bl -tag -width Ds -.It Fa ad -Additional data to authenticate. -It will not be encrypted. -May be -.Dv NULL -if -.Fa ad_size -is zero. -Setting -.Fa ad_size -to zero yields the same results as -.Fn crypto_lock -and -.Fn crypto_unlock . -.It Fa ad_size -Length of the additional data, in bytes. -.El +.Fn crypto_aead_init_x +with a shorter nonce. +.Em Those nonces are too short to be selected at random . +Use a counter instead. +.Pp +In addition to its short nonce, +.Fn crypto_aead_init_ietf +has a smaller internal counter that limits the size of chunks to +256GiB. +Exceeding this size leaks the contents of the chunk. +It is provided strictly for compatibility with RFC 8439. .Sh RETURN VALUES -.Fn crypto_lock +.Fn crypto_aead_lock , +.Fn crypto_aead_init_x , +.Fn crypto_aead_init_djb , +.Fn crypto_aead_init_ietf , and -.Fn crypto_lock_aead +.Fn crypto_aead_write return nothing. -.Fn crypto_unlock +.Fn crypto_aead_unlock and -.Fn crypto_unlock_aead +.Fn crypto_aead_read return 0 on success or -1 if the message was corrupted (i.e. .Fa mac mismatched the combination of @@ -246,8 +313,10 @@ uint8_t mac [16]; /* Message authentication code */ uint8_t cipher_text[12]; /* Encrypted message */ arc4random_buf(key, 32); arc4random_buf(nonce, 24); -crypto_lock(mac, cipher_text, key, nonce, plain_text, - sizeof(plain_text)); +crypto_aead_lock(cipher_text, mac, + key, nonce, + NULL, 0, + plain_text, sizeof(plain_text)); /* Wipe secrets if they are no longer needed */ crypto_wipe(plain_text, 12); crypto_wipe(key, 32); @@ -263,7 +332,10 @@ uint8_t nonce [24]; /* Same as the above */ const uint8_t cipher_text[12]; /* Encrypted message */ const uint8_t mac [16]; /* Received along with text */ uint8_t plain_text [12]; /* Secret message */ -if (crypto_unlock(plain_text, key, nonce, mac, cipher_text, 12)) { +if (crypto_aead_unlock(plain_text, mac, + key, nonce, + NULL, 0, + cipher_text, sizeof(plain_text))) { /* The message is corrupted. * Wipe key if it is no longer needed, * and abort the decryption. @@ -285,7 +357,10 @@ uint8_t text [12] = "Lorem ipsum"; /* Secret message */ uint8_t mac [16]; /* Message authentication code */ arc4random_buf(key, 32); arc4random_buf(nonce, 24); -crypto_lock(mac, text, key, nonce, text, 12); +crypto_aead_lock(text, mac, + key, nonce, + NULL, 0, + text, sizeof(text)); /* Wipe secrets if they are no longer needed */ crypto_wipe(key, 32); /* Transmit cipher_text, nonce, and mac over the network, @@ -299,17 +374,69 @@ uint8_t key [32]; /* Same as the above */ const uint8_t nonce[24]; /* Same as the above */ const uint8_t mac [16]; /* Received from along with text */ uint8_t text [12]; /* Message to decrypt */ -if (crypto_unlock(text, key, nonce, mac, text, 12)) { - /* The message is corrupted. - * Wipe key if it is no longer needed, - * and abort the decryption. - */ - crypto_wipe(key, 32); +if (crypto_aead_unlock(text, mac, key, nonce, + NULL, 0 + text, sizeof(text))) { + /* The message is corrupted. + * Wipe key if it is no longer needed, + * and abort the decryption. + */ + crypto_wipe(key, 32); } else { - /* ...do something with the decrypted text here... */ - /* Finally, wipe secrets if they are no longer needed */ - crypto_wipe(text, 12); - crypto_wipe(key, 32); + /* ...do something with the decrypted text here... */ + /* Finally, wipe secrets if they are no longer needed */ + crypto_wipe(text, 12); + crypto_wipe(key, 32); +} +.Ed +.Pp +Encrypt one message with the incremental interface: +.Bd -literal -offset indent +uint8_t key [32]; /* Random, secret session key */ +uint8_t nonce [24]; /* Use only once per key */ +uint8_t plain_text [12] = "Lorem ipsum"; /* Secret message */ +uint8_t mac [16]; /* Message authentication code */ +uint8_t cipher_text[12]; /* Encrypted message */ +arc4random_buf(key, 32); +arc4random_buf(nonce, 24); +crypto_aead_ctx ctx; +crypto_aead_init_x(&ctx, key, nonce); +crypto_aead_write(&ctx, cipher_text, mac, + NULL, 0, + plain_text, sizeof(plain_text)) +/* Wipe secrets if they are no longer needed */ +crypto_wipe(plain_text, 12); +crypto_wipe(key, 32); +crypto_wipe(&ctx, sizeof(ctx)); +/* Transmit cipher_text, nonce, and mac over the network, + * store them in a file, etc. + */ +.Ed +.Pp +To decrypt the above: +.Bd -literal -offset indent +uint8_t key [32]; /* Same as the above */ +uint8_t nonce [24]; /* Same as the above */ +const uint8_t cipher_text[12]; /* Encrypted message */ +const uint8_t mac [16]; /* Received along with text */ +uint8_t plain_text [12]; /* Secret message */ +crypto_aead_ctx ctx; +crypto_aead_init_x(&ctx, key, nonce); +if (crypto_aead_read(&ctx, plain_text, mac, + NULL, 0, + cipher_text, sizeof(plain_text))) { + /* The message is corrupted. + * Wipe key if it is no longer needed, + * and abort the decryption. + */ + crypto_wipe(key, 32); + crypto_wipe(&ctx, sizeof(ctx)); +} else { + /* ...do something with the decrypted text here... */ + /* Finally, wipe secrets if they are no longer needed */ + crypto_wipe(plain_text, 12); + crypto_wipe(key, 32); + crypto_wipe(&ctx, sizeof(ctx)); } .Ed .Sh SEE ALSO @@ -317,10 +444,18 @@ if (crypto_unlock(text, key, nonce, mac, text, 12)) { .Xr crypto_wipe 3monocypher , .Xr intro 3monocypher .Sh STANDARDS -These functions implement RFC 8439, with XChaCha20 instead of ChaCha20. -XChaCha20 derives from ChaCha20 the same way XSalsa20 derives from -Salsa20 and benefits from the same security reduction (proven secure -as long as ChaCha20 itself is secure). +These functions implement RFC 8439. +.Fn crypto_aead_lock +and +.Fn crypto_aead_init_x , +use XChaCha20 instead of ChaCha20. +.Fn crypto_aead_init_djb +uses a 64-bit nonce and a 64-bit counter. +.Fn crypto_aead_init_ietf +is fully compatible with the RFC. +Note that XChaCha20 derives from ChaCha20 the same way XSalsa20 derives +from Salsa20 and benefits from the same security reduction +(proven secure as long as ChaCha20 itself is secure). .Sh HISTORY The .Fn crypto_lock @@ -340,3 +475,10 @@ The and .Fn crypto_lock_auth functions were removed in Monocypher 2.0.0. +In Monocypher 4.0.0, the +.Fn crypto_lock +and +.Fn crypto_unlock +were removed, +Functions were renamed and arguments reordered for consistency, +and the incremental interface was added. diff --git a/doc/man/man3/crypto_aead_read.3monocypher b/doc/man/man3/crypto_aead_read.3monocypher new file mode 120000 index 0000000..52fef1a --- /dev/null +++ b/doc/man/man3/crypto_aead_read.3monocypher @@ -0,0 +1 @@ +crypto_aead_lock.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_aead_unlock.3monocypher b/doc/man/man3/crypto_aead_unlock.3monocypher new file mode 120000 index 0000000..52fef1a --- /dev/null +++ b/doc/man/man3/crypto_aead_unlock.3monocypher @@ -0,0 +1 @@ +crypto_aead_lock.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_aead_write.3monocypher b/doc/man/man3/crypto_aead_write.3monocypher new file mode 120000 index 0000000..52fef1a --- /dev/null +++ b/doc/man/man3/crypto_aead_write.3monocypher @@ -0,0 +1 @@ +crypto_aead_lock.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_lock_aead.3monocypher b/doc/man/man3/crypto_lock_aead.3monocypher deleted file mode 120000 index 126507a..0000000 --- a/doc/man/man3/crypto_lock_aead.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_lock.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_unlock.3monocypher b/doc/man/man3/crypto_unlock.3monocypher deleted file mode 120000 index 126507a..0000000 --- a/doc/man/man3/crypto_unlock.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_lock.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_unlock_aead.3monocypher b/doc/man/man3/crypto_unlock_aead.3monocypher deleted file mode 120000 index 126507a..0000000 --- a/doc/man/man3/crypto_unlock_aead.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_lock.3monocypher \ No newline at end of file diff --git a/src/monocypher.h b/src/monocypher.h index 77e2d43..15f1f3e 100644 --- a/src/monocypher.h +++ b/src/monocypher.h @@ -99,9 +99,9 @@ int crypto_aead_unlock(uint8_t *plain_text, // Authenticated stream // -------------------- typedef struct { - uint64_t counter; - uint8_t key[32]; - uint8_t nonce[8]; + uint64_t counter; + uint8_t key[32]; + uint8_t nonce[8]; } crypto_aead_ctx; void crypto_aead_init_x(crypto_aead_ctx *ctx,