Fix various documentation typos & oversights

With the help of a (now updated) `doc_extract_examples.sh` script.
Note: We may want to integrate this script in the test suite, if we end
up writing more documentation.

Fix #260

diff --git a/doc/crypto_aead_lock.3monocypher b/doc/crypto_aead_lock.3monocypher
index 7bd1ff50627dac19f70730ff4de608e1ed38ed2a..348c3bf1b7fc2b5188d1eb3b2ab83c0213e4481b 100644 (file)
--- a/doc/crypto_aead_lock.3monocypher
+++ b/doc/crypto_aead_lock.3monocypher
@@ -378,7 +378,7 @@ 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_aead_unlock(text, mac, key, nonce,
-                       NULL, 0
+                       NULL, 0,
                        text, sizeof(text))) {
        /* The message is corrupted.
         * Wipe key if it is no longer needed,
@@ -406,7 +406,7 @@ 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))
+                  plain_text, sizeof(plain_text));
 /* Wipe secrets if they are no longer needed */
 crypto_wipe(plain_text, 12);
 crypto_wipe(key, 32);

diff --git a/doc/crypto_argon2.3monocypher b/doc/crypto_argon2.3monocypher
index 64cc6f5e1d807ea579f942d83a4db2e0c1b7de6a..37bf24fc9afa66f49843cf0e9c118dba0ac48d8d 100644 (file)
--- a/doc/crypto_argon2.3monocypher
+++ b/doc/crypto_argon2.3monocypher
@@ -341,10 +341,11 @@ crypto_argon2_config config = {
     .nb_passes = 3,                          /* 3 iterations    */
     .nb_lanes  = 1                           /* Single-threaded */
 };
+uint8_t password[14] = "Okay Password!";
 crypto_argon2_inputs inputs = {
-    .pass = (const uint8_t *)"Okay Password!", /* User password */
-    .pass_size = 14,                         /* Password length */
-    .salt = salt,                      /* Salt for the password */
+    .pass      = password,                     /* User password */
+    .pass_size = sizeof(password),           /* Password length */
+    .salt      = salt,                 /* Salt for the password */
     .salt_size = 16
 };
 crypto_argon2_extras extras = {0};   /* Extra parameters unused */
@@ -353,17 +354,17 @@ crypto_argon2_extras extras = {0};   /* Extra parameters unused */
  * Note the conversion to size_t.
  * Without it we cannot allocate more than 4GiB.
  */
-void *work_area = malloc((size_t)nb_blocks * 1024);
+void *work_area = malloc((size_t)config.nb_blocks * 1024);
 if (work_area == NULL) {
     /* Handle malloc() failure */
     /* Wipe secrets if they are no longer needed */
-    crypto_wipe(password, password_size);
+    crypto_wipe(password, sizeof(password));
 } else {
     arc4random_buf(salt, 16);
-    crypto_argon2i(hash, 32, work_area,
-                   config, inputs, extras);
+    crypto_argon2(hash, 32, work_area,
+                  config, inputs, extras);
     /* Wipe secrets if they are no longer needed */
-    crypto_wipe(password, password_size);
+    crypto_wipe(password, sizeof(password));
     free(work_area);
 }
 .Ed

diff --git a/doc/crypto_blake2b.3monocypher b/doc/crypto_blake2b.3monocypher
index 4ddc79bc3e97bc28c65cf2249e18937df0df5156..86ff25b876744d91ba9de53ce466380099f91353 100644 (file)
--- a/doc/crypto_blake2b.3monocypher
+++ b/doc/crypto_blake2b.3monocypher
@@ -451,6 +451,8 @@ void xkdf(uint8_t *okm,  size_t okm_size,  /* unlimited   */
 Computing key derivation with BLAKE2b alone
 (a little tedious indeed):
 .Bd -literal -offset indent
+#define MIN(a, b) ((a) < (b) ? (a) : (b))
+
 void b2kdf(uint8_t *okm,  size_t okm_size,  /* unlimited   */
            uint8_t *ikm,  size_t ikm_size,  /* unlimited   */
            uint8_t *salt, size_t salt_size, /* <= 64 bytes */

diff --git a/doc/crypto_sha512.3monocypher b/doc/crypto_sha512.3monocypher
index ca2ccdd22b49847e8230c5e8f5cbd4178d6fa8bf..d03578e4e742eb548f2680a1121f962895155ae6 100644 (file)
--- a/doc/crypto_sha512.3monocypher
+++ b/doc/crypto_sha512.3monocypher
@@ -483,10 +483,10 @@ arc4random_buf(salt, sizeof(salt));
 /* Extract */
 uint8_t prk[64];             /* pseudo-random key         */
 crypto_sha512_hmac_ctx ctx;
-crypto_sha512_hmac_init  (&ctx);
-crypto_sha512_hmac_update(&ctx, pk_a);
-crypto_sha512_hmac_update(&ctx, pk_b);
-crypto_sha512_hmac_update(&ctx, skab);
+crypto_sha512_hmac_init  (&ctx, salt, sizeof(salt));
+crypto_sha512_hmac_update(&ctx, pk_a, sizeof(pk_a));
+crypto_sha512_hmac_update(&ctx, pk_b, sizeof(pk_b));
+crypto_sha512_hmac_update(&ctx, skab, sizeof(skab));
 crypto_sha512_hmac_final (&ctx, prk);
 
 /* Expand */

diff --git a/doc/crypto_x25519.3monocypher b/doc/crypto_x25519.3monocypher
index a4dedd7692a2065bc4e4f5ad56712ba0b1ec123e..d9abbe33298cdf8d3b759622ab1b3c486a801832 100644 (file)
--- a/doc/crypto_x25519.3monocypher
+++ b/doc/crypto_x25519.3monocypher
@@ -189,14 +189,14 @@ uint8_t       your_sk      [32]; /* Your secret key           */
 uint8_t       your_pk      [32]; /* Your public key           */
 uint8_t       shared_secret[32]; /* Shared secret (NOT a key) */
 arc4random_buf(your_sk, 32);
-crypto_x25512(your_pk, your_sk);
+crypto_x25519_public_key(your_pk, your_sk);
 crypto_x25519(shared_secret, your_sk, their_pk);
 /* Wipe secrets if they are no longer needed */
 crypto_wipe(your_sk, 32);
 
 uint8_t shared_keys[64]; /* Two shared session keys */
 crypto_blake2b_ctx ctx;
-crypto_blake2b_init  (&ctx);
+crypto_blake2b_init  (&ctx, 64);
 crypto_blake2b_update(&ctx, shared_secret, 32);
 crypto_blake2b_update(&ctx, your_pk      , 32);
 crypto_blake2b_update(&ctx, their_pk     , 32);

diff --git a/doc/doc_extract_examples.sh b/doc/doc_extract_examples.sh
index 71ea9b39f87a7e5d5e7a13586667af38d84d9379..8fd0736e3f094f20a6dc8d884d6ed55d3f1d9965 100755 (executable)
--- a/doc/doc_extract_examples.sh
+++ b/doc/doc_extract_examples.sh
@@ -53,26 +53,21 @@
 # <https://creativecommons.org/publicdomain/zero/1.0/>
 
 cat << END
+#include <assert.h>
 #include <stdio.h>
 #include <stdlib.h>
+#include <string.h>
 #include "../src/monocypher.h"
 #include "../src/optional/monocypher-ed25519.h"
 
-typedef struct SHA2_CTX { void *x; } SHA2_CTX;
-void SHA512Init(SHA2_CTX*);
-void SHA512Update(SHA2_CTX*, const void*, size_t);
-void SHA512Final(uint8_t*, SHA2_CTX*);
 void arc4random_buf(void*, size_t);
 
-
 int main() {
 END
 
-for f in man/man3/*.3monocypher man/man3/optional/*.3monocypher
+for f in *.3monocypher
 do
-    # crypto_sign_init_first_pass_custom_hash examples are more complicated
-    # and can't be tested like this
-    if [ ! -h "$f" ] && [ "$f" != "man/man3/crypto_sign_init_first_pass_custom_hash.3monocypher" ]
+    if [ ! -h "$f" ]
     then
         echo "// $f"
         cat "$f" | sed -n "/^\.Bd/,/^\.Ed/p" | sed "s/\.Bd.*/{/" | sed "s/\.Ed/}/"