From a7904c0b7bd2f5a6a0600fa137f34f93b0f5d237 Mon Sep 17 00:00:00 2001 From: Michael Savage Date: Thu, 7 Dec 2017 01:06:12 +0200 Subject: [PATCH] Incremental crypto_lock manual tweaks --- doc/man/man3/crypto_lock.3monocypher | 30 +++--- doc/man/man3/crypto_lock_init.3monocypher | 111 +++++++++++----------- 2 files changed, 73 insertions(+), 68 deletions(-) diff --git a/doc/man/man3/crypto_lock.3monocypher b/doc/man/man3/crypto_lock.3monocypher index 0f8a015..170b353 100644 --- a/doc/man/man3/crypto_lock.3monocypher +++ b/doc/man/man3/crypto_lock.3monocypher @@ -6,7 +6,7 @@ .Nm crypto_aead_unlock , .Nm crypto_lock , .Nm crypto_unlock -.Nd authenticated encryption (optionally with additional data) +.Nd authenticated encryption with additional data .Sh SYNOPSIS .In monocypher.h .Ft void @@ -197,19 +197,6 @@ crypto_wipe(key, 32); /* Transmit cipher_text, nonce, and mac over the network */ .Ed .Pp -Encryption (in place): -.Bd -literal -offset indent -const uint8_t key [32]; /* Random, secret session key */ -const uint8_t nonce[24]; /* Use only once per key */ -uint8_t *plain_text; /* Secret message */ -size_t text_size; /* Message size (NOT secret) */ -uint8_t mac [16]; /* Message authentication code */ -crypto_lock(mac, plain_text, key, nonce, plain_text, text_size); -/* Wipe secrets if they are no longer needed */ -crypto_wipe(key, 32); -/* Transmit plain_text, nonce, and mac over the network */ -.Ed -.Pp To decrypt the above: .Bd -literal -offset indent const uint8_t key [32]; /* Same as the above */ @@ -231,7 +218,20 @@ crypto_wipe(plain_text, text_size); crypto_wipe(key, 32); .Ed .Pp -To decrypt the above (in place): +In-place encryption: +.Bd -literal -offset indent +const uint8_t key [32]; /* Random, secret session key */ +const uint8_t nonce[24]; /* Use only once per key */ +uint8_t *plain_text; /* Secret message */ +size_t text_size; /* Message size (NOT secret) */ +uint8_t mac [16]; /* Message authentication code */ +crypto_lock(mac, plain_text, key, nonce, plain_text, text_size); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +/* Transmit plain_text, nonce, and mac over the network */ +.Ed +.Pp +In-place decryption: .Bd -literal -offset indent const uint8_t key [32]; /* Same as the above */ const uint8_t nonce[24]; /* Same as the above */ diff --git a/doc/man/man3/crypto_lock_init.3monocypher b/doc/man/man3/crypto_lock_init.3monocypher index ff5b1b5..b692347 100644 --- a/doc/man/man3/crypto_lock_init.3monocypher +++ b/doc/man/man3/crypto_lock_init.3monocypher @@ -64,43 +64,42 @@ and .Xr crypto_aead_unlock 3monocypher . Prefer those simpler functions if possible. .Pp -This incremental interface allows splitting up decryption and -authentication of messages too large to fit into a single buffer -or to handle individual pieces of data located in different buffers. -The arguments are the same as described for the direct interface on +This incremental interface can be used to encrypt and decrypt messages too +large to fit in a single buffer. +The arguments are the same as described for the direct interface described in .Xr crypto_lock 3monocypher . .Pp -This interface uses four steps: +Encryption requires four steps: .Bl -bullet .It -Initialisation with +Initialise a context with .Fn crypto_lock_init . -This sets up a context for encryption or decryption. -The same function is used for both. .It -Authentication with +Authenticate additional data, if any, with .Fn crypto_lock_auth . -This authenticates (or verifies) additional data, if any. .It -Update with -.Fn crypto_lock_update -for encryption, or -.Fn crypto_unlock_update -for decryption. -This encrypts (or decrypts) and authenticates (or verifies) part of -the secret message. +Encrypt and authenticate some data with +.Fn crypto_lock_update . .It -Finalisation with -.Fn crypto_lock_final -to generate the MAC, or -.Fn crypto_unlock_final -to verify the MAC. +Generate the MAC with +.Fn crypto_lock_final . .El .Pp -Because the incremental interface interleaves encryption and -authentication, it treats corrupted messages three times slower than -the direct interface. -Users who expect a high corruption rate may want a different approach. +Decryption also requires four steps: +.Bl -bullet +.It +Initialise a context with +.Fn crypto_lock_init . +.It +Verify additional data, if any, with +.Fn crypto_lock_auth . +.It +Decrypt and verify some data with +.Fn crypto_unlock_update . +.It +Verify the MAC with +.Fn crypto_unlock_final . +.El .Pp .Fn crypto_lock_encrypt encrypts or decrypts data @@ -127,25 +126,26 @@ They cannot fail. .Pp .Fn crypto_unlock_final returns 0 on success or -1 if the message was corrupted. -Corruption can happen because of transmission errors, programmer -error, or attacker interference. +Corruption can happen because of transmission errors, programmer error, or an +attacker's interference. .Em Always check the return value . .Sh EXAMPLES Encryption: .Bd -literal -offset indent -const uint8_t key [ 32]; /* session key */ -const uint8_t nonce [ 32]; /* unique per session key */ -const uint8_t ad [500]; /* optional additional data */ -const uint8_t plain_text [500]; /* secret message */ -uint8_t cipher_text[500]; /* encrypted message */ -uint8_t mac [ 16]; /* message authentication code */ +const uint8_t key [ 32]; /* Session key */ +const uint8_t nonce [ 32]; /* Unique per session key */ +const uint8_t ad [500]; /* Optional additional data */ +const uint8_t plain_text [500]; /* Secret message */ +uint8_t cipher_text[500]; /* Encrypted message */ +uint8_t mac [ 16]; /* Message authentication code */ /* Set up initial context */ crypto_lock_ctx ctx; crypto_lock_init(&ctx, key, nonce); -crypto_wipe(key, 32); /* wipe the key if no longer needed */ +/* Wipe the key if it is no longer needed */ +crypto_wipe(key, 32); -/* Authenticate additional data, if any */ +/* Authenticate additional data */ for (size_t i = 0; i < 500; i += 100) { crypto_lock_auth(&ctx, ad + i, 100); } @@ -153,7 +153,7 @@ for (size_t i = 0; i < 500; i += 100) { /* Encrypt message */ for (size_t i = 0; i < 500; i += 100) { crypto_lock_update(&ctx, cipher_text + i, plain_text + i, 100); - /* wipe the secret message if no longer needed */ + /* Wipe the secret message if it is no longer needed */ crypto_wipe(plain_text + i, 100); } @@ -163,19 +163,20 @@ crypto_lock_final(&ctx, mac); .Pp To decrypt the above: .Bd -literal -offset indent -const uint8_t key [ 32]; /* session key */ -const uint8_t nonce [ 32]; /* unique per session key */ -const uint8_t mac [ 16]; /* transmitted MAC */ -const uint8_t ad [500]; /* optional additional data */ -const uint8_t cipher_text[500]; /* encrypted message */ -uint8_t plain_text [500]; /* secret message */ +const uint8_t key [ 32]; /* Session key */ +const uint8_t nonce [ 32]; /* Unique per session key */ +const uint8_t mac [ 16]; /* Transmitted MAC */ +const uint8_t ad [500]; /* Optional additional data */ +const uint8_t cipher_text[500]; /* Encrypted message */ +uint8_t plain_text [500]; /* Secret message */ /* Set up initial context */ crypto_lock_ctx ctx; crypto_lock_init(&ctx, key, nonce); -crypto_wipe(key, 32); /* wipe the key if no longer needed */ +/* Wipe the key if it is no longer needed */ +crypto_wipe(key, 32); -/* Authenticate additional data, if any */ +/* Verify additional data */ for (size_t i = 0; i < 500; i += 100) { crypto_lock_auth(&ctx, ad + i, 100); } @@ -187,23 +188,27 @@ for (size_t i = 0; i < 500; i += 100) { /* Check the MAC */ if (crypto_unlock_final(&ctx, mac)) { - /* corrupted message, abort processing */ + /* Corrupted message, abort processing */ } else { - /* genuine message */ + /* Genuine message */ } + +/* Wipe the secret message if it is no longer needed */ +crypto_wipe(plain_text, 500); .Ed .Pp -In-place Encryption (without additional data for clarity): +In-place encryption without additional data: .Bd -literal -offset indent -const uint8_t key [ 32]; /* session key */ -const uint8_t nonce [ 32]; /* unique per session key */ -uint8_t text [500]; /* message */ -uint8_t mac [ 16]; /* message authentication code */ +const uint8_t key [ 32]; /* Session key */ +const uint8_t nonce [ 32]; /* Unique per session key */ +uint8_t text [500]; /* Message */ +uint8_t mac [ 16]; /* Message authentication code */ /* Set up initial context */ crypto_lock_ctx ctx; crypto_lock_init(&ctx, key, nonce); -crypto_wipe(key, 32); /* wipe the key if no longer needed */ +/* Wipe the key if it is no longer needed */ +crypto_wipe(key, 32); /* Encrypt message */ for (size_t i = 0; i < 500; i += 100) { -- 2.47.3