1INTRO(3MONOCYPHER)                   LOCAL                  INTRO(3MONOCYPHER)
2

NAME

4     intro — introduction to Monocypher
5

DESCRIPTION

7     Monocypher is a cryptographic library.  It provides functions for authen‐
8     ticated encryption, hashing, password hashing and key derivation, key ex‐
9     change, and public key signatures.
10
11   Authenticated encryption
12     crypto_lock(3monocypher) and crypto_unlock(3monocypher) use the Chacha20
13     cipher and the Poly1305 one-time authenticator.
14
15     Chacha20 is a stream cipher based on a cryptographic hash function.  It
16     runs efficiently on a wide variety of hardware, and unlike AES naturally
17     runs in constant time on all hardware.
18
19     Poly1305 is a one-time authenticator, derived from Carter & Wegman uni‐
20     versal hashing.  It is very fast and very simple.
21
22     For specialised needs, crypto_chacha20(3monocypher) and
23     crypto_poly1305(3monocypher) are available to implement constructions in‐
24     volving them.  Whenever possible, crypto_lock(3monocypher) should be pre‐
25     ferred, however.
26
27   Hashing
28     crypto_blake2b(3monocypher) implements the Blake2b hash.  Blake2b com‐
29     bines the security of SHA-3 and the speed of MD5.  It is immune to length
30     extension attacks and provides a keyed mode that makes it a safe, easy to
31     use authenticator.
32
33   Password hashing and key derivation
34     crypto_argon2i(3monocypher) implements the Argon2i resource intensive
35     hash algorithm, which can be used to hash passwords for storage and to
36     derive keys from passwords.  Argon2 won the password hashing competition
37     in 2015.  Unlike Scrypt, Argon2i is immune to timing attacks.
38
39   Key exchange
40     crypto_key_exchange(3monocypher) implements X25519, an elliptic curve
41     Diffie Hellman key exchange algorithm based on Curve25519.  X25519 de‐
42     rives a shared secret from two private/public key pairs.  It is fast,
43     simple, and relatively easy to implement securely.
44
45     For specialised protocols that require indistinguishability from random
46     noise, crypto_curve_to_hidden(3monocypher) gives the option to disguise
47     ephemeral (one-time use) X25519 public keys as random noise.
48
49   Public key signatures
50     crypto_sign(3monocypher) and crypto_check(3monocypher) implement EdDSA,
51     with Curve25519 and Blake2b.  This is the same as the more famous
52     Ed25519, with SHA-512 replaced by the faster and more secure Blake2b.
53
54     For highly specialised needs, it is possible to use a custom hash func‐
55     tion with EdDSA; see
56     crypto_sign_init_first_pass_custom_hash(3monocypher).
57
58   Constant time comparison
59     crypto_verify16(3monocypher), crypto_verify32(3monocypher), and
60     crypto_verify64(3monocypher) compare buffers in constant time.  They
61     should be used to compare secrets to prevent timing attacks.
62
63   Memory wipe
64     crypto_wipe(3monocypher) wipes a buffer.  It is meant to erase secrets
65     when they are no longer needed, to reduce the chances of leaks.
66
67   Optional code
68     If Monocypher was compiled and installed with USE_ED25519, SHA-512 func‐
69     tions become available as well.  See crypto_ed25519_sign(3monocypher),
70     crypto_ed25519_sign_init_first_pass(3monocypher),
71     crypto_sha512(3monocypher), and crypto_hmac_sha512(3monocypher).
72

SEE ALSO

74     crypto_argon2i(3monocypher), crypto_argon2i_general(3monocypher),
75     crypto_blake2b(3monocypher), crypto_blake2b_final(3monocypher),
76     crypto_blake2b_general(3monocypher),
77     crypto_blake2b_general_init(3monocypher),
78     crypto_blake2b_init(3monocypher), crypto_blake2b_update(3monocypher),
79     crypto_chacha20(3monocypher), crypto_chacha20_ctr(3monocypher),
80     crypto_check(3monocypher), crypto_check_final(3monocypher),
81     crypto_check_init(3monocypher),
82     crypto_check_init_custom_hash(3monocypher),
83     crypto_check_update(3monocypher), crypto_curve_to_hidden(3monocypher),
84     crypto_from_eddsa_private(3monocypher),
85     crypto_from_eddsa_public(3monocypher), crypto_hchacha20(3monocypher),
86     crypto_hidden_key_pair(3monocypher), crypto_hidden_to_curve(3monocypher),
87     crypto_ietf_chacha20(3monocypher), crypto_ietf_chacha20_ctr(3monocypher),
88     crypto_key_exchange(3monocypher), crypto_lock(3monocypher),
89     crypto_lock_aead(3monocypher), crypto_poly1305(3monocypher),
90     crypto_poly1305_final(3monocypher), crypto_poly1305_init(3monocypher),
91     crypto_poly1305_update(3monocypher), crypto_sign(3monocypher),
92     crypto_sign_final(3monocypher), crypto_sign_init_first_pass(3monocypher),
93     crypto_sign_init_first_pass_custom_hash(3monocypher),
94     crypto_sign_init_second_pass(3monocypher),
95     crypto_sign_public_key(3monocypher),
96     crypto_sign_public_key_custom_hash(3monocypher),
97     crypto_sign_update(3monocypher), crypto_unlock(3monocypher),
98     crypto_unlock_aead(3monocypher), crypto_verify16(3monocypher),
99     crypto_verify32(3monocypher), crypto_verify64(3monocypher),
100     crypto_wipe(3monocypher), crypto_x25519(3monocypher),
101     crypto_x25519_dirty_fast(3monocypher),
102     crypto_x25519_dirty_small(3monocypher),
103     crypto_x25519_inverse(3monocypher),
104     crypto_x25519_public_key(3monocypher), crypto_xchacha20(3monocypher),
105     crypto_xchacha20_ctr(3monocypher)
106
107   Optional code
108     crypto_from_ed25519_private(3monocypher),
109     crypto_from_ed25519_public(3monocypher),
110     crypto_ed25519_check(3monocypher),
111     crypto_ed25519_check_init(3monocypher),
112     crypto_ed25519_check_update(3monocypher),
113     crypto_ed25519_check_final(3monocypher),
114     crypto_ed25519_public_key(3monocypher), crypto_ed25519_sign(3monocypher),
115     crypto_ed25519_sign_init_first_pass(3monocypher),
116     crypto_ed25519_sign_init_second_pass(3monocypher),
117     crypto_ed25519_sign_final(3monocypher), crypto_hmac_sha512(3monocypher),
118     crypto_hmac_sha512_init(3monocypher),
119     crypto_hmac_sha512_update(3monocypher),
120     crypto_hmac_sha512_final(3monocypher) crypto_sha512(3monocypher),
121     crypto_sha512_init(3monocypher), crypto_sha512_update(3monocypher),
122     crypto_sha512_final(3monocypher)
123

SECURITY CONSIDERATIONS

125     Using cryptography securely is difficult.  Flaws that never manifest un‐
126     der normal use might be exploited by a clever adversary.  Cryptographic
127     libraries are easy to misuse.  Even Monocypher allows a number of fatal
128     mistakes.
129
130     Users should follow a formal introduction to cryptography.  We currently
131     recommend the Crypto 101 online course: https://www.crypto101.io/
132
133   Random number generation
134     Use the facilities of your operating system.  Avoid user space random
135     number generators.  They are easy to misuse, which has lead to countless
136     vulnerabilities in the past.  For instance, the random stream may be re‐
137     peated if one is not careful with multi-threading, and forward secrecy is
138     lost without proper key erasure.
139
140     Different system calls are available on different systems:
141
142     Recent versions of Linux (glibc >= 2.25, Linux >= 3.17), provide
143         getrandom() in <linux/random.h>.  Do not set any flag.
144
145     BSD, Darwin/macOS, illumos as well as Solaris provide
146         arc4random_buf() in <stdlib.h> or <bsd/stdlib.h>.  This is easier to
147         use than getrandom().
148
149     Windows provides BCryptGenRandom().
150
151     The /dev/urandom special file may be used on systems that do not provide
152     an easy to use system call.  Be careful though, being a file makes
153     /dev/urandom hard to use correctly and securely.  Reads may be inter‐
154     rupted, and more attacks are possible on a file than on a system call.
155
156   Timing attacks
157     Monocypher runs in “constant time”.  There is no flow from secrets to
158     timings.  No secret dependent indices, no secret dependent branches.
159     Nevertheless, there are a couple important caveats.
160
161     Comparing secrets should be done with constant-time comparison functions,
162     such as crypto_verify16(3monocypher), crypto_verify32(3monocypher), or
163     crypto_verify64(3monocypher).  Do not use standard comparison functions.
164     They tend to stop as soon as a difference is spotted.  In many cases,
165     this enables attackers to recover the secrets and destroy all security.
166
167     The Poly1305 authenticator, X25519, and EdDSA use multiplication.  Some
168     older processors do not multiply in constant time.  If the target plat‐
169     form is something other than Intel or AMD x86_64, double check how it
170     handles multiplication.  In particular, ARM Cortex-M CPUs may lack
171     constant-time multiplication.  Some VIA Nano x86 and x86_64 CPUs may lack
172     constant-time multiplication as well.
173
174   Data compression
175     Encryption does not hide the length of the input plaintext.  Most com‐
176     pression algorithms work by using fewer bytes to encode previously seen
177     data or common characters.  If an attacker can add data to the input be‐
178     fore it is compressed and encrypted, they can observe changes to the ci‐
179     phertext length to recover secrets from the input.  Researchers have
180     demonstrated an attack on HTTPS to steal session cookies when compression
181     is enabled, dubbed “CRIME”.
182
183   Forward secrecy
184     Long term secrets cannot be expected to stay safe indefinitely.  Users
185     may reveal them by mistake, or the host computer might have a vulnerabil‐
186     ity and be compromised.  To mitigate this problem, some protocols guaran‐
187     tee that past messages are not compromised even if the long term keys
188     are.  This is done by generating temporary keys, then encrypting messages
189     using them.
190
191     In general, secrets that went through a computer should not be compro‐
192     mised when this computer is stolen or infected at a later point.
193
194     A first layer of defence is to explicitly wipe secrets as soon as they
195     are no longer used.  Monocypher already wipes its own temporary buffers,
196     and contexts are erased with the crypto_*_final() functions.  The secret
197     keys and messages however are the responsibility of the user.  Use
198     crypto_wipe(3monocypher) to erase them.
199
200     A second layer of defence is to ensure those secrets are not swapped to
201     disk while they are used.  There are several ways to do this.  The most
202     secure is to disable swapping entirely.  Doing so is recommended on sen‐
203     sitive machines.  Another way is to encrypt the swap partition (this is
204     less safe).  Finally, swap can be disabled locally – this is often the
205     only way.
206
207     UNIX systems can disable swap for specific buffers with mlock(), and dis‐
208     able swap for the whole process with mlockall().  Windows can disable
209     swap for specific buffers with VirtualLock().
210
211     Core dumps cause similar problems.  Disable them.  Also beware of suspend
212     to disk (deep sleep mode), which writes all RAM to disk regardless of
213     swap policy, as well as virtual machine snapshots.  Erasing secrets with
214     crypto_wipe(3monocypher) is often the only way to mitigate these dangers.
215
216   Undefined behaviour
217     Monocypher is a C library.  C is notoriously unsafe.  Using Monocypher
218     incorrectly can trigger undefined behaviour.  This can lead to data cor‐
219     ruption, data theft, or even arbitrary code execution.
220
221     Consider binding to a safe language if possible.
222
223BSD                             March 31, 2020                             BSD
Impressum