.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.
.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
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
.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.
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) */
.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 .
.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
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
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
.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
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.
.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
.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
.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
projects / Monocypher.git / commitdiff