From d196a839c597348492146d3436b36090271fa353 Mon Sep 17 00:00:00 2001
From: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date: Mon, 2 Mar 2020 08:08:37 +0100
Subject: [PATCH] crypto_poly1305 example overhaul

1. Randomize key.
2. Give it an actual example message to MAC.
---
 doc/man/man3/crypto_poly1305.3monocypher | 37 +++++++++++++++---------
 1 file changed, 24 insertions(+), 13 deletions(-)

diff --git a/doc/man/man3/crypto_poly1305.3monocypher b/doc/man/man3/crypto_poly1305.3monocypher
index 44cca05..72208ed 100644
--- a/doc/man/man3/crypto_poly1305.3monocypher
+++ b/doc/man/man3/crypto_poly1305.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-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 March 2, 2020
 .Dt CRYPTO_POLY1305 3MONOCYPHER
 .Os
 .Sh NAME
@@ -139,23 +139,33 @@ yields the message authentication code.
 .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
 To authenticate a message:
 .Bd -literal -offset indent
-const uint8_t msg[500]; /* Message to authenticate           */
-uint8_t       key[ 32]; /* Random secret key (use only once) */
-uint8_t       mac[ 16]; /* Message authentication code (MAC) */
-crypto_poly1305(mac, msg, 500, key);
+const uint8_t msg[ 5] = "Lorem"; /* Message to authenticate */
+uint8_t       key[32]; /* Random secret key (use only once) */
+uint8_t       mac[16]; /* Message authentication code (MAC) */
+arc4random_buf(key, 32);
+crypto_poly1305(mac, msg, 5, key);
 /* Wipe the key */
 crypto_wipe(key, 32);
 .Ed
 .Pp
 To verify the above message:
 .Bd -literal -offset indent
-const uint8_t msg     [500]; /* Message to verify */
-uint8_t       key     [ 32]; /* The above key     */
-const uint8_t mac     [ 16]; /* The above MAC     */
-uint8_t       real_mac[ 16]; /* The actual MAC    */
-crypto_poly1305(real_mac, msg, 500, key);
+const uint8_t msg     [ 5] = "Lorem"; /* Message to verify */
+uint8_t       key     [32];           /* The above key     */
+const uint8_t mac     [16];           /* The above MAC     */
+uint8_t       real_mac[16];           /* The actual MAC    */
+crypto_poly1305(real_mac, msg, 5, key);
 /* Wipe the key */
 crypto_wipe(key, 32);
 if (crypto_verify16(mac, real_mac)) {
@@ -169,10 +179,11 @@ crypto_wipe(real_mac, 16);
 .Pp
 Incremental authentication:
 .Bd -literal -offset indent
-const uint8_t msg[500]; /* Message to authenticate           */
+const uint8_t msg[500]= {1}; /* Message to authenticate      */
 uint8_t       key[ 32]; /* Random secret key (use only once) */
 uint8_t       mac[ 16]; /* Message authentication code (MAC) */
 crypto_poly1305_ctx ctx;
+arc4random_buf(key, 32);
 crypto_poly1305_init(&ctx, key);
 /* Wipe the key */
 crypto_wipe(key, 32);
-- 
2.47.3