From: Loup Vaillant Date: Sun, 5 Nov 2017 17:43:24 +0000 (+0100) Subject: Removed "The *** function" patterns X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=d1bc6039199902be87eee0cc9640c193dceb1b18;p=Monocypher.git Removed "The *** function" patterns --- diff --git a/doc/man/man3/crypto_chacha20_H.3monocypher b/doc/man/man3/crypto_chacha20_H.3monocypher index 23d2640..1276826 100644 --- a/doc/man/man3/crypto_chacha20_H.3monocypher +++ b/doc/man/man3/crypto_chacha20_H.3monocypher @@ -13,9 +13,8 @@ .Fa "const uint8_t in[16]" .Fc .Sh DESCRIPTION -The .Fn crypto_chacha20_H -function provides a not-so-cryptographic hash. +provides a not-so-cryptographic hash. It may be used for some specific purposes, such as X25519 key derivation, or XChacha20 initialisation. If in doubt, do not use directly. @@ -53,7 +52,9 @@ crypto_wipe(in , 16); .Xr crypto_chacha20_encrypt 3monocypher , .Xr crypto_key_exchange 3monocypher , .Xr intro 3monocypher +.Sh STANDARDS +This function implements HChacha20. +HChacha20 derives from Chacha20 the same way HSalsa20 derives from +Salsa20. .Sh CAVEATS .Sy This is not a general-purpose cryptographic hash function . -.Sh IMPLEMENTATION DETAILS -This function implements HChacha20. diff --git a/doc/man/man3/crypto_key_exchange.3monocypher b/doc/man/man3/crypto_key_exchange.3monocypher index e64d6e7..c56bfc4 100644 --- a/doc/man/man3/crypto_key_exchange.3monocypher +++ b/doc/man/man3/crypto_key_exchange.3monocypher @@ -26,27 +26,24 @@ .Fa "const uint8_t their_public_key[32]" .Fc .Sh DESCRIPTION -The .Fn crypto_key_exchange -function computes a shared key with your secret key and their public -key, suitable for the +computes a shared key with your secret key and their public key, +suitable for the .Xr crypto_lock 3monocypher family of functions. It performs an X25519 key exchange, then hashes the shared secret with HChacha20 to get a suitably random shared key. .Pp -The .Fn crypto_x25519_public_key -function deterministically computes the public key from a random +deterministically computes the public key from a random .Fa secret_key . See .Xr intro 3monocypher about generating random bytes (use the operating system's random number generator). .Pp -The .Fn crypto_x25519 -function computes a shared secret with +computes a shared secret with .Fa your_secret_key and .Fa their_public_key . @@ -57,19 +54,17 @@ Hash it first with or .Xr crypto_blake2b . .Sh RETURN VALUES -The .Fn crypto_key_exchange and .Fn crypto_x25519 -functions return zero on success, or -1 on failure. +return zero on success, or -1 on failure. The return value serves as a security check: some public keys force the shared key to a known constant. This never happens with legitimate public keys, but if the ones you process are not known to be trustworthy, check the return value. .Pp -The .Fn crypto_x25519_public_key -function returns nothing. +returns nothing. It cannot fail. .Sh EXAMPLES Generate a public key from a randomly generated secret key: @@ -123,9 +118,8 @@ crypto_wipe(shared_secret, 32); /* wipe the unneeded secret */ .Xr intro 3monocypher .Sh STANDARDS These functions implement X25519, described in RFC 7748. -The .Fn crypto_key_exchange -function uses HChacha20 as well. +uses HChacha20 as well. .Sh SECURITY CONSIDERATIONS If either of the long term secret keys leaks, it may compromise diff --git a/doc/man/man3/crypto_lock.3monocypher b/doc/man/man3/crypto_lock.3monocypher index 6513e8d..ba84851 100644 --- a/doc/man/man3/crypto_lock.3monocypher +++ b/doc/man/man3/crypto_lock.3monocypher @@ -50,12 +50,10 @@ .Fa "size_t text_size" .Fc .Sh DESCRIPTION -The .Fn crypto_lock -function encrypts and authenticates a plaintext. -It can be decrypted by the -.Fn crypto_unlock -function. +encrypts and authenticates a plaintext. +It can be decrypted by +.Fn crypto_unlock . The arguments are: .Bl -tag -width Ds .It Fa key @@ -112,20 +110,18 @@ and arguments may point to the same buffer for in-place encryption. Otherwise, the buffers they point to must not overlap. .Pp -The .Fn crypto_unlock -function first checks the integrity of an encrypted message. +first checks the integrity of an encrypted message. If it has been corrupted, .Fn crypto_unlock returns -1 immediately. Otherwise, it decrypts the message, then returns zero. .Em Always check the return value . .Pp -The .Fn crypto_aead_lock and .Fn crypto_aead_unlock -functions are variants of +are variants of .Fn crypto_lock and .Fn crypto_unlock , @@ -161,18 +157,15 @@ This may cause buffer overflows in some programs. An incremental interface is available; see .Xr crypto_lock_init 3monocypher . .Sh RETURN VALUES -The .Fn crypto_lock and .Fn crypto_aead_lock -functions return nothing. +return nothing. They cannot fail. -The .Fn crypto_unlock and .Fn crypto_aead_unlock -functions return 0 on success or -1 if the message was corrupted -(i.e. +return 0 on success or -1 if the message was corrupted (i.e. .Fa mac mismatched the combination of .Fa key , @@ -259,12 +252,10 @@ 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 IMPLEMENTATION DETAILS -The .Fn crypto_aead_lock and .Fn crypto_aead_unlock -functions do not authenticate the length themselves to make them -compatible with +do not authenticate the length themselves to make them compatible with .Fn crypto_lock and .Fn crypto_unlock diff --git a/doc/man/man3/crypto_lock_init.3monocypher b/doc/man/man3/crypto_lock_init.3monocypher index 2dde8c6..7ad982e 100644 --- a/doc/man/man3/crypto_lock_init.3monocypher +++ b/doc/man/man3/crypto_lock_init.3monocypher @@ -102,9 +102,8 @@ authentication, it treats corrupted messages three times slower than the direct interface. Users who expect a high corruption rate may want a different approach. .Pp -The .Fn crypto_lock_encrypt -function encrypts or decrypts data +encrypts or decrypts data .Em without authenticating it . It is meant as a building block. Used with @@ -117,19 +116,17 @@ and .Fn crypto_unlock_update instead. .Sh RETURN VALUES -The .Fn crypto_lock_init , .Fn crypto_lock_auth , .Fn crypto_lock_encrypt , .Fn crypto_lock_update , and .Fn crypto_lock_final -functions return nothing. +return nothing. They cannot fail. .Pp -The .Fn crypto_unlock_final -function returns 0 on success or -1 if the message was corrupted. +returns 0 on success or -1 if the message was corrupted. Corruption can happen because of transmission errors, programmer error, or attacker interference. .Em Always check the return value . diff --git a/doc/man/man3/crypto_memcmp.3monocypher b/doc/man/man3/crypto_memcmp.3monocypher index f43748d..ed3ee21 100644 --- a/doc/man/man3/crypto_memcmp.3monocypher +++ b/doc/man/man3/crypto_memcmp.3monocypher @@ -12,11 +12,10 @@ .Ft int .Fn crypto_zerocmp "const uint8_t *p" "size_t n" .Sh DESCRIPTION -The .Fn crypto_memcmp and .Fn crypto_zerocmp -functions were meant to provide timing-safe data comparison. +were meant to provide timing-safe data comparison. They have been removed from Monocypher because they could not uphold those guarantees when compiled with .Fl O3 diff --git a/doc/man/man3/crypto_poly1305_auth.3monocypher b/doc/man/man3/crypto_poly1305_auth.3monocypher index 743d4b9..2195cae 100644 --- a/doc/man/man3/crypto_poly1305_auth.3monocypher +++ b/doc/man/man3/crypto_poly1305_auth.3monocypher @@ -45,9 +45,8 @@ Poly1305 is a low-level primitive. Consider using authenticated encryption, implemented by .Xr crypto_lock 3monocypher . .Ss Direct interface -The .Fn crypto_poly1305_auth -function produces a message authentication code for the given +produces a message authentication code for the given message and authentication key. The authentication key must be used only once. .Fa mac @@ -65,9 +64,8 @@ To verify the integrity of a message, use to compare the received MAC to the output .Fa mac . .Ss Streaming interface -The .Fn crypto_poly1305_init -function initialises a context. +initialises a context. The .Fa key should be wiped once the context is initialised. diff --git a/doc/man/man3/crypto_sign.3monocypher b/doc/man/man3/crypto_sign.3monocypher index e7562d6..1d5cabd 100644 --- a/doc/man/man3/crypto_sign.3monocypher +++ b/doc/man/man3/crypto_sign.3monocypher @@ -29,9 +29,8 @@ .Fa "size_t message_size" .Fc .Sh DESCRIPTION -The .Fn crypto_sign_public_key -function deterministically computes a public key from the specified +deterministically computes a public key from the specified secret key. That key must be random. See @@ -75,16 +74,14 @@ arguments may overlap. An incremental interface is available; see .Xr crypto_sign_init_first_pass 3monocypher . .Sh RETURN VALUES -The .Fn crypto_sign_public_key and .Fn crypto_sign -functions return nothing. +return nothing. They cannot fail. .Pp -The .Fn crypto_check -function returns zero for legitimate messages and -1 for forgeries. +returns zero for legitimate messages and -1 for forgeries. .Sh EXAMPLES Generate a public key from a random secret key: .Bd -literal -offset indent diff --git a/doc/man/man3/crypto_sign_init_first_pass.3monocypher b/doc/man/man3/crypto_sign_init_first_pass.3monocypher index 0d9ce67..1301aab 100644 --- a/doc/man/man3/crypto_sign_init_first_pass.3monocypher +++ b/doc/man/man3/crypto_sign_init_first_pass.3monocypher @@ -95,7 +95,6 @@ You do not have to wipe the context structs with Signatures made with this interface are compatible with the direct interface and vice-versa. .Sh RETURN VALUES -The .Fn crypto_sign_init_first_pass , .Fn crypto_sign_init_second_pass , .Fn crypto_sign_update , @@ -103,12 +102,11 @@ The .Fn crypto_check_init and .Fn crypto_check_update -functions return nothing. +return nothing. They cannot fail. .Pp -The .Fn crypto_check_final -function returns zero for legitimate messages and -1 for forgeries. +returns zero for legitimate messages and -1 for forgeries. .Sh EXAMPLES This example signs a random message and verifies the signature. .Bd -literal -offset indent diff --git a/doc/man/man3/crypto_verify16.3monocypher b/doc/man/man3/crypto_verify16.3monocypher index fead04e..2ccdc64 100644 --- a/doc/man/man3/crypto_verify16.3monocypher +++ b/doc/man/man3/crypto_verify16.3monocypher @@ -32,12 +32,11 @@ forge a message. This has lead to practical attacks in the past. .Pp To avoid such catastrophic failure, -the .Fn crypto_verify16 , .Fn crypto_verify32 and .Fn crypto_verify64 -functions provide comparison functions whose timing is independent from +provide comparison functions whose timing is independent from the content of their input. They compare the first 16, 32, or 64 bytes of the two byte arrays diff --git a/doc/man/man3/intro.3monocypher b/doc/man/man3/intro.3monocypher index e4d3af4..69a9498 100644 --- a/doc/man/man3/intro.3monocypher +++ b/doc/man/man3/intro.3monocypher @@ -39,9 +39,8 @@ or This is arguably even easier to use than .Fn getrandom . .It -Windows provides the -.Fn CryptGenRandom -function. +Windows provides +.Fn CryptGenRandom . .El .Pp If no easy to use system call is available on your system, you may @@ -85,7 +84,7 @@ It is recommended to also use to clear secrets from memory as soon as possible to mitigate these dangers. .Ss Index -Monocypher provides functions the following: +Monocypher provides the following: .Bl -ohang -offset indent .It Authenticated encryption .Bl -tag -offset indent-two -width Ds