.\" This file is dual-licensed.  Choose whichever you want.
.\"
.\" The first licence is a regular 2-clause BSD licence.  The second licence
.\" is the CC-0 from Creative Commons. It is intended to release Monocypher
.\" to the public domain.  The BSD licence serves as a fallback option.
.\"
.\" SPDX-License-Identifier: BSD-2-Clause OR CC0-1.0
.\"
.\" ----------------------------------------------------------------------------
.\"
.\" Copyright (c) 2017-2021 Loup Vaillant
.\" Copyright (c) 2018 Michael Savage
.\" Copyright (c) 2017, 2019-2022 Fabio Scotoni
.\" All rights reserved.
.\"
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" ----------------------------------------------------------------------------
.\"
.\" Written in 2017-2022 by Loup Vaillant, Michael Savage and Fabio Scotoni
.\"
.\" To the extent possible under law, the author(s) have dedicated all copyright
.\" and related neighboring rights to this software to the public domain
.\" worldwide.  This software is distributed without any warranty.
.\"
.\" You should have received a copy of the CC0 Public Domain Dedication along
.\" with this software.  If not, see
.\" <https://creativecommons.org/publicdomain/zero/1.0/>
.\"
.Dd February 20, 2022
.Dt INTRO 3MONOCYPHER
.Os
.Sh NAME
.Nm intro
.Nd introduction to Monocypher
.Sh DESCRIPTION
Monocypher is a cryptographic library.
It provides functions for authenticated encryption, hashing, password
hashing and key derivation, key exchange, and public key signatures.
.Ss Authenticated encryption
.Xr crypto_aead_lock 3monocypher
and
.Xr crypto_aead_unlock 3monocypher
use the ChaCha20 cipher and the Poly1305 one-time authenticator.
There is also an incremental interface to facilitate
file encryption and encrypted streams.
.Pp
ChaCha20 is a stream cipher based on a cryptographic hash function.
It runs efficiently on a wide variety of hardware, and unlike AES
naturally runs in constant time on all hardware.
.Pp
Poly1305 is a one-time authenticator, derived from Carter & Wegman
universal hashing.
It is very fast and very simple.
.Ss Hashing
.Xr 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.
.Ss Password hashing and key derivation
.Xr crypto_argon2 3monocypher
implements the Argon2 resource intensive hash algorithm,
which can be used to hash passwords for storage and to derive keys
from passwords.
Argon2 won the password hashing competition in 2015.
Unlike scrypt, the Argon2i variant is immune to timing attacks.
.Ss Key exchange (Public Key Cryptography)
.Xr crypto_x25519 3monocypher
implements X25519, an elliptic curve Diffie Hellman key exchange
algorithm based on Curve25519.
X25519 derives a shared secret from two private/public key pairs.
It is fast, simple, and relatively easy to implement securely.
.Pp
For specialised protocols that require indistinguishability from random
noise,
.Xr crypto_elligator_rev 3monocypher
gives the option to disguise ephemeral (one-time use) X25519 public keys
as random noise.
.Ss Public key signatures
.Xr crypto_eddsa_sign 3monocypher
and
.Xr crypto_eddsa_check 3monocypher
implement EdDSA, with Curve25519 and BLAKE2b.
This is the same as the more famous Ed25519, with SHA-512 replaced by
the faster BLAKE2b.
.Ss Constant time comparison
.Xr crypto_verify16 3monocypher ,
.Xr crypto_verify32 3monocypher ,
and
.Xr crypto_verify64 3monocypher
compare buffers in constant time.
They should be used to compare secrets to prevent timing attacks.
.Ss Memory wipe
.Xr crypto_wipe 3monocypher
wipes a buffer.
It is meant to erase secrets when they are no longer needed, to reduce
the chances of leaks.
.Ss Optional code
If Monocypher was compiled and installed with the provided makefile,
SHA-512 functions become available as well.
See
.Xr crypto_ed25519_sign 3monocypher ,
and
.Xr crypto_sha512 3monocypher .
.Sh SEE ALSO
.Xr crypto_aead_init_djb 3monocypher ,
.Xr crypto_aead_init_ietf 3monocypher ,
.Xr crypto_aead_init_x 3monocypher ,
.Xr crypto_aead_lock 3monocypher ,
.Xr crypto_aead_read 3monocypher ,
.Xr crypto_aead_unlock 3monocypher ,
.Xr crypto_aead_write 3monocypher ,
.Xr crypto_argon2 3monocypher ,
.Xr crypto_blake2b 3monocypher ,
.Xr crypto_blake2b_final 3monocypher ,
.Xr crypto_blake2b_init 3monocypher ,
.Xr crypto_blake2b_keyed 3monocypher ,
.Xr crypto_blake2b_keyed_init 3monocypher ,
.Xr crypto_blake2b_update 3monocypher ,
.Xr crypto_chacha20_djb 3monocypher ,
.Xr crypto_chacha20_h 3monocypher ,
.Xr crypto_chacha20_ietf 3monocypher ,
.Xr crypto_chacha20_x 3monocypher ,
.Xr crypto_eddsa_check 3monocypher ,
.Xr crypto_eddsa_check_equation 3monocypher ,
.Xr crypto_eddsa_key_pair 3monocypher ,
.Xr crypto_eddsa_mul_add 3monocypher ,
.Xr crypto_eddsa_reduce 3monocypher ,
.Xr crypto_eddsa_scalarbase 3monocypher ,
.Xr crypto_eddsa_sign 3monocypher ,
.Xr crypto_eddsa_to_x25519 3monocypher ,
.Xr crypto_eddsa_trim_scalar 3monocypher ,
.Xr crypto_elligator_key_pair 3monocypher ,
.Xr crypto_elligator_map 3monocypher ,
.Xr crypto_elligator_rev 3monocypher ,
.Xr crypto_poly1305 3monocypher ,
.Xr crypto_poly1305_final 3monocypher ,
.Xr crypto_poly1305_init 3monocypher ,
.Xr crypto_poly1305_update 3monocypher ,
.Xr crypto_verify16 3monocypher ,
.Xr crypto_verify32 3monocypher ,
.Xr crypto_verify64 3monocypher ,
.Xr crypto_wipe 3monocypher ,
.Xr crypto_x25519 3monocypher ,
.Xr crypto_x25519_dirty_fast 3monocypher ,
.Xr crypto_x25519_dirty_small 3monocypher ,
.Xr crypto_x25519_inverse 3monocypher ,
.Xr crypto_x25519_public_key 3monocypher ,
.Xr crypto_x25519_to_eddsa 3monocypher
.Ss Optional code
.Xr crypto_ed25519_check 3monocypher ,
.Xr crypto_ed25519_key_pair 3monocypher ,
.Xr crypto_ed25519_ph_check 3monocypher ,
.Xr crypto_ed25519_ph_sign 3monocypher ,
.Xr crypto_ed25519_sign 3monocypher ,
.Xr crypto_sha512 3monocypher ,
.Xr crypto_sha512_final 3monocypher ,
.Xr crypto_sha512_hkdf 3monocypher ,
.Xr crypto_sha512_hkdf_expand 3monocypher ,
.Xr crypto_sha512_hmac 3monocypher ,
.Xr crypto_sha512_hmac_final 3monocypher ,
.Xr crypto_sha512_hmac_init 3monocypher ,
.Xr crypto_sha512_hmac_update 3monocypher ,
.Xr crypto_sha512_init 3monocypher ,
.Xr crypto_sha512_update 3monocypher
.Sh CAVEATS
Monocypher does not perform any input validation.
Any deviation from the specified input and output length ranges results
in
.Sy undefined behaviour .
Make sure your inputs are correct.
.Sh SECURITY CONSIDERATIONS
Using cryptography securely is difficult.
Flaws that never manifest under normal use might be exploited by a
clever adversary.
Cryptographic libraries are easy to catastrophically misuse,
and Monocypher is no exception.
.Pp
Users should follow a formal introduction to cryptography.
We currently recommend the
.Lk https://www.crypto101.io/ "Crypto 101 online course" .
.Ss Random number generation
Use the facilities of your operating system.
Avoid user space random number generators,
whose misuse has led 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.
.Pp
Different system calls are available on different systems:
.Bl -bullet
.It
Recent versions of Linux (glibc >= 2.25, Linux >= 3.17), provide
.Fn getrandom
in
.In sys/random.h .
Do not set any flag.
.It
BSD, Darwin/macOS, illumos, and Solaris provide
.Fn arc4random_buf
in
.In stdlib.h
or
.In bsd/stdlib.h .
This is easier to use than
.Fn getrandom .
.It
Windows provides
.Fn BCryptGenRandom .
.El
.Pp
The
.Pa /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
.Pa /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.
.Ss Timing attacks
Monocypher runs in
.Dq constant time .
There is no flow from secrets to timings.
No secret dependent indices, no secret dependent branches.
Nevertheless, there are a couple important caveats.
.Pp
Comparing secrets should be done with constant-time comparison
functions, such as
.Xr crypto_verify16 3monocypher ,
.Xr crypto_verify32 3monocypher ,
or
.Xr crypto_verify64 3monocypher .
Do not use standard comparison functions.
They tend to stop as soon as a difference is spotted.
In many cases this enables attackers to recover the secrets and
destroy all security.
.Pp
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 Intel or AMD x86_64,
double check how it handles multiplication.
In particular,
.Em ARM Cortex-M CPUs may lack constant-time multiplication .
Some VIA Nano x86 and x86_64 CPUs may lack constant-time multiplication
as well.
.Ss Data compression
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
.Dq CRIME .
.Ss Forward secrecy
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
using them.
.Pp
In general, secrets that went through a computer should not be
compromised when this computer is stolen or infected at a later point.
.Pp
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
.Fn crypto_*_final
functions.
The secret keys and messages however are the responsibility of the
user.
Use
.Xr crypto_wipe 3monocypher
to erase them.
.Pp
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 \(en this is often the only
way.
.Pp
UNIX systems can disable swap for specific buffers with
.Fn mlock
and disable swap for the whole process with
.Fn mlockall .
Windows can disable swap for specific buffers with
.Fn VirtualLock .
.Pp
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
.Xr crypto_wipe 3monocypher
is often the only way to mitigate these dangers.
.Ss Undefined behaviour
Monocypher is a C library.
C is notoriously unsafe.
Using Monocypher incorrectly can trigger undefined behaviour.
This can lead to data corruption, data theft, or even arbitrary code
execution.
.Pp
Consider binding to a safe language if possible.
