Examples: const correctness

It's unfortunate that we can't both tell users to wipe keys and
illustrate which arguments are inputs and which ones are outputs
at the same time, but that's just how it is.

diff --git a/doc/man/man3/crypto_chacha20.3monocypher b/doc/man/man3/crypto_chacha20.3monocypher
index df3454903a6a9c9dcd6bed68bea0c6aef93f23e2..980613ca7734d1987345e77a2c6ff8f84cbf3c11 100644 (file)
--- a/doc/man/man3/crypto_chacha20.3monocypher
+++ b/doc/man/man3/crypto_chacha20.3monocypher
@@ -239,9 +239,9 @@ plus one if there was a remainder.
 .Sh EXAMPLES
 Simple encryption:
 .Bd -literal -offset indent
-const uint8_t key        [ 32]; /* Secret random key              */
+uint8_t       key        [ 32]; /* Secret random key              */
 const uint8_t nonce      [ 24]; /* Unique nonce (possibly random) */
-const uint8_t plain_text [500]; /* Message to be encrypted        */
+uint8_t       plain_text [500]; /* Message to be encrypted        */
 uint8_t       cipher_text[500]; /* Will be the encrypted message  */
 crypto_xchacha20(cipher_text, plain_text, 500, key, nonce);
 /* Wipe secrets if they are no longer needed */
@@ -251,7 +251,7 @@ crypto_wipe(plain_text, 500);
 .Pp
 To decrypt the above:
 .Bd -literal -offset indent
-const uint8_t key  [ 32]; /* Same key as above              */
+uint8_t       key  [ 32]; /* Same key as above              */
 const uint8_t nonce[ 24]; /* Same nonce as above            */
 uint8_t plain_text [500]; /* Will be the decrypted message  */
 uint8_t cipher_text[500]; /* Encrypted message              */
@@ -264,9 +264,9 @@ crypto_wipe(plain_text, 500);
 .Pp
 Incremental encryption (in blocks of 64 bytes):
 .Bd -literal -offset indent
-const uint8_t key        [ 32]; /* Secret random key              */
+uint8_t       key        [ 32]; /* Secret random key              */
 const uint8_t nonce      [ 24]; /* Unique nonce (possibly random) */
-const uint8_t plain_text [500]; /* Message to be encrypted        */
+uint8_t       plain_text [500]; /* Message to be encrypted        */
 uint8_t       cipher_text[500]; /* Will be the encrypted message  */
 uint64_t      ctr;              /* Block counter */
 int i;
@@ -289,9 +289,9 @@ how
 .Fn crypto_xchacha20_ctr
 works):
 .Bd -literal -offset indent
-const uint8_t key        [ 32]; /* Secret random key              */
+uint8_t       key        [ 32]; /* Secret random key              */
 const uint8_t nonce      [ 24]; /* Unique nonce (possibly random) */
-const uint8_t plain_text [500]; /* Message to be encrypted        */
+uint8_t       plain_text [500]; /* Message to be encrypted        */
 uint8_t       cipher_text[500]; /* Will be the encrypted message  */
 /* Encrypt the second part of the message first... */
 crypto_chacha20(cipher_text + (3 * 64),

diff --git a/doc/man/man3/crypto_hchacha20.3monocypher b/doc/man/man3/crypto_hchacha20.3monocypher
index 85107997788a13e7f101e1f7ba3cfa407c4ba1e2..1ae4a8f61fbbfdac2a3db12ac164e40d20db1e51 100644 (file)
--- a/doc/man/man3/crypto_hchacha20.3monocypher
+++ b/doc/man/man3/crypto_hchacha20.3monocypher
@@ -94,9 +94,9 @@ This function returns nothing.
 .Sh EXAMPLES
 Simple hash:
 .Bd -literal -offset indent
-const uint8_t key[32]; /* Must have enough entropy           */
-const uint8_t in [16]; /* Does not have to be random         */
-uint8_t       out[32]; /* Will be random iff the above holds */
+uint8_t key[32]; /* Must have enough entropy           */
+uint8_t in [16]; /* Does not have to be random         */
+uint8_t out[32]; /* Will be random iff the above holds */
 crypto_hchacha20(out, key, in);
 /* Wipe secrets if they are no longer needed */
 crypto_wipe(key, 32);

diff --git a/doc/man/man3/crypto_key_exchange.3monocypher b/doc/man/man3/crypto_key_exchange.3monocypher
index 70df8ae3af6d3239d5f3f21145a117563e89fb69..9bfd3fd29887a53f4f614108a14814c235cdee33 100644 (file)
--- a/doc/man/man3/crypto_key_exchange.3monocypher
+++ b/doc/man/man3/crypto_key_exchange.3monocypher
@@ -117,8 +117,8 @@ keys over a trusted channel.
 .Sh EXAMPLES
 Generate a public key from a randomly generated secret key:
 .Bd -literal -offset indent
-const uint8_t sk[32]; /* Random secret key */
-uint8_t       pk[32]; /* Public key        */
+uint8_t sk[32]; /* Random secret key */
+uint8_t pk[32]; /* Public key        */
 crypto_key_exchange_public_key(pk, sk);
 /* Wipe secrets if they are no longer needed */
 crypto_wipe(sk, 32);
@@ -130,7 +130,7 @@ key.
 key and their secret key.)
 .Bd -literal -offset indent
 const uint8_t their_pk  [32]; /* Their public key   */
-const uint8_t your_sk   [32]; /* Your secret key    */
+uint8_t       your_sk   [32]; /* Your secret key    */
 uint8_t       shared_key[32]; /* Shared session key */
 crypto_key_exchange(shared_key, your_sk, their_pk);
 /* Wipe secrets if they are no longer needed */

diff --git a/doc/man/man3/crypto_lock.3monocypher b/doc/man/man3/crypto_lock.3monocypher
index 49e711020ab37fa4e3be7c4aa5520bd9cafaa229..993a2f88583658d15c4d9fabfe7ba7c72e2d381c 100644 (file)
--- a/doc/man/man3/crypto_lock.3monocypher
+++ b/doc/man/man3/crypto_lock.3monocypher
@@ -228,9 +228,9 @@ does not need to be wiped if the decryption fails.
 .Sh EXAMPLES
 Encryption:
 .Bd -literal -offset indent
-const uint8_t key        [32];  /* Random, secret session key  */
+uint8_t       key        [32];  /* Random, secret session key  */
 const uint8_t nonce      [24];  /* Use only once per key       */
-const uint8_t plain_text [500]; /* Secret message              */
+uint8_t       plain_text [500]; /* Secret message              */
 uint8_t       mac        [16];  /* Message authentication code */
 uint8_t       cipher_text[500]; /* Encrypted message           */
 crypto_lock(mac, cipher_text, key, nonce, plain_text, 500);
@@ -242,7 +242,7 @@ crypto_wipe(key, 32);
 .Pp
 To decrypt the above:
 .Bd -literal -offset indent
-const uint8_t key        [32];  /* Same as the above         */
+uint8_t       key        [32];  /* Same as the above         */
 const uint8_t nonce      [24];  /* Same as the above         */
 const uint8_t cipher_text[500]; /* Encrypted message         */
 const uint8_t mac        [16];  /* Received from the network */
@@ -261,7 +261,7 @@ crypto_wipe(key, 32);
 .Pp
 In-place encryption:
 .Bd -literal -offset indent
-const uint8_t key  [32];  /* Random, secret session key  */
+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 */
@@ -273,7 +273,7 @@ crypto_wipe(key, 32);
 .Pp
 In-place decryption:
 .Bd -literal -offset indent
-const uint8_t  key  [32];  /* Same as the above         */
+uint8_t        key  [32];  /* Same as the above         */
 const uint8_t  nonce[24];  /* Same as the above         */
 const uint8_t  mac  [16];  /* Received from the network */
 uint8_t        text [500]; /* Message to decrypt        */

diff --git a/doc/man/man3/crypto_poly1305.3monocypher b/doc/man/man3/crypto_poly1305.3monocypher
index fb39af2d2ff636f97990904d339a5f975185ace4..44cca05f83836b375a247d410537094ba3674daf 100644 (file)
--- a/doc/man/man3/crypto_poly1305.3monocypher
+++ b/doc/man/man3/crypto_poly1305.3monocypher
@@ -142,7 +142,7 @@ These functions return nothing.
 To authenticate a message:
 .Bd -literal -offset indent
 const uint8_t msg[500]; /* Message to authenticate           */
-const uint8_t key[ 32]; /* Random secret key (use only once) */
+uint8_t       key[ 32]; /* Random secret key (use only once) */
 uint8_t       mac[ 16]; /* Message authentication code (MAC) */
 crypto_poly1305(mac, msg, 500, key);
 /* Wipe the key */
@@ -152,7 +152,7 @@ crypto_wipe(key, 32);
 To verify the above message:
 .Bd -literal -offset indent
 const uint8_t msg     [500]; /* Message to verify */
-const uint8_t key     [ 32]; /* The above key     */
+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);
@@ -170,7 +170,7 @@ crypto_wipe(real_mac, 16);
 Incremental authentication:
 .Bd -literal -offset indent
 const uint8_t msg[500]; /* Message to authenticate           */
-const uint8_t key[ 32]; /* Random secret key (use only once) */
+uint8_t       key[ 32]; /* Random secret key (use only once) */
 uint8_t       mac[ 16]; /* Message authentication code (MAC) */
 crypto_poly1305_ctx ctx;
 crypto_poly1305_init(&ctx, key);

diff --git a/doc/man/man3/crypto_sign.3monocypher b/doc/man/man3/crypto_sign.3monocypher
index 5367ebd0d5d4ffbab9f6892499e79224c586e8ae..90174a7d89771c596862cb758290015c54992900 100644 (file)
--- a/doc/man/man3/crypto_sign.3monocypher
+++ b/doc/man/man3/crypto_sign.3monocypher
@@ -152,7 +152,7 @@ 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       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 */
@@ -161,7 +161,7 @@ crypto_wipe(sk, 32);
 .Pp
 Sign a message:
 .Bd -literal -offset indent
-const uint8_t sk       [ 32]; /* Your secret key     */
+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];

diff --git a/doc/man/man3/crypto_sign_init_first_pass.3monocypher b/doc/man/man3/crypto_sign_init_first_pass.3monocypher
index 58aebd3919db95eb6bc45df0b164a00409a9a9c2..dfa7fd9ad118b757d96a50aed23db8e98d15c694 100644 (file)
--- a/doc/man/man3/crypto_sign_init_first_pass.3monocypher
+++ b/doc/man/man3/crypto_sign_init_first_pass.3monocypher
@@ -170,7 +170,7 @@ 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            */
+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]; /* Output signature      */

diff --git a/doc/man/man3/crypto_sign_init_first_pass_custom_hash.3monocypher b/doc/man/man3/crypto_sign_init_first_pass_custom_hash.3monocypher
index 5302f9da47f9dd685977bfd4aad5888e60acca24..c1af870ff7f3ef88b721c398a2edbd267737ba9f 100644 (file)
--- a/doc/man/man3/crypto_sign_init_first_pass_custom_hash.3monocypher
+++ b/doc/man/man3/crypto_sign_init_first_pass_custom_hash.3monocypher
@@ -277,6 +277,7 @@ main(void)
         return 1;
     }
     puts("ok");
+    return 0;
 }
 .Ed
 .Sh SEE ALSO

diff --git a/doc/man/man3/crypto_x25519.3monocypher b/doc/man/man3/crypto_x25519.3monocypher
index 7e29ce810b09e5956a6259cff48c04724e00ea38..fed0d23992a0b51ae7cfa8804eb219dbe31a97f9 100644 (file)
--- a/doc/man/man3/crypto_x25519.3monocypher
+++ b/doc/man/man3/crypto_x25519.3monocypher
@@ -126,7 +126,7 @@ key.
 (This can help nonce management for full duplex communications.)
 .Bd -literal -offset indent
 const uint8_t their_pk     [32]; /* Their public key          */
-const uint8_t your_sk      [32]; /* Your secret key           */
+uint8_t       your_sk      [32]; /* Your secret key           */
 uint8_t       shared_secret[32]; /* Shared secret (NOT a key) */
 crypto_x25519(shared_secret, your_sk, their_pk);
 /* Wipe secrets if they are no longer needed */