From c126f51eea324a181e224f2385e5bc5033626913 Mon Sep 17 00:00:00 2001 From: CuleX Date: Fri, 6 Oct 2017 13:31:56 +0200 Subject: [PATCH] Fix formatting and typos in the man pages --- doc/man/man3/crypto_aead_lock.3monocypher | 6 +++--- doc/man/man3/crypto_argon2i.3monocypher | 2 +- doc/man/man3/crypto_blake2b.3monocypher | 19 ++++++++++++------- .../man3/crypto_chacha20_encrypt.3monocypher | 6 +++--- doc/man/man3/crypto_key_exchange.3monocypher | 8 ++++---- doc/man/man3/crypto_memcmp.3monocypher | 3 ++- 6 files changed, 25 insertions(+), 19 deletions(-) diff --git a/doc/man/man3/crypto_aead_lock.3monocypher b/doc/man/man3/crypto_aead_lock.3monocypher index 0db754b..d6f8321 100644 --- a/doc/man/man3/crypto_aead_lock.3monocypher +++ b/doc/man/man3/crypto_aead_lock.3monocypher @@ -35,7 +35,7 @@ These functions are variants of and .Xr crypto_unlock 3monocypher , permitting additional data. -Addiional data is authenticated, but +Additional data is authenticated, but .Em not encrypted. .Pp @@ -50,8 +50,8 @@ and .Ef .Pp If you must send unencrypted data, remember that you cannot trust -unauthenticated data. -.Em Including the length of the additional data . +unauthenticated data, +.Em including the length of the additional data . If you transmit that length over the wire, you must authenticate it. (The easiest way to do so is to append that length to the additional data before you call diff --git a/doc/man/man3/crypto_argon2i.3monocypher b/doc/man/man3/crypto_argon2i.3monocypher index 8981f3b..fe4c0e8 100644 --- a/doc/man/man3/crypto_argon2i.3monocypher +++ b/doc/man/man3/crypto_argon2i.3monocypher @@ -99,7 +99,7 @@ is zero. You generally do not need this parameter, but it does have some use: The key is supposed to be unknown to the attacker. In the context of password derivation, it would stay unknown -.Em even if an attacker steals your password database. +.Em even if an attacker steals your password database . This may be possible if that key is stored separately from your password database (like on a separate server, and never written on the main server's disks). diff --git a/doc/man/man3/crypto_blake2b.3monocypher b/doc/man/man3/crypto_blake2b.3monocypher index 9b68cb6..5cc8b6c 100644 --- a/doc/man/man3/crypto_blake2b.3monocypher +++ b/doc/man/man3/crypto_blake2b.3monocypher @@ -51,7 +51,7 @@ .Sh DESCRIPTION Blake2b is a fast cryptographically secure hash, based on the ideas of Chacha20. -It is faster than md5, yet just as secure as SHA-3. +It is faster than MD5, yet just as secure as SHA-3. .Pp Blake2b is immune to length extension attacks, and as such does not require any specific precautions, such as using the HMAC algorithm. @@ -67,6 +67,8 @@ free bytes. .It Fa hash_size the length of the output hash. Must be between 1 and 64. +A value of 64 is recommended. +Values below 32 are discouraged. .It Fa key some secret key. May be @@ -93,14 +95,17 @@ and .Fn crypto_blake2b_general . The .Fn crypto_blake2b -is provided for convenience. -It uses a 64 bytes hash and no key (this is a good default). +function is provided for convenience. +It uses a 64 byte hash and no key. +These values are good defaults for +.Fn crypto_blake2b_general_init , +too. .Pp If you use the .Fn crypto_blake2b_general -function, you can specify the size of the hash (sizes below 32 bytes -are discouraged), and use a secret key to make the hash unpredictable -\(en useful for message authentication codes. +function, you can specify the size of the hash, and use a secret key to +make the hash unpredictable \(en useful for message authentication +codes. .Ss Incremental interface Incremental interfaces are useful to handle streams of data or large files without using too much memory. @@ -121,7 +126,7 @@ The invariants of the parameters are the same as for .Fn crypto_blake2b_init is a convenience initialisation function that specifies a 64-byte hash and no key. -This is a good default. +This is considered a good default. .Sh RETURN VALUES These functions return nothing. .Sh EXAMPLES diff --git a/doc/man/man3/crypto_chacha20_encrypt.3monocypher b/doc/man/man3/crypto_chacha20_encrypt.3monocypher index 791d4e6..aa0479f 100644 --- a/doc/man/man3/crypto_chacha20_encrypt.3monocypher +++ b/doc/man/man3/crypto_chacha20_encrypt.3monocypher @@ -48,8 +48,8 @@ .Fa "uint64_t ctr" .Fc .Sh DESCRIPTION -These functions provides an incremental interface for Chacha20, with an -initialisation, and as many encryption steps as you want. +These functions provide an incremental interface for Chacha20, with an +initialisation function, and as many encryption steps as desired. .Pp To use these functions, you must first initialize a .Vt crypto_chacha_ctx @@ -105,7 +105,7 @@ with being .Dv NULL . This is useful as a user space random number generator. -Do not use this as a cryptographic random number generator. +.Sy \&Do not use this as a cryptographic random number generator . Still, this function can be used outside of a security context: deterministic procedural generation comes to mind. .Pp diff --git a/doc/man/man3/crypto_key_exchange.3monocypher b/doc/man/man3/crypto_key_exchange.3monocypher index 09eed6e..f050ebf 100644 --- a/doc/man/man3/crypto_key_exchange.3monocypher +++ b/doc/man/man3/crypto_key_exchange.3monocypher @@ -55,9 +55,9 @@ and .Xr crypto_aead_unlock 3monocypher functions. It performs an X25519 key exchange, then hashes the shared secret (with -HChacha20) to get a suitably random-looking shared key. +HChacha20) to get a suitably random shared key. .Pp -Keep in mind that if either of your long term secret keys leaks, it +Keep in mind that if either of the long term secret keys leaks, it may compromise .Em all past messages ! If you want forward secrecy, you will need to exchange temporary public @@ -87,7 +87,7 @@ This function computes a shared secret with your secret key .Fa your_secret_key and the other party's public key .Fa their_public_key . -.Sy Warning: the shared secret is not cryptographically random. +.Sy Warning: the shared secret is not cryptographically random . Do not use it directly as a session key. You need to hash it first. Any cryptographically secure hash will do. @@ -158,7 +158,7 @@ function utilizes HChacha20 as well. .Pp Note that the most significant bit of the public key is systematically ignored. -It is not needed, because every public key should be smaller than +It is not needed because every public key should be smaller than 2^255-19, which fits in 255 bits. If another implementation of X25519 gives you a key that's not fully reduced and has its high bit set, the computation will fail. diff --git a/doc/man/man3/crypto_memcmp.3monocypher b/doc/man/man3/crypto_memcmp.3monocypher index cbe9fd9..4ab5e06 100644 --- a/doc/man/man3/crypto_memcmp.3monocypher +++ b/doc/man/man3/crypto_memcmp.3monocypher @@ -12,7 +12,8 @@ .Ft int .Fn crypto_zerocmp "const uint8_t *p" "size_t n" .Sh DESCRIPTION -In crypto, we often need to compare secrets together. +In cryptography, we often need to compare secrets or values derived from +secrets. A message authentication code for instance: while the MAC sent over the network along with a message is public, the true MAC is secret. -- 2.47.3