Use "Length of .Fa x , in bytes."

diff --git a/doc/man/man3/crypto_argon2i.3monocypher b/doc/man/man3/crypto_argon2i.3monocypher
index 9c148ced6266dc3de4e47cb38ca14ca9eb8f359c..3851d2ef6a8f54627707d2bf200b61759e434146 100644 (file)
--- 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 4020afc2c182f29f13ef59268e43df22165dff39..a28f60e24e4c74f233a9c60f744e6f3e11ea94dd 100644 (file)
--- 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 4ae7ce2d0bf230c2acd73bea8668dc21211c3f4a..02a2b4e8fe4e09ebe8cf1c48d9f9737d6e549926 100644 (file)
--- 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 1ef3db50a9ac169e06abf1215825c2110c55613c..a35bf8f9f7c15127f0e1b2d050308dc1299cbcd5 100644 (file)
--- 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 23fadaacf3c8c139945bf20933d4daf299b9bd04..ecde1dcc48b346d1ed8900a3b09088d8e6737547 100644 (file)
--- 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 a4adc6d6a6d50be6bd3bc5827d55bd97f156ecf6..fc088c18d96d2a6da36aefd04f6fec7c0cc6a280 100644 (file)
--- 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 3004d826482da5d499f8135a450c8612bd6cc820..846511fd71c067d0470b973dd5f842cb1d1f2f3e 100644 (file)
--- 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.