From: Loup Vaillant Date: Tue, 17 Oct 2017 18:52:36 +0000 (+0200) Subject: Manual review: applying CuleX's advice X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=003bd3ce2889e30e7cd30c7465af818904fd291a;p=Monocypher.git Manual review: applying CuleX's advice --- diff --git a/doc/man/man3/crypto_chacha20_encrypt.3monocypher b/doc/man/man3/crypto_chacha20_encrypt.3monocypher index c4b58ae..c797682 100644 --- a/doc/man/man3/crypto_chacha20_encrypt.3monocypher +++ b/doc/man/man3/crypto_chacha20_encrypt.3monocypher @@ -44,31 +44,35 @@ These functions provide an incremental interface for the Chacha20 encryption primitive. .Pp -Chacha20 is a low-level primitive. Consider using authenticated -encryption, implemented by +Chacha20 is a low-level primitive. +Consider using authenticated encryption, implemented by .Xr crypto_lock 3monocypher . .Pp .Fn crypto_chacha20_init initialises the .Vt crypto_chacha_ctx -context. It needs a 32-byte secret +context. +It needs a 32-byte secret .Fa key and an 8-byte .Fa nonce . The nonce must be used only once per secret key (repeating them destroys confidentiality). Counters and (unique) message numbers can -be used as nonces. Random numbers +be used as nonces. +Random numbers .Em cannot : 8-byte nonces are too small to prevent accidental reuse. .Pp .Fn crypto_chacha20_x_init initialises the .Vt crypto_chacha_ctx -context. It needs a 32-byte secret +context. +It needs a 32-byte secret .Fa key and a 24-byte .Fa nonce . -The nonce is big enough to be selected at random. See +The nonce is big enough to be selected at random. +See .Xr intro 3monocypher about generating random numbers (use the operating system's random number generator). @@ -89,7 +93,8 @@ encrypts the by XORing it with a pseudo-random stream of numbers, seeded by the provided .Vt crypto_chacha_ctx -context. Once the encryption is done, the context is updated to allow +context. +Once the encryption is done, the context is updated to allow subsequent calls of .Fn crypto_chacha20_encrypt on the rest of the message, if any. @@ -98,8 +103,8 @@ The .Fa plain_text and .Fa cipher_text -may point to the same buffer for in-place encryption. If they don't, -the buffers they point to +may point to the same buffer for in-place encryption. +If they don't, the buffers they point to .Em must not overlap . .Pp The @@ -109,7 +114,8 @@ pointer is allowed to be (0), in which case it will be interpreted as an all zero input. The cipher_text will then contain the raw Chacha20 stream. .Pp -Decryption is the same as encryption. To Decrypt the +Decryption is the same as encryption. +To Decrypt the .Fa cipher_text , encrypt it again with the same .Fa key @@ -123,11 +129,12 @@ with .Fa plain_text being .Dv NULL . -This is useful as a user space random number generator. While -.Sy \&this must not be used as a cryptographic random number generator , -it can be handy outside of a security context. Deterministic -procedural generation and reproducible property-based tests come to -mind. +This is useful as a user space random number generator. +While +.Sy this must not be used as a cryptographic random number generator , +it can be handy outside of a security context. +Deterministic procedural generation and reproducible property-based +tests come to mind. .Pp .Fn crypto_chacha20_set_ctr resets the internal counter of the @@ -141,8 +148,10 @@ Resuming the encryption will use the stream at the block This can be used to encrypt (or decrypt) part of a long message, or to implement some AEAD constructions such as the one described in RFC 7539 (not implemented in Monocypher because of its complexity and -limitations). Be careful when using this not to accidentally reuse -parts of the random stream. This would destroy confidentiality. +limitations). +Be careful when using this not to accidentally reuse parts of the +random stream. +This would destroy confidentiality. .Sh RETURN VALUES These functions return nothing. They cannot fail. @@ -177,11 +186,9 @@ const uint8_t plain_text [500]; /* Message to be encrypted */ uint8_t cipher_text[500]; /* Will be the encrypted message */ crypto_chacha_ctx ctx; crypto_chacha20_x_init(&ctx, key, nonce); -crypto_chacha20_encrypt(&ctx, cipher_text + 0, plain_text + 0, 100); -crypto_chacha20_encrypt(&ctx, cipher_text + 100, plain_text + 100, 100); -crypto_chacha20_encrypt(&ctx, cipher_text + 200, plain_text + 200, 100); -crypto_chacha20_encrypt(&ctx, cipher_text + 300, plain_text + 300, 100); -crypto_chacha20_encrypt(&ctx, cipher_text + 400, plain_text + 400, 100); +for(int i = 0; i < 500; i += 100) { + crypto_chacha20_encrypt(&ctx, cipher_text+i, plain_text+i, 100); +} .Ed .Pp In place encryption (same results as simple encryption): @@ -229,29 +236,33 @@ crypto_chacha20_encrypt(&ctx, cipher_text, plain_text, 3 * 64); .Xr intro 3monocypher .Sh STANDARDS These functions implement Chacha20 and XChacha20. +Chacha20 is described in rfc7539. +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 .Sy Encryption alone is not sufficient for security . -Chacha20 should never be used alone. It only protects against -eavesdropping, not forgeries. To ensure the integrity of a message, -use Blake2b in keyed mode, or authenticated encryption; see +Chacha20 should never be used alone. +It only protects against eavesdropping, not forgeries. +To ensure the integrity of a message, use Blake2b in keyed mode, or +authenticated encryption; see .Xr crypto_blake2b 3monocypher and .Xr crypto_lock 3monocypher .Pp -When using -.Fn crypto_chacha20_init , -.Pp -Do not reuse a nonce for the same key. This would expose the XOR of -subsequent encrypted messages, and destroy confidentiality. +Do not reuse a nonce for the same key. +This would expose the XOR of subsequent encrypted messages, and +destroy confidentiality. .Pp .Sy do not select small nonces at random . The .Fn crypto_chacha20_init nonce spans only 64 bits, which is small enough to trigger accidental -reuses. A counter should be used instead. If multiple parties send -out messages, Each can start with an initial nonce of 0, 1 .. n-1 -respectively, and increment them by n for each new message. (Make sure -the counters never wrap around). +reuses. +A counter should be used instead. +If multiple parties send out messages, Each can start with an initial +nonce of 0, 1 .. n-1 respectively, and increment them by n for each +new message (make sure the counters never wrap around). .Pp Do not use these functions as cryptographic random number generator. Always use the operating system's random number generator for diff --git a/doc/man/man3/intro.3monocypher b/doc/man/man3/intro.3monocypher index efbb784..5849b0d 100644 --- a/doc/man/man3/intro.3monocypher +++ b/doc/man/man3/intro.3monocypher @@ -19,8 +19,8 @@ misuse, which has lead to countless vulnerabilities in the past, typically by repeating parts of the random stream. .Pp Generating cryptographically secure random numbers portably is -currently impossible without using other libraries. You need system -specific calls: +currently impossible without using other libraries. +You need system specific calls: .Bl -bullet .It On recent versions of Linux (glibc >= 2.25, Linux >= 3.17), you can use