and
.Xr crypto_unlock 3monocypher ,
permitting additional data.
-Addiional data is authenticated, but
+Additional data is authenticated, but
.Em not
encrypted.
.Pp
.Ef
.Pp
If you must send unencrypted data, remember that you cannot trust
-unauthenticated data.
-.Em Including the length of the additional data .
+unauthenticated data,
+.Em including the length of the additional data .
If you transmit that length over the wire, you must authenticate it.
(The easiest way to do so is to append that length to the additional
data before you call
You generally do not need this parameter, but it does have some use:
The key is supposed to be unknown to the attacker.
In the context of password derivation, it would stay unknown
-.Em even if an attacker steals your password database.
+.Em even if an attacker steals your password database .
This may be possible if that key is stored separately from your password
database (like on a separate server, and never written on the main
server's disks).
.Sh DESCRIPTION
Blake2b is a fast cryptographically secure hash, based on the ideas of
Chacha20.
-It is faster than md5, yet just as secure as SHA-3.
+It is faster than MD5, yet just as secure as SHA-3.
.Pp
Blake2b is immune to length extension attacks, and as such does not
require any specific precautions, such as using the HMAC algorithm.
.It Fa hash_size
the length of the output hash.
Must be between 1 and 64.
+A value of 64 is recommended.
+Values below 32 are discouraged.
.It Fa key
some secret key.
May be
.Fn crypto_blake2b_general .
The
.Fn crypto_blake2b
-is provided for convenience.
-It uses a 64 bytes hash and no key (this is a good default).
+function is provided for convenience.
+It uses a 64 byte hash and no key.
+These values are good defaults for
+.Fn crypto_blake2b_general_init ,
+too.
.Pp
If you use the
.Fn crypto_blake2b_general
-function, you can specify the size of the hash (sizes below 32 bytes
-are discouraged), and use a secret key to make the hash unpredictable
-\(en useful for message authentication codes.
+function, you can specify the size of the hash, and use a secret key to
+make the hash unpredictable \(en useful for message authentication
+codes.
.Ss Incremental interface
Incremental interfaces are useful to handle streams of data or large
files without using too much memory.
.Fn crypto_blake2b_init
is a convenience initialisation function that
specifies a 64-byte hash and no key.
-This is a good default.
+This is considered a good default.
.Sh RETURN VALUES
These functions return nothing.
.Sh EXAMPLES
.Fa "uint64_t ctr"
.Fc
.Sh DESCRIPTION
-These functions provides an incremental interface for Chacha20, with an
-initialisation, and as many encryption steps as you want.
+These functions provide an incremental interface for Chacha20, with an
+initialisation function, and as many encryption steps as desired.
.Pp
To use these functions, you must first initialize a
.Vt crypto_chacha_ctx
being
.Dv NULL .
This is useful as a user space random number generator.
-Do not use this as a cryptographic random number generator.
+.Sy \&Do not use this as a cryptographic random number generator .
Still, this function can be used outside of a security context:
deterministic procedural generation comes to mind.
.Pp
.Xr crypto_aead_unlock 3monocypher
functions.
It performs an X25519 key exchange, then hashes the shared secret (with
-HChacha20) to get a suitably random-looking shared key.
+HChacha20) to get a suitably random shared key.
.Pp
-Keep in mind that if either of your long term secret keys leaks, it
+Keep in mind that if either of the long term secret keys leaks, it
may compromise
.Em all past messages !
If you want forward secrecy, you will need to exchange temporary public
.Fa your_secret_key
and the other party's public key
.Fa their_public_key .
-.Sy Warning: the shared secret is not cryptographically random.
+.Sy Warning: the shared secret is not cryptographically random .
Do not use it directly as a session key.
You need to hash it first.
Any cryptographically secure hash will do.
.Pp
Note that the most significant bit of the public key is systematically
ignored.
-It is not needed, because every public key should be smaller than
+It is not needed because every public key should be smaller than
2^255-19, which fits in 255 bits.
If another implementation of X25519 gives you a key that's not fully
reduced and has its high bit set, the computation will fail.
.Ft int
.Fn crypto_zerocmp "const uint8_t *p" "size_t n"
.Sh DESCRIPTION
-In crypto, we often need to compare secrets together.
+In cryptography, we often need to compare secrets or values derived from
+secrets.
A message authentication code for instance:
while the MAC sent over the network along with a message is public, the
true MAC is secret.
projects / Monocypher.git / commitdiff