From 3ce4d032cd729a5a940d071db91b69532360b009 Mon Sep 17 00:00:00 2001 From: Fabio Scotoni <34964387+fscoto@users.noreply.github.com> Date: Tue, 25 Feb 2020 09:53:24 +0100 Subject: [PATCH] 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. --- doc/man/man3/crypto_chacha20.3monocypher | 14 +++++++------- doc/man/man3/crypto_hchacha20.3monocypher | 6 +++--- doc/man/man3/crypto_key_exchange.3monocypher | 6 +++--- doc/man/man3/crypto_lock.3monocypher | 10 +++++----- doc/man/man3/crypto_poly1305.3monocypher | 6 +++--- doc/man/man3/crypto_sign.3monocypher | 4 ++-- .../man3/crypto_sign_init_first_pass.3monocypher | 2 +- ...to_sign_init_first_pass_custom_hash.3monocypher | 1 + doc/man/man3/crypto_x25519.3monocypher | 2 +- 9 files changed, 26 insertions(+), 25 deletions(-) diff --git a/doc/man/man3/crypto_chacha20.3monocypher b/doc/man/man3/crypto_chacha20.3monocypher index df34549..980613c 100644 --- 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 8510799..1ae4a8f 100644 --- 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 70df8ae..9bfd3fd 100644 --- 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 49e7110..993a2f8 100644 --- 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 fb39af2..44cca05 100644 --- 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 5367ebd..90174a7 100644 --- 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 58aebd3..dfa7fd9 100644 --- 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 5302f9d..c1af870 100644 --- 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 7e29ce8..fed0d23 100644 --- 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 */ -- 2.47.3