Add random_bytes() to crypto_lock examples

diff --git a/doc/extract_examples.sh b/doc/extract_examples.sh
index aadf4567be76bef0ee2e8e036805cdad87b03d59..78fb5f8446b7d40c738531f190a17bbbe3524f65 100755 (executable)
--- a/doc/extract_examples.sh
+++ b/doc/extract_examples.sh
@@ -12,6 +12,7 @@
 # ------------------------------------------------------------------------
 #
 # Copyright (c) 2019 Michael Savage
+# Copyright (c) 2020 Fabio Scotoni
 # All rights reserved.
 #
 #
@@ -41,7 +42,7 @@
 #
 # ------------------------------------------------------------------------
 #
-# Written in 2019 by Michael Savage
+# Written in 2019-2020 by 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
@@ -63,6 +64,11 @@ void SHA512Update(SHA2_CTX*, const void*, size_t);
 void SHA512Final(uint8_t*, SHA2_CTX*);
 void arc4random_buf(void*, size_t);
 
+static void random_bytes(uint8_t *buf, size_t len)
+{
+    arc4random_buf(buf, len);
+}
+
 int main() {
 END
 

diff --git a/doc/man/man3/crypto_lock.3monocypher b/doc/man/man3/crypto_lock.3monocypher
index 993a2f88583658d15c4d9fabfe7ba7c72e2d381c..ac72692e25fb553436d3fcc8d33d5597f0b95985 100644 (file)
--- a/doc/man/man3/crypto_lock.3monocypher
+++ b/doc/man/man3/crypto_lock.3monocypher
@@ -10,7 +10,7 @@
 .\"
 .\" Copyright (c) 2017-2019 Loup Vaillant
 .\" Copyright (c) 2017-2018 Michael Savage
-.\" Copyright (c) 2017, 2019 Fabio Scotoni
+.\" Copyright (c) 2017, 2019-2020 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -40,7 +40,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2017-2019 by Loup Vaillant, Michael Savage and Fabio Scotoni
+.\" Written in 2017-2020 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
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd December 12, 2019
+.Dd February 29, 2020
 .Dt CRYPTO_LOCK 3MONOCYPHER
 .Os
 .Sh NAME
@@ -226,6 +226,21 @@ attacker's interference.
 .Fa plain_text
 does not need to be wiped if the decryption fails.
 .Sh EXAMPLES
+The following examples assume that a function called
+.Fn random_bytes
+exists.
+It fills the given buffer with cryptographically secure random
+bytes
+(see
+.Xr intro 3monocypher
+for some advice on how to accomplish this yourself).
+The function has this prototype:
+.Ft void
+.Fo random_bytes
+.Fa "uint8_t *buf"
+.Fa "size_t len"
+.Fc
+.Pp
 Encryption:
 .Bd -literal -offset indent
 uint8_t       key        [32];  /* Random, secret session key  */
@@ -233,11 +248,14 @@ const uint8_t nonce      [24];  /* Use only once per key       */
 uint8_t       plain_text [500]; /* Secret message              */
 uint8_t       mac        [16];  /* Message authentication code */
 uint8_t       cipher_text[500]; /* Encrypted message           */
+random_bytes(key, 32);
 crypto_lock(mac, cipher_text, key, nonce, plain_text, 500);
 /* Wipe secrets if they are no longer needed */
 crypto_wipe(plain_text, 500);
 crypto_wipe(key, 32);
-/* Transmit cipher_text, nonce, and mac over the network */
+/* Transmit cipher_text, nonce, and mac over the network,
+ * store them in a file, etc.
+ */
 .Ed
 .Pp
 To decrypt the above:
@@ -253,10 +271,12 @@ if (crypto_unlock(plain_text, key, nonce, mac, cipher_text, 500)) {
      * 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(plain_text, 500);
+    crypto_wipe(key, 32);
 }
-/* Wipe secrets if they are no longer needed */
-crypto_wipe(plain_text, 500);
-crypto_wipe(key, 32);
 .Ed
 .Pp
 In-place encryption:
@@ -265,10 +285,13 @@ 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 */
+random_bytes(key, 32);
 crypto_lock(mac, text, key, nonce, text, 500);
 /* Wipe secrets if they are no longer needed */
 crypto_wipe(key, 32);
-/* Transmit text, nonce, and mac over the network */
+/* Transmit cipher_text, nonce, and mac over the network,
+ * store them in a file, etc.
+ */
 .Ed
 .Pp
 In-place decryption:
@@ -283,10 +306,12 @@ if (crypto_unlock(text, key, nonce, mac, text, 500)) {
      * 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, 500);
+    crypto_wipe(key, 32);
 }
-/* Wipe secrets if they are no longer needed */
-crypto_wipe(text, 500);
-crypto_wipe(key, 32);
 .Ed
 .Sh SEE ALSO
 .Xr crypto_key_exchange 3monocypher ,