From: Loup Vaillant Date: Sat, 28 Oct 2017 11:56:03 +0000 (+0200) Subject: Manual review: applying CuleX's advice X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=8655f433467eb88dabbeae7bd959d4ee69bb56c6;p=Monocypher.git Manual review: applying CuleX's advice * Removed contractions for a more formal style. * Spelled BLAKE2b upper case. * Put a final period *after* the parenthesis. --- diff --git a/doc/man/man3/crypto_blake2b.3monocypher b/doc/man/man3/crypto_blake2b.3monocypher index e756ac6..36b5b48 100644 --- a/doc/man/man3/crypto_blake2b.3monocypher +++ b/doc/man/man3/crypto_blake2b.3monocypher @@ -49,11 +49,11 @@ .Fa "uint8_t *hash" .Fc .Sh DESCRIPTION -Blake2b is a fast cryptographically secure hash, based on the ideas of +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. .Pp -Blake2b is immune to length extension attacks, and as such does not +BLAKE2b is immune to length extension attacks, and as such does not require any specific precautions, such as using the HMAC algorithm. It can authenticate messages with a naive approach. .Pp @@ -71,12 +71,12 @@ Must be between 1 and 64. Anything below 32 is discouraged. .It Fa key Some secret key. -Those who don't know it cannot predict the final hash. +One cannot predict the final hash without it. May be .Dv NULL if .Fa key_size -is 0. +is 0 (this means there is no key). Keys can be used to create a message authentication code (MAC). Use .Xr crypto_verify16 3monocypher , @@ -87,7 +87,7 @@ to compare MACs created this way. Choose the size of the hash accordingly. Users may want to wipe the key with .Xr crypto_wipe 3monocypher -once they're done with it. +once they are done with it. .It Fa key_size Length of the .Fa key @@ -109,7 +109,7 @@ and .Fn crypto_blake2b , provided for convenience (calling it is the same as calling .Fn crypto_blake2b_general -with a null key and a 64-byte hash.) +with a null key and a 64-byte hash). .Pp .Fn crypto_blake2b_general users can specify the size of the hash, and use a secret key to @@ -201,9 +201,9 @@ crypto_blake2b_final (&ctx, hash); .Xr crypto_lock 3monocypher , .Xr intro 3monocypher .Sh STANDARDS -These functions implement Blake2b. +These functions implement BLAKE2b. .Sh CAVEATS -Monocypher doesn't perform any input verification. +Monocypher does not perform any input verification. Any deviation from the specified input and output length ranges results in .Sy undefined behaviour . diff --git a/doc/man/man3/crypto_chacha20_encrypt.3monocypher b/doc/man/man3/crypto_chacha20_encrypt.3monocypher index dba7cc1..1b6d4fb 100644 --- a/doc/man/man3/crypto_chacha20_encrypt.3monocypher +++ b/doc/man/man3/crypto_chacha20_encrypt.3monocypher @@ -80,8 +80,7 @@ number generator). The recommended initialisation routine is .Fn crypto_chacha20_x_init . The ability to use random nonces makes it easier to use securely, and -the performance hit, equivalent to the encryption of 64 bytes, doesn't -matter in practice. +the performance hit is negligible in practice. .Pp The following functions need an initialised context to work properly. Calling them with an uninitialised context triggers undefined @@ -104,7 +103,7 @@ The and .Fa cipher_text may point to the same buffer for in-place encryption. -If they don't, the buffers they point to +Otherwise, the buffers they point to .Em must not overlap . .Pp The @@ -185,7 +184,7 @@ uint8_t plain_text [500]; /* Will be the decrypted message */ crypto_chacha_ctx ctx; crypto_chacha20_x_init(&ctx, key, nonce); crypto_chacha20_encrypt(&ctx, plain_text, cipher_text, 500); -/* Wipe secrets if they're no longer needed */ +/* Wipe secrets if they are no longer needed */ crypto_wipe(key, sizeof(key)); crypto_wipe(&ctx, sizeof(ctx)); /* The plain text likely needs to be processed before you wipe it */ @@ -202,7 +201,7 @@ crypto_chacha20_x_init(&ctx, key, nonce); for(int i = 0; i < 500; i += 100) { crypto_chacha20_encrypt(&ctx, cipher_text+i, plain_text+i, 100); } -/* Wipe secrets if they're no longer needed */ +/* Wipe secrets if they are no longer needed */ crypto_wipe(key, sizeof(key)); crypto_wipe(&ctx, sizeof(ctx)); crypto_wipe(plain_text, sizeof(plain_text)); @@ -218,7 +217,7 @@ crypto_chacha20_x_init(&ctx, key, nonce); crypto_chacha20_encrypt(&ctx, message, message, 500); crypto_wipe(key, sizeof(key)); crypto_wipe(&ctx, sizeof(ctx)); -/* Wipe secrets if they're no longer needed */ +/* Wipe secrets if they are no longer needed */ crypto_wipe(key, sizeof(key)); crypto_wipe(&ctx, sizeof(ctx)); .Ed @@ -235,7 +234,7 @@ crypto_chacha20_init(&ctx, key, nonce); crypto_chacha20_encrypt(&ctx, cipher_text, plain_text, 500); crypto_wipe(key, sizeof(key)); crypto_wipe(&ctx, sizeof(ctx)); -/* Wipe secrets if they're no longer needed */ +/* Wipe secrets if they are no longer needed */ crypto_wipe(key, sizeof(key)); crypto_wipe(&ctx, sizeof(ctx)); crypto_wipe(plain_text, sizeof(plain_text)); @@ -258,7 +257,7 @@ crypto_chacha20_encrypt(&ctx, /* ...then encrypt the first part */ crypto_chacha20_set_ctr(&ctx, 0); crypto_chacha20_encrypt(&ctx, cipher_text, plain_text, 3 * 64); -/* Wipe secrets if they're no longer needed */ +/* Wipe secrets if they are no longer needed */ crypto_wipe(key, sizeof(key)); crypto_wipe(&ctx, sizeof(ctx)); crypto_wipe(plain_text, sizeof(plain_text)); @@ -274,7 +273,7 @@ XChacha20 derives from Chacha20 the same way XSalsa20 derives from Salsa20, and benefits from the same security reduction (proven secure as long as Chacha20 itself is secure). .Sh SECURITY CONSIDERATIONS -.Ss Encrypted doesn't mean secure +.Ss Encrypted does not mean secure Chacha20 only protects against eavesdropping, not forgeries. Most applications need protection against forgeries to be properly secure. diff --git a/doc/man/man3/crypto_poly1305_auth.3monocypher b/doc/man/man3/crypto_poly1305_auth.3monocypher index 255f050..743d4b9 100644 --- a/doc/man/man3/crypto_poly1305_auth.3monocypher +++ b/doc/man/man3/crypto_poly1305_auth.3monocypher @@ -183,8 +183,8 @@ Use .Xr crypto_verify16 3monocypher To compare message authentication code. Avoid standard buffer comparison functions. -They don't run in constant time, and allow attackers to recover the -MAC in relatively few tries. +They do not run in constant time, which allows attackers to recover +the MAC in relatively few tries. .Pp The authentication key should be wiped with .Xr crypto_wipe 3monocypher