crypto_hmac_sha512 example overhaul

1. Randomize the key.
2. Key for HMAC is NOT optional.
3. Give it an actual example message to authenticate.

diff --git a/doc/man/man3/optional/crypto_hmac_sha512.3monocypher b/doc/man/man3/optional/crypto_hmac_sha512.3monocypher
index 0e55b71b26b52f98bb8383c666514556b7e40495..59b4e48d22caffe28b537321693b61a9efeb7026 100644 (file)
--- a/doc/man/man3/optional/crypto_hmac_sha512.3monocypher
+++ b/doc/man/man3/optional/crypto_hmac_sha512.3monocypher
@@ -8,7 +8,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Copyright (c) 2019 Fabio Scotoni
+.\" Copyright (c) 2019-2020 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -38,7 +38,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2019 by Fabio Scotoni
+.\" Written in 2019-2020 by 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
@@ -48,7 +48,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd December 12, 2019
+.Dd March 2, 2020
 .Dt CRYPTO_HMAC_SHA512 3MONOCYPHER
 .Os
 .Sh NAME
@@ -167,11 +167,21 @@ functions can be used to to compare (possibly truncated) MACs.
 .Sh RETURN VALUES
 These functions return nothing.
 .Sh EXAMPLES
+The following examples assume the existence of
+.Fn arc4random_buf ,
+which fills the given buffer with cryptographically secure random bytes.
+If
+.Fn arc4random_buf
+does not exist on your system, see
+.Xr intro 3monocypher
+for advice about how to generate cryptographically secure random bytes.
+.Pp
 Computing 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                       */
+uint8_t hash   [64]; /* Output hash  (between 1 and 64 bytes)  */
+uint8_t key    [32]; /* Key          (at least 1 byte)         */
+uint8_t message[10] = "Lorem ipsu"; /* Message to authenticate */
+arc4random_buf(key, 32);
 crypto_hmac_sha512(hash, key, 32, message, 500);
 /* Wipe secrets if they are no longer needed */
 crypto_wipe(message, 500);
@@ -180,10 +190,11 @@ crypto_wipe(key, 32);
 .Pp
 Computing 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]; /* Key          (at least 1 byte)         */
+uint8_t message[500] = {1}; /* Message to authenticate         */
 crypto_hmac_sha512_ctx ctx;
+arc4random_buf(key, 32);
 crypto_hmac_sha512_init(&ctx, key, 32);
 /* Wipe the key */
 crypto_wipe(key, 32);