Manual: examples (#58)

diff --git a/doc/man/man3/crypto_blake2b.3monocypher b/doc/man/man3/crypto_blake2b.3monocypher
index 8fb0aa1960a1e0ec182340f90c2b73c195672f1e..89cd64809dae5512cdb255acde30e806ae964a53 100644 (file)
--- a/doc/man/man3/crypto_blake2b.3monocypher
+++ b/doc/man/man3/crypto_blake2b.3monocypher
@@ -152,28 +152,26 @@ These functions return nothing.
 .Sh EXAMPLES
 Hashes a message all at once.
 .Bd -literal -offset indent
-uint8_t hash[64];
-crypto_blake2b_ctx ctx;
-uint8_t hash   [ 64]; /* output hash (must be 64 bytes) */
-uint8_t message[500]; /* message to hash                */
-crypto_blake2b_ctx ctx;
+uint8_t hash   [ 64]; /* Output hash (64 bytes) */
+uint8_t message[500]; /* Message to hash        */
 crypto_blake2b(hash, message, 500);
 .Ed
 .Pp
 Computes a message authentication code all at once.
 .Bd -literal -offset indent
-uint8_t hash   [ 64]; /* output hash  (between 1 and 64 bytes) */
-uint8_t key    [ 32]; /* optional key (between 0 and 64 bytes) */
-uint8_t message[500]; /* message to hash                       */
-crypto_blake2b_ctx ctx;
+uint8_t hash   [ 64]; /* Output hash  (between 1 and 64 bytes) */
+uint8_t key    [ 32]; /* Optional key (between 0 and 64 bytes) */
+uint8_t message[500]; /* Message to hash                       */
 crypto_blake2b_general(hash, 64, key, 32, message, 500);
-crypto_wipe(key, 32); /* You may want to wipe the key          */
+/* Wipe the key. */
+crypto_wipe(key, 32);
 .Ed
 .Pp
 Hashes a message incrementally.
 .Bd -literal -offset indent
-uint8_t hash    [ 64]; /* output hash (must be 64 bytes) */
-uint8_t message [500]; /* message to hash                */
+uint8_t hash   [ 64]; /* Output hash (64 bytes) */
+uint8_t message[500]; /* Message to hash        */
+crypto_blake2b_ctx ctx;
 crypto_blake2b_init  (&ctx);
 for (size_t i = 0; i < 500; i += 100) {
     crypto_blake2b_update(&ctx, message + i, 100);
@@ -183,11 +181,13 @@ crypto_blake2b_final (&ctx, hash);
 .Pp
 Computes a message authentication code incrementally.
 .Bd -literal -offset indent
-uint8_t hash   [ 64]; /* output hash  (between 1 and 64 bytes) */
-uint8_t key    [ 32]; /* optional key (between 0 and 64 bytes) */
-uint8_t message[500]; /* message to hash                       */
+uint8_t hash   [ 64]; /* Output hash  (between 1 and 64 bytes) */
+uint8_t key    [ 32]; /* Optional key (between 0 and 64 bytes) */
+uint8_t message[500]; /* Message to hash                       */
+crypto_blake2b_ctx ctx;
 crypto_blake2b_general_init(&ctx, 64, key, 32);
-crypto_wipe(key, 32); /* You may want to wipe the key          */
+/* Wipe the key. */
+crypto_wipe(key, 32);
 for (size_t i = 0; i < 500; i += 100) {
     crypto_blake2b_update(&ctx, message + i, 100);
 }

diff --git a/doc/man/man3/crypto_poly1305.3monocypher b/doc/man/man3/crypto_poly1305.3monocypher
index a6bc95a44905cac8b282cc5482fe0dfb83b9b1f5..1ecea1df23be97ecf2f4a35c17881cdca9742c23 100644 (file)
--- a/doc/man/man3/crypto_poly1305.3monocypher
+++ b/doc/man/man3/crypto_poly1305.3monocypher
@@ -109,6 +109,8 @@ if (crypto_verify16(mac, real_mac)) {
 } else {
     /* Genuine message */
 }
+/* The real mac is secret.  Wipe it */
+crypto_wipe(real_mac, 16);
 .Ed
 .Pp
 Incremental authentication:

diff --git a/doc/man/man3/crypto_sign.3monocypher b/doc/man/man3/crypto_sign.3monocypher
index 5f6ab17bf386601b9237c750716fbd1c5b194a54..792cf09ccb547bfd604c1eb00725e45c46490e38 100644 (file)
--- a/doc/man/man3/crypto_sign.3monocypher
+++ b/doc/man/man3/crypto_sign.3monocypher
@@ -96,33 +96,33 @@ returns 0 for legitimate messages and -1 for forgeries.
 .Sh EXAMPLES
 Generate a public key from a random secret key:
 .Bd -literal -offset indent
-const uint8_t sk[32]; /* random secret key   */
-uint8_t       pk[32]; /* matching public key */
+const uint8_t sk[32]; /* Random secret key   */
+uint8_t       pk[32]; /* Matching public key */
 crypto_sign_public_key(pk, sk);
-/* wipe the secret key if it is no longer needed */
+/* Wipe the secret key if it is no longer needed */
 crypto_wipe(sk, 32);
 .Ed
 .Pp
 Sign a message:
 .Bd -literal -offset indent
-const uint8_t sk       [ 32]; /* your secret key     */
-const uint8_t pk       [ 32]; /* matching public key */
-const uint8_t message  [500]; /* message to sign     */
+const uint8_t sk       [ 32]; /* Your secret key     */
+const uint8_t pk       [ 32]; /* Matching public key */
+const uint8_t message  [500]; /* Message to sign     */
 uint8_t       signature[ 64];
 crypto_sign(signature, sk, pk, message, 500);
-/* wipe the secret key if it is no longer needed */
+/* Wipe the secret key if it is no longer needed */
 crypto_wipe(sk, 32);
 .Ed
 .Pp
 Check the above:
 .Bd -literal -offset indent
-const uint8_t pk       [ 32]; /* their public key   */
-const uint8_t message  [500]; /* signed message     */
-const uint8_t signature[ 64]; /* signature to check */
+const uint8_t pk       [ 32]; /* Their public key   */
+const uint8_t message  [500]; /* Signed message     */
+const uint8_t signature[ 64]; /* Signature to check */
 if (crypto_check(signature, pk, message, 500)) {
-    /* message is corrupted, abort processing */
+    /* Message is corrupted, abort processing */
 } else {
-    /* message is genuine */
+    /* Message is genuine */
 }
 .Ed
 .Sh SEE ALSO

diff --git a/doc/man/man3/crypto_sign_init_first_pass.3monocypher b/doc/man/man3/crypto_sign_init_first_pass.3monocypher
index f850be0e79746ee5e20c5feec6caea14354f3a97..93493bbeb0e3f7fa92cc386e44ab6384bb7f8d08 100644 (file)
--- a/doc/man/man3/crypto_sign_init_first_pass.3monocypher
+++ b/doc/man/man3/crypto_sign_init_first_pass.3monocypher
@@ -120,13 +120,13 @@ returns 0 for legitimate messages and -1 for forgeries.
 .Sh EXAMPLES
 Sign a message:
 .Bd -literal -offset indent
-const uint8_t sk       [ 32]; /* secret key            */
-const uint8_t pk       [ 32]; /* public key (optional) */
-const uint8_t message  [500]; /* message to sign       */
+const uint8_t sk       [ 32]; /* Secret key            */
+const uint8_t pk       [ 32]; /* Public key (optional) */
+const uint8_t message  [500]; /* Message to sign       */
 uint8_t       signature[ 64];
 crypto_sign_ctx ctx;
 crypto_sign_init_first_pass(&ctx, sk, pk);
-/* wipe the secret key if no longer needed */
+/* Wipe the secret key if no longer needed */
 crypto_wipe(sk, 32);
 for (size_t i = 0; i < 500; i += 100) {
     crypto_sign_update(&ctx, message + i, 100);
@@ -140,8 +140,8 @@ crypto_sign_final(&ctx, signature);
 .Pp
 Check the above:
 .Bd -literal -offset indent
-const uint8_t pk       [ 32]; /* public key      */
-const uint8_t message  [500]; /* message to sign */
+const uint8_t pk       [ 32]; /* Public key      */
+const uint8_t message  [500]; /* Message to sign */
 const uint8_t signature[ 64];
 crypto_check_ctx ctx;
 crypto_check_init(&ctx, signature, pk);
@@ -149,9 +149,9 @@ for (size_t i = 0; i < 500; i += 100) {
     crypto_check_update(&ctx, message + i, 100);
 }
 if (crypto_check_final(&ctx)) {
-    /* message is corrupted, abort processing */
+    /* Message is corrupted, abort processing */
 } else {
-    /* message is genuine */
+    /* Message is genuine */
 }
 
 .Ed