From 5287e5f0e6bda02589fb6f290c01535f0c09af06 Mon Sep 17 00:00:00 2001 From: Loup Vaillant Date: Thu, 28 Dec 2017 16:31:34 +0100 Subject: [PATCH] Manual: examples (#58) --- doc/man/man3/crypto_blake2b.3monocypher | 32 +++++++++---------- doc/man/man3/crypto_poly1305.3monocypher | 2 ++ doc/man/man3/crypto_sign.3monocypher | 24 +++++++------- .../crypto_sign_init_first_pass.3monocypher | 16 +++++----- 4 files changed, 38 insertions(+), 36 deletions(-) diff --git a/doc/man/man3/crypto_blake2b.3monocypher b/doc/man/man3/crypto_blake2b.3monocypher index 8fb0aa1..89cd648 100644 --- 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 a6bc95a..1ecea1d 100644 --- 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 5f6ab17..792cf09 100644 --- 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 f850be0..93493bb 100644 --- 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 -- 2.47.3