From: Michael Savage Date: Wed, 3 Jan 2018 20:55:06 +0000 (+0200) Subject: Use "Length of .Fa x , in bytes." X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=b41a61197f3b843ca3b0a343a25af234e5845451;p=Monocypher.git Use "Length of .Fa x , in bytes." --- diff --git a/doc/man/man3/crypto_argon2i.3monocypher b/doc/man/man3/crypto_argon2i.3monocypher index 9c148ce..3851d2e 100644 --- a/doc/man/man3/crypto_argon2i.3monocypher +++ b/doc/man/man3/crypto_argon2i.3monocypher @@ -52,7 +52,9 @@ The arguments are: .It Fa hash Buffer for the output hash. .It Fa hash_size -The length of the output hash, in bytes. +The length of +.Fa hash , +in bytes. This argument should be set to 16, 32 or 64 for compatibility with the .Fn crypto_verify* constant time comparison functions. diff --git a/doc/man/man3/crypto_blake2b.3monocypher b/doc/man/man3/crypto_blake2b.3monocypher index 4020afc..a28f60e 100644 --- a/doc/man/man3/crypto_blake2b.3monocypher +++ b/doc/man/man3/crypto_blake2b.3monocypher @@ -61,7 +61,9 @@ The arguments are: .It Fa hash The output hash. .It Fa hash_size -Length of the output hash, in bytes. +Length of +.Fa hash , +in bytes. Must be between 1 and 64. 64 is recommended. Anything below 32 is discouraged. @@ -85,7 +87,9 @@ Users may want to wipe the key with .Xr crypto_wipe 3monocypher once they are done with it. .It Fa key_size -Length of the secret key, in bytes. +Length of +.Fa key , +in bytes. Must be between 0 and 64. 32 is a good default. .It Fa message @@ -94,7 +98,9 @@ May overlap with the .Fa hash argument. .It Fa message_size -The length of the message, in bytes. +Length of +.Fa message , +in bytes. .El .Ss Direct interface The direct interface has two functions, @@ -151,8 +157,6 @@ Hashing a message all at once: uint8_t hash [ 64]; /* Output hash (64 bytes) */ uint8_t message[500]; /* Message to hash */ crypto_blake2b(hash, message, 500); -/* Wipe secrets if they are no longer needed */ -crypto_wipe(message, 500); .Ed .Pp Computing a message authentication code all at once: @@ -174,8 +178,6 @@ crypto_blake2b_ctx ctx; crypto_blake2b_init(&ctx); for (size_t i = 0; i < 500; i += 100) { crypto_blake2b_update(&ctx, message + i, 100); - /* Wipe secrets if they are no longer needed */ - crypto_wipe(message + i, 100); } crypto_blake2b_final(&ctx, hash); .Ed diff --git a/doc/man/man3/crypto_chacha20_encrypt.3monocypher b/doc/man/man3/crypto_chacha20_encrypt.3monocypher index 4ae7ce2..02a2b4e 100644 --- a/doc/man/man3/crypto_chacha20_encrypt.3monocypher +++ b/doc/man/man3/crypto_chacha20_encrypt.3monocypher @@ -83,7 +83,9 @@ in bytes. .It Fa stream The raw Chacha20 stream. .It Fa stream_size -The size of the stream, in bytes. +The size of +.Fa stream , +in bytes. .It Fa ctr The number of 64-byte blocks since the beginning of the stream. .El diff --git a/doc/man/man3/crypto_key_exchange.3monocypher b/doc/man/man3/crypto_key_exchange.3monocypher index 1ef3db5..a35bf8f 100644 --- a/doc/man/man3/crypto_key_exchange.3monocypher +++ b/doc/man/man3/crypto_key_exchange.3monocypher @@ -45,7 +45,7 @@ The public keys are different, and revealing both may leak information. The public key of the other party. .It Fa your_public_key Your public key, generated from -.Fa secret_key +.Fa your_secret_key with .Fn crypto_x25519_public_key . .El diff --git a/doc/man/man3/crypto_lock.3monocypher b/doc/man/man3/crypto_lock.3monocypher index 23fadaa..ecde1dc 100644 --- a/doc/man/man3/crypto_lock.3monocypher +++ b/doc/man/man3/crypto_lock.3monocypher @@ -189,29 +189,26 @@ does not need to be wiped if the decryption fails. .Sh EXAMPLES Encryption: .Bd -literal -offset indent -const uint8_t key [32]; /* Random, secret session key */ -const uint8_t nonce[24]; /* Use only once per key */ -const uint8_t *plain_text; /* Secret message */ -size_t text_size; /* Message size (NOT secret) */ -uint8_t mac [16]; /* Message authentication code */ -uint8_t *cipher_text; /* Encrypted message */ -crypto_lock(mac, cipher_text, key, nonce, plain_text, text_size); +const uint8_t key [32]; /* Random, secret session key */ +const uint8_t nonce [24]; /* Use only once per key */ +const uint8_t plain_text [500]; /* Secret message */ +uint8_t mac [16]; /* Message authentication code */ +uint8_t cipher_text[500]; /* Encrypted message */ +crypto_lock(mac, cipher_text, key, nonce, plain_text, 500); /* Wipe secrets if they are no longer needed */ -crypto_wipe(plain_text, text_size); +crypto_wipe(plain_text, 500); crypto_wipe(key, 32); /* Transmit cipher_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 */ -const uint8_t nonce[24]; /* Same as the above */ -const uint8_t mac [16]; /* Received from the network */ -const uint8_t *cipher_text; /* Encrypted message */ -size_t text_size; /* Message size (NOT secret) */ -uint8_t *plain_text; /* Secret message */ -if (crypto_unlock(plain_text, key, nonce, mac, - cipher_text, text_size)) { +const uint8_t key [32]; /* Same as the above */ +const uint8_t nonce [24]; /* Same as the above */ +const uint8_t cipher_text[500]; /* Encrypted message */ +const uint8_t mac [16]; /* Received from the network */ +uint8_t plain_text [500]; /* Secret message */ +if (crypto_unlock(plain_text, key, nonce, mac, cipher_text, 500)) { /* The message is corrupted. * Wipe key if it is no longer needed, * and abort the decryption. @@ -219,31 +216,29 @@ if (crypto_unlock(plain_text, key, nonce, mac, crypto_wipe(key, 32); } /* Wipe secrets if they are no longer needed */ -crypto_wipe(plain_text, text_size); +crypto_wipe(plain_text, 500); crypto_wipe(key, 32); .Ed .Pp 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); +const uint8_t key [32]; /* Random, secret session key */ +const uint8_t nonce[24]; /* Use only once per key */ +uint8_t text [500]; /* Secret message */ +uint8_t mac [16]; /* Message authentication code */ +crypto_lock(mac, text, key, nonce, text, 500); /* Wipe secrets if they are no longer needed */ crypto_wipe(key, 32); -/* Transmit plain_text, nonce, and mac over the network */ +/* Transmit 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 */ -const uint8_t mac [16]; /* Received from the network */ -uint8_t *text; /* Message to decrypt */ -size_t text_size; /* Message size (NOT secret) */ -if (crypto_unlock(text, key, nonce, mac, text, text_size)) { +const uint8_t key [32]; /* Same as the above */ +const uint8_t nonce[24]; /* Same as the above */ +const uint8_t mac [16]; /* Reived from the network */ +uint8_t text [500]; /* Message to decrypt */ +if (crypto_unlock(text, key, nonce, mac, text, 500)) { /* The message is corrupted. * Wipe key if it is no longer needed, * and abort the decryption. @@ -251,7 +246,7 @@ if (crypto_unlock(text, key, nonce, mac, text, text_size)) { crypto_wipe(key, 32); } /* Wipe secrets if they are no longer needed */ -crypto_wipe(text, text_size); +crypto_wipe(text, 500); crypto_wipe(key, 32); .Ed .Sh SEE ALSO diff --git a/doc/man/man3/crypto_poly1305.3monocypher b/doc/man/man3/crypto_poly1305.3monocypher index a4adc6d..fc088c1 100644 --- a/doc/man/man3/crypto_poly1305.3monocypher +++ b/doc/man/man3/crypto_poly1305.3monocypher @@ -60,7 +60,9 @@ May overlap with the .Fa mac argument. .It Fa message_size -Size of the message, in bytes. +Size of +.Fa message , +in bytes. .El .Ss Direct interface .Fn crypto_poly1305 diff --git a/doc/man/man3/intro.3monocypher b/doc/man/man3/intro.3monocypher index 3004d82..846511f 100644 --- a/doc/man/man3/intro.3monocypher +++ b/doc/man/man3/intro.3monocypher @@ -183,8 +183,8 @@ previously seen data or common characters. If an attacker can add data to the input before it is compressed and encrypted, they can observe changes to the ciphertext length to recover secrets from the input. -Researchers have demonstrated an attack on HTTPS to steal session cookies when -compression is enabled, dubbed "CRIME". +Researchers have demonstrated an attack on HTTPS to steal session +cookies when compression is enabled, dubbed "CRIME". .Ss Forward secrecy Long term secrets cannot be expected to stay safe indefinitely. Users may reveal them by mistake, or the host computer might have a @@ -194,9 +194,8 @@ are not compromised even if the long term keys are. This is done by generating temporary keys, then encrypting messages with them. .Pp -.Ss Temporary secrets -If a computer is stolen or infected after handling secret data, those past -secrets should not be compromised. +In general, secrets that went through a computer should not be +compromised when this computer is stolen or infected at a later point. .Pp A first layer of defence is to explicitly wipe secrets as soon as they are no longer used.