crypto_blake2b(3monocypher)
implements the Blake2b hash. Blake2b combines the security of SHA-3 and the
speed of MD5. It is immune to length extension attacks and provides a keyed
mode that makes it a safe, easy to use authenticator.

crypto_sign(3monocypher)
and
crypto_check(3monocypher)
implement EdDSA, with Curve25519 and Blake2b. This is the same as the more
famous Ed25519, with SHA-512 replaced by the faster and more secure Blake2b.
Ed25519 (EdDSA with SHA-512), is supported as a compilation option.

Using cryptography securely is difficult. Flaws that never manifest under normal
use might be exploited by a clever adversary. Cryptographic libraries are easy
to misuse. Even Monocypher allows a number of fatal mistakes.

Users should follow a formal introduction to cryptography. We currently
recommend the https://www.crypto101.io/ online course.

Use the facilities of your operating system. Avoid user space random number
generators. They are easy to misuse, which has lead to countless
vulnerabilities in the past. For instance, the random stream may be repeated
if one is not careful with multi-threading, and forward secrecy is lost
without proper key erasure.

Different system calls are available on different systems:

Recent versions of Linux (glibc >= 2.25, Linux >=
3.17), provide getrandom() in
<linux/random.h>.
Do not set any flag.

BSD provides
arc4random_buf() in
<stdlib.h>
or
<bsd/stdlib.h>.
This is easier to use than getrandom().

Windows provides
CryptGenRandom().

The /dev/urandom special file may be used on
systems that do not provide an easy to use system call. Be careful though,
being a file makes /dev/urandom hard to use
correctly and securely. Reads may be interrupted, and more attacks are
possible on a file than on a system call.

The Poly1305 authenticator, X25519, and EdDSA use multiplication. Some older
processors do not multiply in constant time. If the target platform is
something other than x86, x86_64, ARM or ARM64, double check how it handles
multiplication.

Encryption does not hide the length of the input plaintext. Most compression
algorithms work by using fewer bytes to encode previously seen data or common
characters. If an attacker can add data to the input before it is compressed
and encrypted, they can observe changes to the ciphertext length to recover
secrets from the input. Researchers have demonstrated an attack on HTTPS to
steal session cookies when compression is enabled, dubbed "CRIME".

Long term secrets cannot be expected to stay safe indefinitely. Users may reveal
them by mistake, or the host computer might have a vulnerability and be
compromised. To mitigate this problem, some protocols guarantee that past
messages are not compromised even if the long term keys are. This is done by
generating temporary keys, then encrypting messages with them.

In general, secrets that went through a computer should not be compromised when
this computer is stolen or infected at a later point.

A first layer of defence is to explicitly wipe secrets as soon as they are no
longer used. Monocypher already wipes its own temporary buffers, and contexts
are erased with the crypto_*_final() functions.
The secret keys and messages however are the responsibility of the user. Use
crypto_wipe(3monocypher)
to erase them.

A second layer of defence is to ensure those secrets are not swapped to disk
while they are used. There are several ways to do this. The most secure is to
disable swapping entirely. Doing so is recommended on sensitive machines.
Another way is to encrypt the swap partition (this is less safe). Finally,
swap can be disabled locally – this is often the only way.

UNIX systems can disable swap for specific buffers with
mlock(), and disable swap for the whole process
with mlockall(). Windows can disable swap for
specific buffers with VirtualLock().

Core dumps cause similar problems. Disable them. Also beware of suspend to disk
(deep sleep mode), which writes all RAM to disk regardless of swap policy, as
well as virtual machine snapshots. Erasing secrets with
crypto_wipe(3monocypher)
is often the only way to mitigate these dangers.