.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.
.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.
.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 .
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:
.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
.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
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 ,
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 ,
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
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
.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 .
.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
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
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.
.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
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
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 ,
.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
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
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
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
projects / Monocypher.git / commitdiff