From: Loup Vaillant Date: Sat, 23 Dec 2017 11:38:01 +0000 (+0100) Subject: Manual: add missing args blocks X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=ea8d396d9af37604511263e1a5e9910540fddfb4;p=Monocypher.git Manual: add missing args blocks --- diff --git a/doc/man/man3/crypto_chacha20_H.3monocypher b/doc/man/man3/crypto_chacha20_H.3monocypher index 4b7d266..7986c33 100644 --- a/doc/man/man3/crypto_chacha20_H.3monocypher +++ b/doc/man/man3/crypto_chacha20_H.3monocypher @@ -22,18 +22,21 @@ Use .Xr crypto_blake2b 3monocypher instead. .Pp -The output -.Fa out -is a cryptographically secure random number +The arguments are: +.Bl -tag -width Ds +.It Fa key +A sufficiently random key, such as the output of +.Xr crypto_x25519 3monocypher . +.It Fa in +The space reserved for the Chacha20 nonce and counter. +It does not have to be random. +.It Fa out +A cryptographically secure random number .Em if there is enough entropy in the input .Fa key . X25519 shared secrets have enough entropy. -The input -.Fa in -fills the space reserved for the -nonce and counter. -It does not have to be random. +.El .Sh RETURN VALUES This function returns nothing. It cannot fail. diff --git a/doc/man/man3/crypto_chacha20_encrypt.3monocypher b/doc/man/man3/crypto_chacha20_encrypt.3monocypher index 8ca9224..e7d95f9 100644 --- a/doc/man/man3/crypto_chacha20_encrypt.3monocypher +++ b/doc/man/man3/crypto_chacha20_encrypt.3monocypher @@ -33,7 +33,7 @@ .Fo crypto_chacha20_stream .Fa "crypto_chacha_ctx *ctx" .Fa "uint8_t *stream" -.Fa "size_t size" +.Fa "size_t stream_size" .Fc .Ft void .Fo crypto_chacha20_set_ctr @@ -48,34 +48,70 @@ Chacha20 is a low-level primitive. Consider using authenticated encryption, implemented by .Xr crypto_lock 3monocypher . .Pp +The arguments are: +.Bl -tag -width Ds +.It Fa key +A 32-byte secret key. +.It Fa nonce +An 8 or 24 byte number, used only once with any given key. +It does not need to be secret or random, but it does have to be unique. +Repeating a nonce with the same key reveals the XOR of two different +messages, which allows decryption. +24 byte nonces can be selected at random. +8 byte nonces +.Em cannot . +They are too small, and the same number may be selected twice by +accident. +See +.Xr intro 3monocypher +for advice about generating random numbers (use the operating system's +random number generator). +.It Fa plain_text +The message to encrypt. +It is allowed to be +.Dv NULL , +in which case it will be interpreted as an all zero input. +The cipher_text will then contain the raw Chacha20 stream. +.It Fa cipher_text +The encrypted message, to be transmitted over the network. +.It Fa text_size +The size of both +.Fa plain_text and +.Fa cipher_text . +.It Fa stream +the raw Chacha20 stream. +.It Fa stream_size +The size of the stream. +.It Fa ctr +The number of 64-byte blocks since the beginning of the stream. +.El +.Pp +The +.Fa key +and +.Fa nonce +buffers may overlap. +The +.Fa plain_text +and +.Fa cipher_text +buffers may +.Em not . +They must either be the same buffer (for in-place encryption), or +disjoint. +.Pp .Fn crypto_chacha20_init initialises the .Vt crypto_chacha_ctx 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 -.Em cannot : -8-byte nonces are too small to prevent accidental reuse. +It uses an 8 byte nonce, too small to be selected at random. +Use a counter. .Pp .Fn crypto_chacha20_x_init initialises the .Vt crypto_chacha_ctx 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 -.Xr intro 3monocypher -for advice about generating random numbers (use the operating system's -random number generator). +It uses 24-byte nonce, big enough to be selected at random. .Pp .Fn crypto_chacha20_x_init is recommended over @@ -98,20 +134,11 @@ You may call .Fn crypto_chacha20_encrypt repeatedly with the same context struct to encrypt a message incrementally. -.Pp -.Fa plain_text -and -.Fa cipher_text -may point to the same buffer for in-place encryption. -Otherwise, the buffers they point to -.Em must not overlap . -.Pp The .Fa plain_text pointer is allowed to be .Dv NULL , in which case it will be interpreted as an all zero input. -The cipher_text will then contain the raw Chacha20 stream. .Pp Since XOR is its own inverse, decryption is the same operation as encryption. @@ -227,7 +254,10 @@ crypto_wipe(&ctx, sizeof(ctx)); crypto_wipe(plain_text, sizeof(plain_text)); .Ed .Pp -Encryption by jumping around (don't do that): +Encryption by jumping around (do not do that, this is only meant to show +how +.Fn crypto_chacha20_set_ctr +works): .Bd -literal -offset indent const uint8_t key [ 32]; /* Secret random key */ const uint8_t nonce [ 24]; /* Unique nonce (possibly random) */ @@ -271,7 +301,7 @@ and .Xr crypto_lock 3monocypher .Ss Nonce reuse Repeating a nonce with the same key exposes the XOR of two or more -plaintext messages, effectively destroying confidentiality. +plain text messages, effectively destroying confidentiality. .Pp For the same reason, .Sy do not select small nonces at random . diff --git a/doc/man/man3/crypto_key_exchange.3monocypher b/doc/man/man3/crypto_key_exchange.3monocypher index 3c686dd..9427fc6 100644 --- a/doc/man/man3/crypto_key_exchange.3monocypher +++ b/doc/man/man3/crypto_key_exchange.3monocypher @@ -21,16 +21,37 @@ .Sh DESCRIPTION .Fn crypto_key_exchange computes a shared key with your secret key and their public key, -suitable for use with the -.Xr crypto_lock 3monocypher -family of functions. .Pp .Fn crypto_x25519_public_key deterministically computes the public key from a random secret key. +.Pp +The arguments are: +.Bl -tag -width Ds +.It Fa shared_key +The shared secret, known only to those who know a relevant secret key +(yours or theirs). +It is cryptographically random, and suitable for use with the +.Xr crypto_lock 3monocypher +family of functions. +.It Fa your_secret_key +A 32 byte random number, known only to you. See .Xr intro 3monocypher for advice about generating random bytes (use the operating system's random number generator). +Do not use the same private key for both key exchanges and signatures. +The public keys are different, and revealing both may leak information. +.It Fa their_public_key +The public key of the other party, generated from their secret key with +.Fn crypto_x25519_public_key . +.It Fa public_key +The public key, generated from a +.Fa secret_key +with +.Fn crypto_x25519_public_key . +.It Fa secret_key +A 32 byte random number, known only to you. +.El .Sh RETURN VALUES Some public keys force the shared key to a known constant. .Fn crypto_key_exchange diff --git a/doc/man/man3/crypto_lock.3monocypher b/doc/man/man3/crypto_lock.3monocypher index 50afe87..29db10c 100644 --- a/doc/man/man3/crypto_lock.3monocypher +++ b/doc/man/man3/crypto_lock.3monocypher @@ -100,6 +100,10 @@ See for details. .It Fa cipher_text The encrypted message, to be transmitted over the network. +.It Fa text_size +The size of both +.Fa plain_text and +.Fa cipher_text . .El .Pp The diff --git a/doc/man/man3/crypto_poly1305.3monocypher b/doc/man/man3/crypto_poly1305.3monocypher index 47d7423..a6bc95a 100644 --- a/doc/man/man3/crypto_poly1305.3monocypher +++ b/doc/man/man3/crypto_poly1305.3monocypher @@ -42,25 +42,35 @@ correctly. Poly1305 is a low-level primitive. Consider using authenticated encryption, implemented by .Xr crypto_lock 3monocypher . +.Pp +The arguments are: +.Bl -tag -width Ds +.It Fa mac +The authentication code. +.It Fa key +The secret authentication key. +Use only once per message. +Do not use the session key to authenticate messages. +It should be wiped with +.Xr crypto_wipe 3monocypher +after use. +.It Fa message +The message to authenticate. +May overlap with the +.Fa mac +argument. +.It Fa message_size +Size of the message. +.El .Ss Direct interface .Fn crypto_poly1305 produces a message authentication code for the given message and authentication key. -.Fa mac -and -.Fa message -may overlap. -.Pp -.Fa key -should be wiped with -.Xr crypto_wipe 3monocypher -after being used. -.Pp To verify the integrity of a message, use .Xr crypto_verify16 3monocypher to compare the received MAC to the output .Fa mac . -.Ss Streaming interface +.Ss Incremental interface .Fn crypto_poly1305_init initialises a context. .Fa key diff --git a/doc/man/man3/crypto_sign.3monocypher b/doc/man/man3/crypto_sign.3monocypher index a3abe15..705b441 100644 --- a/doc/man/man3/crypto_sign.3monocypher +++ b/doc/man/man3/crypto_sign.3monocypher @@ -29,19 +29,40 @@ .Fa "size_t message_size" .Fc .Sh DESCRIPTION -.Fn crypto_sign_public_key -deterministically computes a public key from the specified -secret key. -The secret key must be random. +.Fn crypto_sign +and +.Fn crypto_check +provide EdDSA public key signatures and verification. +.Pp +The arguments are: +.Bl -tag -width Ds +.It Fa secret_key +A 32 byte random number, known only to you. See .Xr intro 3monocypher about random number generation (use your operating system's random number generator). -The key pairs generated here are -.Em not -the same as those used for -.Xr crypto_key_exchange 3monocypher . -Do not use the same private key for both purposes. +Do not use the same private key for both signatures and key exchanges. +The public keys are different, and revealing both may leak information. +.It Fa public_key +The public key, generated from a +.Fa secret_key +with +.Fn crypto_sign_public_key . +.It Fa message +Message to sign. +.It Fa message_size +Size of the message, in bytes. +.El +.Pp +The +.Fa signature +and the +.Fa message +arguments may overlap. +.Pp +.Fn crypto_sign_public_key +computes the public key of the specified secret key. .Pp .Fn crypto_sign signs a message with @@ -53,11 +74,7 @@ This recomputation doubles the execution time. checks that a given signature is genuine. Meaning, only someone who had the private key could have signed the message. -.Pp -.Fn crypto_check -does -.Em not -run in constant time. +.Sy \It does not run in constant time . It does not have to in most threat models, because nothing is secret: everyone knows the public key, and the signature and message are rarely secret. @@ -65,12 +82,6 @@ To ascertain the origin of a secret message, use .Xr crypto_key_exchange 3monocypher instead. .Pp -The -.Fa signature -and the -.Fa message -arguments may overlap. -.Pp An incremental interface is available; see .Xr crypto_sign_init_first_pass 3monocypher . .Sh RETURN VALUES diff --git a/doc/man/man3/crypto_sign_init_first_pass.3monocypher b/doc/man/man3/crypto_sign_init_first_pass.3monocypher index 6c62cd7..f850be0 100644 --- a/doc/man/man3/crypto_sign_init_first_pass.3monocypher +++ b/doc/man/man3/crypto_sign_init_first_pass.3monocypher @@ -56,6 +56,9 @@ and .Xr crypto_check 3monocypher . Prefer those more simple functions if possible. .Pp +The arguments are the same as those described in +.Xr crypto_sign 3monocypher . +.Pp This incremental interface can be used to sign or verify messages too large to fit in a single buffer. The arguments are the same as the direct interface described in diff --git a/doc/man/man3/crypto_x25519.3monocypher b/doc/man/man3/crypto_x25519.3monocypher index ef9f9d6..7fb8ab8 100644 --- a/doc/man/man3/crypto_x25519.3monocypher +++ b/doc/man/man3/crypto_x25519.3monocypher @@ -18,19 +18,33 @@ computes a shared secret with .Fa your_secret_key and .Fa their_public_key . -.Sy The shared secret is not cryptographically random . -Do not use it directly as a session key. +It is a low-level primitive. +Users should use +.Xr crypto_key_exchange 3monocypher +unless they have a specific reason not to. +.Pp +The arguments are: +.Bl -tag -width Ds +.It Fa raw_shared_secret +The shared secret, known only to those who know a relevant secret key +(yours or theirs). +It is not cryptographically random. +Do not use it directly as a key. Hash it with .Xr crypto_chacha20_H 3monocypher or .Xr crypto_blake2b 3monocypher first. -.Pp -.Fn crypto_x25519 -is a low-level primitive. -Users should use -.Xr crypto_key_exchange 3monocypher -unless they have a specific reason not to. +.It Fa your_secret_key +A 32 byte secret random number. +See +.Xr intro 3monocypher +for advice about generating random bytes (use the operating system's +random number generator). +.It Fa their_public_key +The public key of the other party, generated from their secret key with +.Xr crypto_x25519_public_key 3monocypher . +.El .Sh RETURN VALUES Some public keys force the shared key to a known constant. This function returns -1 if it detects such a public key, otherwise it