From 85a7c3742f06ab55fdf523a7a6a9cfe5cda09837 Mon Sep 17 00:00:00 2001 From: Loup Vaillant Date: Thu, 26 Jan 2023 22:47:48 +0100 Subject: [PATCH] Documentation overhaul The API was broken left and right, and the documentation had to be updated to reflect it. In the process, I decided to go slightly above and beyond. The documentation is rather daunting. One problem I had with it was the sheer number of pages to navigate. On top of that the optional and advanced section didn't help. So I made a number of changes: * I'm sick of having to update symbolic links, so I removed them all. Instead they're generated as part of the documentation generation process. * I collapsed the advanced and optional section into the main folder. Monocypher is a low-level library, so in practice even part of the main API is advanced. Let's stop being shy about it and document everything at the same level. The optional part costs almost nothing on systems that can meaningfully use the makefile. It is now included by default. * I organised all function name around the `crypto_
_*()` naming scheme, and each section gets exactly one man page. This gives us 13 sections, 13 corresponding man pages, plus `intro.3monocypher`. One unfortunate consequence is that some of the man pages grew extra sections for the advanced functions that were bolted on there. I'm not exactly sure how we should tackle them. Still, I think this is a win overall: those fewer man pages are still easier to navigate, and I don't think the advanced stuff really hurt the readability of the man pages they were inserted in. This automation is a first step towards solving #250. The next step should be to automate some cross verification: - Compare the header files and the man pages, spot any missing functions. Maybe also control arguments. - Control that all .Fo and .Fn macros list the same functions. - Control that no cross link (.Xr) is dead. - Control that no function name (.Fn) isn't declared in the header. (except in the HISTORY section). Maybe also do the same for arguments. --- .gitignore | 1 + .../man3 => }/crypto_aead_lock.3monocypher | 15 +- doc/{man/man3 => }/crypto_argon2.3monocypher | 0 doc/{man/man3 => }/crypto_blake2b.3monocypher | 0 ...cypher => crypto_chacha20_djb.3monocypher} | 133 +++++-- .../crypto_ed25519_sign.3monocypher | 56 ++- ...nocypher => crypto_eddsa_sign.3monocypher} | 361 ++++++++++-------- ...ypher => crypto_elligator_map.3monocypher} | 59 +-- .../crypto_hmac_sha512.3monocypher | 0 .../advanced => }/crypto_poly1305.3monocypher | 0 .../optional => }/crypto_sha512.3monocypher | 0 .../man3 => }/crypto_verify16.3monocypher | 0 doc/{man/man3 => }/crypto_wipe.3monocypher | 0 doc/{man/man3 => }/crypto_x25519.3monocypher | 146 ++++++- doc/gen_doc.sh | 87 +++++ doc/{man/man3 => }/intro.3monocypher | 0 .../advanced/crypto_chacha20_h.3monocypher | 132 ------- .../crypto_eddsa_to_x25519.3monocypher | 124 ------ .../crypto_hidden_key_pair.3monocypher | 1 - .../crypto_hidden_to_curve.3monocypher | 1 - .../advanced/crypto_ietf_chacha20.3monocypher | 151 -------- .../crypto_ietf_chacha20_ctr.3monocypher | 1 - .../crypto_poly1305_final.3monocypher | 1 - .../advanced/crypto_poly1305_init.3monocypher | 1 - .../crypto_poly1305_update.3monocypher | 1 - .../crypto_x25519_dirty_fast.3monocypher | 125 ------ .../crypto_x25519_dirty_small.3monocypher | 1 - .../crypto_x25519_inverse.3monocypher | 103 ----- .../crypto_x25519_to_eddsa.3monocypher | 1 - .../advanced/crypto_xchacha20.3monocypher | 1 - doc/man/man3/crypto_aead_init_djb.3monocypher | 1 - .../man3/crypto_aead_init_ietf.3monocypher | 1 - doc/man/man3/crypto_aead_read.3monocypher | 1 - doc/man/man3/crypto_aead_unlock.3monocypher | 1 - doc/man/man3/crypto_aead_write.3monocypher | 1 - doc/man/man3/crypto_blake2b_final.3monocypher | 1 - doc/man/man3/crypto_blake2b_init.3monocypher | 1 - .../man3/crypto_blake2b_update.3monocypher | 1 - doc/man/man3/crypto_check.3monocypher | 1 - .../man3/crypto_sign_public_key.3monocypher | 1 - doc/man/man3/crypto_verify32.3monocypher | 1 - doc/man/man3/crypto_verify64.3monocypher | 1 - .../man3/crypto_x25519_public_key.3monocypher | 1 - .../optional/crypto_ed25519_check.3monocypher | 1 - .../crypto_ed25519_public_key.3monocypher | 1 - .../crypto_hmac_sha512_final.3monocypher | 1 - .../crypto_hmac_sha512_init.3monocypher | 1 - .../crypto_hmac_sha512_update.3monocypher | 1 - .../optional/crypto_sha512_final.3monocypher | 1 - .../optional/crypto_sha512_init.3monocypher | 1 - .../optional/crypto_sha512_update.3monocypher | 1 - doc/man2html.sh | 149 -------- makefile | 19 +- src/monocypher.c | 4 +- src/monocypher.h | 82 ++-- 55 files changed, 640 insertions(+), 1137 deletions(-) rename doc/{man/man3 => }/crypto_aead_lock.3monocypher (98%) rename doc/{man/man3 => }/crypto_argon2.3monocypher (100%) rename doc/{man/man3 => }/crypto_blake2b.3monocypher (100%) rename doc/{man/man3/advanced/crypto_chacha20.3monocypher => crypto_chacha20_djb.3monocypher} (80%) rename doc/{man/man3/optional => }/crypto_ed25519_sign.3monocypher (81%) rename doc/{man/man3/crypto_sign.3monocypher => crypto_eddsa_sign.3monocypher} (54%) rename doc/{man/man3/advanced/crypto_curve_to_hidden.3monocypher => crypto_elligator_map.3monocypher} (91%) rename doc/{man/man3/optional => }/crypto_hmac_sha512.3monocypher (100%) rename doc/{man/man3/advanced => }/crypto_poly1305.3monocypher (100%) rename doc/{man/man3/optional => }/crypto_sha512.3monocypher (100%) rename doc/{man/man3 => }/crypto_verify16.3monocypher (100%) rename doc/{man/man3 => }/crypto_wipe.3monocypher (100%) rename doc/{man/man3 => }/crypto_x25519.3monocypher (64%) create mode 100755 doc/gen_doc.sh rename doc/{man/man3 => }/intro.3monocypher (100%) delete mode 100644 doc/man/man3/advanced/crypto_chacha20_h.3monocypher delete mode 100644 doc/man/man3/advanced/crypto_eddsa_to_x25519.3monocypher delete mode 120000 doc/man/man3/advanced/crypto_hidden_key_pair.3monocypher delete mode 120000 doc/man/man3/advanced/crypto_hidden_to_curve.3monocypher delete mode 100644 doc/man/man3/advanced/crypto_ietf_chacha20.3monocypher delete mode 120000 doc/man/man3/advanced/crypto_ietf_chacha20_ctr.3monocypher delete mode 120000 doc/man/man3/advanced/crypto_poly1305_final.3monocypher delete mode 120000 doc/man/man3/advanced/crypto_poly1305_init.3monocypher delete mode 120000 doc/man/man3/advanced/crypto_poly1305_update.3monocypher delete mode 100644 doc/man/man3/advanced/crypto_x25519_dirty_fast.3monocypher delete mode 120000 doc/man/man3/advanced/crypto_x25519_dirty_small.3monocypher delete mode 100644 doc/man/man3/advanced/crypto_x25519_inverse.3monocypher delete mode 120000 doc/man/man3/advanced/crypto_x25519_to_eddsa.3monocypher delete mode 120000 doc/man/man3/advanced/crypto_xchacha20.3monocypher delete mode 120000 doc/man/man3/crypto_aead_init_djb.3monocypher delete mode 120000 doc/man/man3/crypto_aead_init_ietf.3monocypher delete mode 120000 doc/man/man3/crypto_aead_read.3monocypher delete mode 120000 doc/man/man3/crypto_aead_unlock.3monocypher delete mode 120000 doc/man/man3/crypto_aead_write.3monocypher delete mode 120000 doc/man/man3/crypto_blake2b_final.3monocypher delete mode 120000 doc/man/man3/crypto_blake2b_init.3monocypher delete mode 120000 doc/man/man3/crypto_blake2b_update.3monocypher delete mode 120000 doc/man/man3/crypto_check.3monocypher delete mode 120000 doc/man/man3/crypto_sign_public_key.3monocypher delete mode 120000 doc/man/man3/crypto_verify32.3monocypher delete mode 120000 doc/man/man3/crypto_verify64.3monocypher delete mode 120000 doc/man/man3/crypto_x25519_public_key.3monocypher delete mode 120000 doc/man/man3/optional/crypto_ed25519_check.3monocypher delete mode 120000 doc/man/man3/optional/crypto_ed25519_public_key.3monocypher delete mode 120000 doc/man/man3/optional/crypto_hmac_sha512_final.3monocypher delete mode 120000 doc/man/man3/optional/crypto_hmac_sha512_init.3monocypher delete mode 120000 doc/man/man3/optional/crypto_hmac_sha512_update.3monocypher delete mode 120000 doc/man/man3/optional/crypto_sha512_final.3monocypher delete mode 120000 doc/man/man3/optional/crypto_sha512_init.3monocypher delete mode 120000 doc/man/man3/optional/crypto_sha512_update.3monocypher delete mode 100755 doc/man2html.sh diff --git a/.gitignore b/.gitignore index e3e1130..2a1e6fe 100644 --- a/.gitignore +++ b/.gitignore @@ -25,4 +25,5 @@ tests/formal-analysis monocypher-*/ **/__pycache__/** doc/html/ +doc/man3/ tests/vectors.h diff --git a/doc/man/man3/crypto_aead_lock.3monocypher b/doc/crypto_aead_lock.3monocypher similarity index 98% rename from doc/man/man3/crypto_aead_lock.3monocypher rename to doc/crypto_aead_lock.3monocypher index 95497dc..50feaa4 100644 --- a/doc/man/man3/crypto_aead_lock.3monocypher +++ b/doc/crypto_aead_lock.3monocypher @@ -54,15 +54,18 @@ .Dt CRYPTO_LOCK 3MONOCYPHER .Os .Sh NAME -.Nm crypto_lock_aead , -.Nm crypto_unlock_aead , -.Nm crypto_lock , -.Nm crypto_unlock +.Nm crypto_aead_lock , +.Nm crypto_aead_unlock , +.Nm crypto_aead_init_x , +.Nm crypto_aead_init_djb , +.Nm crypto_aead_init_ietf , +.Nm crypto_aead_write , +.Nm crypto_aead_read .Nd authenticated encryption with additional data .Sh SYNOPSIS .In monocypher.h .Ft void -.Fo crypto_lock +.Fo crypto_aead_lock .Fa "uint8_t *cipher_text" .Fa "uint8_t mac[16]" .Fa "const uint8_t key[32]" @@ -73,7 +76,7 @@ .Fa "size_t text_size" .Fc .Ft int -.Fo crypto_unlock +.Fo crypto_aead_unlock .Fa "uint8_t *plain_text" .Fa "const uint8_t mac[16]" .Fa "const uint8_t key[32]" diff --git a/doc/man/man3/crypto_argon2.3monocypher b/doc/crypto_argon2.3monocypher similarity index 100% rename from doc/man/man3/crypto_argon2.3monocypher rename to doc/crypto_argon2.3monocypher diff --git a/doc/man/man3/crypto_blake2b.3monocypher b/doc/crypto_blake2b.3monocypher similarity index 100% rename from doc/man/man3/crypto_blake2b.3monocypher rename to doc/crypto_blake2b.3monocypher diff --git a/doc/man/man3/advanced/crypto_chacha20.3monocypher b/doc/crypto_chacha20_djb.3monocypher similarity index 80% rename from doc/man/man3/advanced/crypto_chacha20.3monocypher rename to doc/crypto_chacha20_djb.3monocypher index 9dc045b..fe584a5 100644 --- a/doc/man/man3/advanced/crypto_chacha20.3monocypher +++ b/doc/crypto_chacha20_djb.3monocypher @@ -9,7 +9,7 @@ .\" ---------------------------------------------------------------------------- .\" .\" Copyright (c) 2017-2019, 2023 Loup Vaillant -.\" Copyright (c) 2018 Michael Savage +.\" Copyright (c) 2017-2018 Michael Savage .\" Copyright (c) 2017, 2019-2021 Fabio Scotoni .\" All rights reserved. .\" @@ -50,18 +50,19 @@ .\" with this software. If not, see .\" .\" -.Dd January 8, 2023 +.Dd January 26, 2023 .Dt CRYPTO_CHACHA20 3MONOCYPHER .Os .Sh NAME -.Nm crypto_chacha20 , -.Nm crypto_xchacha20 , -.Nm crypto_ietf_chacha20 +.Nm crypto_chacha20_djb , +.Nm crypto_chacha20_ietf , +.Nm crypto_chacha20_x , +.Nm crypto_chacha20_h .Nd ChaCha20 and XChaCha20 encryption functions .Sh SYNOPSIS .In monocypher.h .Ft uint64_t -.Fo crypto_chacha20 +.Fo crypto_chacha20_djb .Fa "uint8_t *cipher_text" .Fa "const uint8_t *plain_text" .Fa "size_t text_size" @@ -70,7 +71,7 @@ .Fa "uint64_t ctr" .Fc .Ft uint32_t -.Fo crypto_ietf_chacha20 +.Fo crypto_chacha20_ietf .Fa "uint8_t *cipher_text" .Fa "const uint8_t *plain_text" .Fa "size_t text_size" @@ -79,7 +80,7 @@ .Fa "uint32_t ctr" .Fc .Ft uint64_t -.Fo crypto_xchacha20 +.Fo crypto_chacha20_x .Fa "uint8_t *cipher_text" .Fa "const uint8_t *plain_text" .Fa "size_t text_size" @@ -87,6 +88,12 @@ .Fa "const uint8_t nonce[24]" .Fa "uint64_t ctr" .Fc +.Ft void +.Fo crypto_chacha20_h +.Fa "uint8_t out[32]" +.Fa "const uint8_t key[32]" +.Fa "const uint8_t in[16]" +.Fc .Sh DESCRIPTION These functions provide an interface for the ChaCha20 encryption primitive. @@ -150,33 +157,33 @@ and must either be the same buffer (for in-place encryption) or non-overlapping. .Pp -.Fn crypto_chacha20 , -.Fn crypto_ietf_chacha20 , +.Fn crypto_chacha20_djb , +.Fn crypto_chacha20_ietf , and -.Fn crypto_xchacha20 +.Fn crypto_chacha20_x perform a ChaCha20 operation. Their main difference is the size of their nonce and counter. -.Fn crypto_ietf_chacha20 +.Fn crypto_chacha20_ietf in particular implements RFC 8439, and is provided strictly for compatibility with existing systems or standards compliance. .Pp -.Fn crypto_xchacha20 +.Fn crypto_chacha20_x Is the only function that uses a nonce long enough to be random. This makes it easier to use securely, and the performance hit of the extended nonce is often negligible in practice. Use it instead of -.Fn crypto_chacha20 +.Fn crypto_chacha20_djb and -.Fn crypto_ietf_chacha20 +.Fn crypto_chacha20_ietf if possible. .Pp The -.Fn crypto_chacha20 , -.Fn crypto_ietf_chacha20 , +.Fn crypto_chacha20_djb , +.Fn crypto_chacha20_ietf , and -.Fn crypto_xchacha20 +.Fn crypto_chacha20_x encrypt .Fa plain_text by XORing it with a pseudo-random stream of @@ -215,10 +222,10 @@ be used to generate large amounts of random-looking data quickly \(en for example to generate padding. .Pp .Sh RETURN VALUES -.Fn crypto_chacha20 , -.Fn crypto_ietf_chacha20 , +.Fn crypto_chacha20_djb , +.Fn crypto_chacha20_ietf , and -.Fn crypto_xchacha20 +.Fn crypto_chacha20_x return the next .Fa ctr to use with the same key and nonce values; @@ -245,7 +252,7 @@ uint8_t plain_text [500] = {1}; /* Secret message */ uint8_t cipher_text[500]; /* Encrypted message */ arc4random_buf(key, 32); arc4random_buf(nonce, 24); -crypto_xchacha20(cipher_text, plain_text, 500, key, nonce, 0); +crypto_chacha20_x(cipher_text, plain_text, 500, key, nonce, 0); /* Wipe secrets if they are no longer needed */ crypto_wipe(key, 32); crypto_wipe(plain_text, 500); @@ -257,7 +264,7 @@ uint8_t key [ 32]; /* Same key as above */ const uint8_t nonce [ 24]; /* Same nonce as above */ uint8_t plain_text [500]; /* Message to decrypt */ uint8_t cipher_text[500]; /* Secret message */ -crypto_xchacha20(cipher_text, plain_text, 500, key, nonce, 0); +crypto_chacha20_x(cipher_text, plain_text, 500, key, nonce, 0); /* Wipe secrets if they are no longer needed */ crypto_wipe(key, 32); /* The plaintext likely needs to be processed before you wipe it */ @@ -275,14 +282,14 @@ unsigned int i; arc4random_buf(key, 32); arc4random_buf(nonce, 24); for(i = 0; i < 500; i += 64) { - ctr = crypto_xchacha20(cipher_text+i, plain_text+i, 64, - key, nonce, ctr); + ctr = crypto_chacha20_x(cipher_text+i, plain_text+i, 64, + key, nonce, ctr); } /* Process data that didn't fit into 64-byte pieces */ -crypto_xchacha20(cipher_text+500-(i-64), - plain_text+500-(i-64), - 500-(i-64), - key, nonce, ctr); +crypto_chacha20_x(cipher_text+500-(i-64), + plain_text+500-(i-64), + 500-(i-64), + key, nonce, ctr); /* Wipe secrets if they are no longer needed */ crypto_wipe(key, 32); crypto_wipe(plain_text, 500); @@ -298,23 +305,60 @@ uint8_t cipher_text[500]; /* Will be the encrypted message */ arc4random_buf(key, 32); arc4random_buf(nonce, 24); /* Encrypt the second part of the message first... */ -crypto_xchacha20(cipher_text + (3 * 64), - plain_text + (3 * 64), - 500 - (3 * 64), - key, nonce, 3); +crypto_chacha20_x(cipher_text + (3 * 64), + plain_text + (3 * 64), + 500 - (3 * 64), + key, nonce, 3); /* ...then encrypt the first part */ -crypto_xchacha20(cipher_text, plain_text, 3 * 64, key, nonce, 0); +crypto_chacha20_x(cipher_text, plain_text, 3 * 64, key, nonce, 0); /* Wipe secrets if they are no longer needed */ crypto_wipe(key, 32); crypto_wipe(plain_text, 500); .Ed +.Sh HCHACHA20 +.Fn crypto_chacha20_h +provides a not-so-cryptographic hash. +.Sy This is not a general-purpose cryptographic hash function . +It may be used for some specific purposes such as X25519 key +derivation or XChaCha20 initialisation. +If in doubt, do not use directly. +Use +.Xr crypto_blake2b 3monocypher +instead. +.Pp +The arguments are: +.Bl -tag -width Ds +.It Fa key +A sufficiently random key, such as the output of +.Xr crypto_x25519 3monocypher . +.It Fa in +The space reserved for the ChaCha20 nonce and counter. +It does not have to be random. +.It Fa out +A cryptographically secure random number +.Em if +there is enough entropy in +.Fa key . +X25519 shared secrets have enough entropy. +.El +.Pp +For instance: +.Bd -literal -offset indent +uint8_t key[32]; /* Must have enough entropy */ +uint8_t in [16]; /* Does not have to be random */ +uint8_t out[32]; /* Will be random iff the above holds */ +arc4random_buf(key, 32); +crypto_chacha20_h(out, key, in); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(key, 32); +crypto_wipe(in , 16); +.Ed .Sh SEE ALSO -.Xr crypto_ietf_chacha20 3monocypher , .Xr crypto_lock 3monocypher , .Xr crypto_wipe 3monocypher , .Xr intro 3monocypher .Sh STANDARDS -These functions implement ChaCha20 and XChaCha20. +These functions implement ChaCha20, XChaCha20, and HChaCha20. ChaCha20 is described in: .Rs .%A Daniel J. Bernstein @@ -345,11 +389,20 @@ and that were deprecated in Monocypher 3.0.0. In Monocypher 4.0.0, only the ctr variants have been kept, and were renamed -.Fn crypto_chacha20 , -.Fn crypto_ietf_chacha20 , +.Fn crypto_chacha20_djb , +.Fn crypto_chacha20_ietf , and -.Fn crypto_xchacha20 +.Fn crypto_chacha20_x respectively. +.Pp +.Fn crypto_chacha20_h +function first appeared in Monocypher 0.1 as +.Fn crypto_chacha20_H . +It was renamed to +.Fn crypto_hchacha20 +in Monocypher 3.0.0, then +.Fn crypto_chacha20_h +in Monocypher 4.0.0. .Sh SECURITY CONSIDERATIONS .Ss Encrypted does not mean secure . ChaCha20 only protects against eavesdropping, not forgeries. @@ -367,7 +420,7 @@ plaintext messages, effectively destroying confidentiality. For the same reason, .Sy do not select small nonces at random . The -.Fn crypto_chacha20 +.Fn crypto_chacha20_djb nonce spans only 64 bits, which is small enough to trigger accidental reuses. A message counter should be used instead. diff --git a/doc/man/man3/optional/crypto_ed25519_sign.3monocypher b/doc/crypto_ed25519_sign.3monocypher similarity index 81% rename from doc/man/man3/optional/crypto_ed25519_sign.3monocypher rename to doc/crypto_ed25519_sign.3monocypher index cae71be..64660e9 100644 --- a/doc/man/man3/optional/crypto_ed25519_sign.3monocypher +++ b/doc/crypto_ed25519_sign.3monocypher @@ -59,15 +59,9 @@ .Sh SYNOPSIS .In monocypher-ed25519.h .Ft void -.Fo crypto_ed25519_public_key -.Fa "uint8_t public_key[32]" -.Fa "const uint8_t secret_key[32]" -.Fc -.Ft void .Fo crypto_ed25519_sign .Fa "uint8_t signature[64]" -.Fa "const uint8_t secret_key[32]" -.Fa "const uint8_t public_key[32]" +.Fa "const uint8_t secret_key[64]" .Fa "const uint8_t *message" .Fa "size_t message_size" .Fc @@ -78,6 +72,24 @@ .Fa "const uint8_t *message" .Fa "size_t message_size" .Fc +.Ft void +.Fo crypto_ed25519_key_pair +.Fa "uint8_t secret_key[64]" +.Fa "uint8_t public_key[32]" +.Fa "uint8_t seed[32]" +.Fc +.Ft void +.Fo crypto_ed25519_ph_sign +.Fa "uint8_t signature[64]" +.Fa "const uint8_t secret_key[32]" +.Fa "const uint8_t message_hash[64]" +.Fc +.Ft int +.Fo crypto_ed25519_ph_check +.Fa "const uint8_t signature[64]" +.Fa "const uint8_t public_key[32]" +.Fa "const uint8_t message_hash[64]" +.Fc .Sh DESCRIPTION The .Fn crypto_ed25519_sign @@ -87,24 +99,34 @@ functions provide Ed25519 public key signatures and verification with SHA-512 as the underlying hash function. They are interoperable with other Ed25519 implementations. If you have no interoperability requirements, prefer -.Xr crypto_sign 3monocypher . +.Xr crypto_eddsa_sign 3monocypher . .Pp The arguments and security considerations are the same as those described in .Xr crypto_sign 3monocypher . .Pp -For an incremental interface, see -.Xr crypto_ed25519_sign_init_first_pass 3monocypher . +.Fn crypto_ed25519_ph_sign +and +.Fn crypto_ed25519_ph_check +implement Ed25519ph. +To sign or check a message, +first hash the message with +.Xr crypto_sha512 3monocypher , +then process the resulting +.Fa message_hash . .Sh RETURN VALUES -.Fn crypto_ed25519_public_key +.Fn crypto_ed25519_public_key , +.Fn crypto_ed25519_sign , and -.Fn crypto_ed25519_sign +.Fn crypto_ed25519_ph_sign return nothing. .Pp .Fn crypto_ed25519_check +and +.Fn crypto_ed25519_ph_check returns 0 for legitimate messages and -1 for forgeries. .Sh SEE ALSO -.Xr crypto_check 3monocypher , +.Xr crypto_eddsa_sign 3monocypher , .Xr crypto_x25519 3monocypher , .Xr crypto_lock 3monocypher , .Xr crypto_sha512 3monocypher , @@ -121,3 +143,11 @@ functions appeared in Monocypher 3.0.0. They replace recompilation of Monocypher with the .Dv ED25519_SHA512 preprocessor definition. +.Pp +In Monocypher 4.0.0, +the incremental and custom hash API removed. +The main interface was also reworked to avoid misuse, +and +.Fn crypto_ed25519_key_pair +replaced +.Fn crypto_ed25519_public_key . diff --git a/doc/man/man3/crypto_sign.3monocypher b/doc/crypto_eddsa_sign.3monocypher similarity index 54% rename from doc/man/man3/crypto_sign.3monocypher rename to doc/crypto_eddsa_sign.3monocypher index 3b11762..470a293 100644 --- a/doc/man/man3/crypto_sign.3monocypher +++ b/doc/crypto_eddsa_sign.3monocypher @@ -8,7 +8,7 @@ .\" .\" ---------------------------------------------------------------------------- .\" -.\" Copyright (c) 2017-2019, 2022 Loup Vaillant +.\" Copyright (c) 2017-2019, 2022-2023 Loup Vaillant .\" Copyright (c) 2017-2018 Michael Savage .\" Copyright (c) 2017, 2019-2022 Fabio Scotoni .\" All rights reserved. @@ -40,7 +40,7 @@ .\" .\" ---------------------------------------------------------------------------- .\" -.\" Written in 2017-2022 by Loup Vaillant, Michael Savage and Fabio Scotoni +.\" Written in 2017-2023 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 @@ -61,48 +61,87 @@ .Sh SYNOPSIS .In monocypher.h .Ft void -.Fo crypto_sign_public_key -.Fa "uint8_t public_key[32]" -.Fa "const uint8_t secret_key[32]" -.Fc -.Ft void -.Fo crypto_sign +.Fo crypto_eddsa_sign .Fa "uint8_t signature[64]" -.Fa "const uint8_t secret_key[32]" -.Fa "const uint8_t public_key[32]" +.Fa "const uint8_t secret_key[64]" .Fa "const uint8_t *message" .Fa "size_t message_size" .Fc .Ft int -.Fo crypto_check +.Fo crypto_eddsa_check .Fa "const uint8_t signature[64]" .Fa "const uint8_t public_key[32]" .Fa "const uint8_t *message" .Fa "size_t message_size" .Fc +.Ft void +.Fo crypto_eddsa_key_pair +.Fa "uint8_t secret_key[64]" +.Fa "uint8_t public_key[32]" +.Fa "uint8_t seed[32]" +.Fc +.Ft void +.Fo crypto_eddsa_to_x25519 +.Fa "uint8_t x25519[32]" +.Fa "const uint8_t eddsa[32]" +.Fc +.Ft void +.Fo crypto_eddsa_trim_scalar +.Fa "uint8_t out[32]" +.Fa "const uint8_t in[32]" +.Fc +.Ft void +.Fo crypto_eddsa_reduce +.Fa "uint8_t reduced[32]" +.Fa "const uint8_t expanded[64]" +.Fc +.Ft void +.Fo crypto_eddsa_mul_add +.Fa "uint8_t r[32]" +.Fa "const uint8_t a[32]" +.Fa "const uint8_t b[32]" +.Fa "const uint8_t c[32]" +.Fc +.Ft void +.Fo crypto_eddsa_scalarbase +.Fa "uint8_t point[32]" +.Fa "const uint8_t scalar[32]" +.Fc +.Ft int +.Fo crypto_eddsa_check_equation +.Fa "const uint8_t Rs[64]" +.Fa "const uint8_t A[32]" +.Fa "const uint8_t h[32]" +.Fc .Sh DESCRIPTION -.Fn crypto_sign +.Fn crypto_eddsa_sign and -.Fn crypto_check +.Fn crypto_eddsa_check provide EdDSA public key signatures and verification. -.Pp +.Fn crypto_sign_key_pair +computes the private and public keys from a random seed. The arguments are: .Bl -tag -width Ds -.It Fa signature -The signature. -.It Fa secret_key -A 32-byte random number known only to you. +.It Fa seed +Random seed, freshly generated and used only once. +It is automatically wiped by +.Fn crypto_sign_key_pair . See .Xr intro 3monocypher about random number generation (use your operating system's random number generator). -Do not use the same private key for both signatures and key exchanges. -The public keys are different and revealing both may leak information. +.It Fa signature +The signature. +.It Fa secret_key +A secret key generated by +.Fn crypto_eddsa_key_pair , +known only to you. +Internally the secret key is made up of the seed and the public key. +They are bundled together to avoid misuse, +and should be treated as a unit. .It Fa public_key -The public key, generated from -.Fa secret_key -with -.Fn crypto_sign_public_key . +The associated public key, +known to everyone. .It Fa message The message to sign. .It Fa message_size @@ -116,23 +155,11 @@ and .Fa message may overlap. .Pp -.Fn crypto_sign_public_key -computes the public key of the specified secret key. -.Pp -.Fn crypto_sign +.Fn crypto_eddsa_sign signs a message with .Fa secret_key . -The public key is optional and will be recomputed if not provided. -This recomputation doubles the execution time. -.Sy Never sign a message with the wrong public key . -Doing so would expose the private key. -Either provide -.Dv NULL -as the -.Fa public_key -or store the private and public keys together as a single unit. .Pp -.Fn crypto_check +.Fn crypto_eddsa_check checks that a given signature is genuine. Meaning, only someone who had the private key could have signed the message. @@ -144,18 +171,16 @@ If the message needs to be secret, use a key exchange protocol involving .Xr crypto_x25519 3monocypher and then -.Xr crypto_lock_aead 3monocypher +.Xr crypto_aead_lock 3monocypher instead. .Pp -An incremental interface is available; see -.Xr crypto_sign_init_first_pass 3monocypher . .Sh RETURN VALUES -.Fn crypto_sign_public_key +.Fn crypto_eddsa_key_pair and -.Fn crypto_sign +.Fn crypto_eddsa_sign return nothing. .Pp -.Fn crypto_check +.Fn crypto_eddsa_check returns 0 for legitimate messages and -1 for forgeries. .Sh EXAMPLES The following examples assume the existence of @@ -167,22 +192,24 @@ does not exist on your system, see .Xr intro 3monocypher for advice about how to generate cryptographically secure random bytes. .Pp -Generate a public key from a random secret key: +Generate a key pair: .Bd -literal -offset indent -uint8_t sk[32]; /* Random secret key */ -uint8_t pk[32]; /* Matching public key */ -arc4random_buf(sk, 32); -crypto_sign_public_key(pk, sk); +uint8_t seed[32]; /* Random seed */ +uint8_t sk [64]; /* secret key */ +uint8_t pk [32]; /* Matching public key */ +arc4random_buf(seed, 32); +crypto_eddsa_key_pair(sk, pk, seed); /* Wipe the secret key if it is no longer needed */ +/* The seed is wiped automatically */ crypto_wipe(sk, 32); .Ed .Pp Sign a message: .Bd -literal -offset indent -uint8_t sk [32]; /* Secret key from above */ +uint8_t sk [64]; /* Secret key from above */ const uint8_t message [11] = "Lorem ipsu"; /* Message to sign */ uint8_t signature[64]; -crypto_sign(signature, sk, NULL, message, 10); +crypto_eddsa_sign(signature, sk, message, 10); /* Wipe the secret key if it is no longer needed */ crypto_wipe(sk, 32); .Ed @@ -192,92 +219,126 @@ Check the above: const uint8_t pk [32]; /* Their public key */ const uint8_t message [11] = "Lorem ipsu"; /* Signed message */ const uint8_t signature[64]; /* Signature to check */ -if (crypto_check(signature, pk, message, 10)) { - /* Message is corrupted, abort processing */ +if (crypto_eddsa_check(signature, pk, message, 10)) { + /* Message is corrupted, do not trust it */ } else { - /* Message is genuine */ + /* Message is genuine */ } .Ed +.Sh CONVERSIONS to X25519 +.Fn crypto_eddsa_to_x25519 +Converts and EdDSA public key to an X25519 public key. +Note that it ignores the sign of the +.Em x +coordinate of the EdDSA input. +The inverse operation is provided by +.Xr crypto_x25519_to_eddsa 3monocypher . +.Sh LOW LEVEL BUILDING BLOCKS +.Fn crypto_eddsa_trim_scalar , +.Fn crypto_eddsa_reduce , +.Fn crypto_eddsa_mul_add , +.Fn crypto_eddsa_scalarbase , +and +.Fn crypto_eddsa_check_equation +provide low-level functionality to implement specialised APIs and +variants of EdDSA. +Monocypher uses them to implement all high-level EdDSA and Ed25519 +functions. .Pp -To avoid recomputing the public key with each signature, -store it next to the private key -.Pq Dq composite private key . -Make sure you treat that key pair as a single unit: -.Bd -literal -offset indent -uint8_t sk[64]; /* Combined secret key */ -uint8_t pk[32]; /* Public key */ -arc4random_buf(sk, 32); /* Secret half */ -crypto_sign_public_key(sk + 32, sk); /* Public half */ -memcpy(pk, sk + 32, 32); /* Copy public key */ -/* Wipe the secret key if it is no longer needed */ -crypto_wipe(sk, 64); -.Ed +These functions are +.Sy dangerous , +using them directly allows many kinds of catastrophic misuse. +The following descriptions are kept concise and technical on purpose. +If you do not understand them, do not not use those functions. .Pp -That way signing can use the composite private key alone: -.Bd -literal -offset indent -uint8_t sk [64]; /* Combined secret key from above */ -const uint8_t message [11] = "Lorem ipsu"; /* Message to sign */ -uint8_t signature[64]; -crypto_sign(signature, sk, sk + 32, message, 10); -/* Wipe the secret key if it is no longer needed */ -crypto_wipe(sk, 64); -.Ed +.Fn crypto_eddsa_trim_scalar +reads a 256-bit number represented in Little Endian, +and outputs the same number modified as follows: +the 3 least significant bits are cleared; +the most significant bit is cleared; +and the second most significant bit is set. .Pp -It is also possible to implement a safer API that provides a combined -key abstraction: -.Bd -literal -offset indent -void eddsa_sign_key_pair(uint8_t secret_key[64], - uint8_t public_key[32], - uint8_t seed[32]) -{ - /* Copy seed to secret key then wipes the seed. */ - /* Accounts for buffer overlaps. */ - uint8_t sk[32]; - memcpy(sk , seed, 32); crypto_wipe(seed, 32); - memcpy(secret_key, sk , 32); crypto_wipe(sk , 32); - - crypto_sign_public_key(secret_key + 32, secret_key); - memmove(public_key, secret_key + 32, 32); -} - -void eddsa_sign(uint8_t signature [64], - const uint8_t secret_key[64], - const uint8_t *message, size_t message_size) -{ - crypto_sign(signature, secret_key, secret_key + 32, - message, message_size); -} -.Ed +.Fn crypto_eddsa_reduce +reads a 512-bit number represented in Little Endian, +and outputs the same number reduced modulo the prime order of +Curve25519. .Pp -With this API we can generate a key pair from a seed: -.Bd -literal -offset indent -uint8_t seed[32]; /* Random seed */ -uint8_t sk [64]; /* Combined secret key */ -uint8_t pk [32]; /* Public key */ -arc4random_buf(seed, 32); -eddsa_sign_key_pair(sk, pk, seed); -/* Wipe the secret key if it is no longer needed */ -crypto_wipe(sk, 64); -.Ed +.Fn crypto_eddsa_mul_add +reads three 256-bit numbers represented in Little Endian, +and outputs +.Fa a +× +.Fa b ++ +.Fa c , +reduced modulo the prime order of Curve25519. .Pp -Then we can sign with the composite private key: -.Bd -literal -offset indent -uint8_t sk [64]; /* Combined secret key from above */ -const uint8_t message [11] = "Lorem ipsu"; /* Message to sign */ -uint8_t signature[64]; -eddsa_sign(signature, sk, message, 10); -/* Wipe the secret key if it is no longer needed */ -crypto_wipe(sk, 64); -.Ed +.Fn crypto_eddsa_scalarbase +reads a 256-bit number represented in Little Endian, +and outputs the result of the scalar multiplication between that number +and the twisted Edwards base point of Curve25519. +The output uses the same compressed representation as regular EdDSA +public keys: +the most significant bit represents the sign of the +.Em x +coordinate (1 if it is odd, 0 if it is even), +and the 255 other bits represent the +.Em y +coordinate in Little Endian. +.Pp +.Fn crypto_eddsa_check_equation +reads a signature +.Fa Rs , +a public_key +.Fa A , +and hash +.Fa h, +then checks the following: +.Bl -dash +.It +.Fa A +and +.Fa R +are both on the curve. +.It +.Fa s +is below the prime order of Curve25519. +.It +[8×s]B = [8]R + [8×h]A +.El +.Pp +It then returns 0 if all checks hold, +-1 otherwise. +Note that +.Fa A +and +.Fa R +are allowed to have low order, +and their encoding is allowed to be non-canonical. +.Sy This function does not run in constant time , +do not use it with secret inputs. .Sh SEE ALSO .Xr crypto_blake2b 3monocypher , .Xr crypto_x25519 3monocypher , -.Xr crypto_lock 3monocypher , +.Xr crypto_aead_lock 3monocypher , .Xr intro 3monocypher .Sh STANDARDS -These functions implement PureEdDSA with Curve25519 and BLAKE2b, as -described in RFC 8032. +.Fn crypto_eddsa_sign , +.Fn crypto_eddsa_check , +and +.Fn crypto_eddsa_key_pair +implement PureEdDSA with Curve25519 and BLAKE2b, +as described in RFC 8032. This is the same as Ed25519, with BLAKE2b instead of SHA-512. +.Pp +.Fn crypto_eddsa_trim_scalar , +.Fn crypto_eddsa_reduce , +.Fn crypto_eddsa_mul_add , +.Fn crypto_eddsa_scalarbase , +and +.Fn crypto_eddsa_check_equation +can be used to implement any Curve25519 based EdDSA variant, +including Ed25519 and Ed25519ph. .Sh HISTORY The .Fn crypto_sign , @@ -296,44 +357,33 @@ in prior versions, such signatures would be accepted. that caused all-zero signatures to be accepted was introduced in Monocypher 0.3; it was fixed in Monocypher 1.1.1 and 2.0.4. -.Sh SECURITY CONSIDERATIONS -.Ss Using the wrong public key exposes the private key -Performing two signatures on the same message -with the same private key -but with two different public keys -instantly exposes the private key. .Pp -There are two ways to avoid this error. -The easiest is to call -.Fn crypto_sign -with a -.Dv NULL -public key so it regenerates the correct one from the private key. -This method is slower, -but in practice is often fast enough. -.Pp -The fastest is to treat the private and public key as a single unit: -once generated, they must be stored together and treated -as one composite private key. -When calling -.Fn crypto_sign , -provide the public half of the composite private key. -The public half can be copied and and published separately, -but the copy itself must never be used for signatures. +In Monocypher 4.0.0 +.Fn crypto_eddsa_trim_scalar , +.Fn crypto_eddsa_reduce , +.Fn crypto_eddsa_mul_add , +.Fn crypto_eddsa_scalarbase , +and +.Fn crypto_eddsa_check_equation +were added, +and the incremental and custom hash API removed. +The main interface was also reworked to avoid misuse, +and +.Fn crypto_eddsa_key_pair +replaced +.Fn crypto_sign_public_key . +.Sh SECURITY CONSIDERATIONS .Ss Signature malleability Signature malleability is the ability of an attacker to produce a valid signature with knowledge of only an existing signature and the public key. -That is, given a message, a signature and a public key, -an attacker could generate a new signature for the same message that -is valid under the same public key. -Monocypher prevents signature malleability by only accepting -signatures in canonical form. +Monocypher prevents that by checking the encoding of the signature, +and guarantees that generating new signatures requires the private key. .Pp On the other hand, EdDSA signatures are not unique like cryptographic hashes. The signing procedure is deterministic by specification and -.Fn crypto_sign +.Fn crypto_eddsa_sign follows this specification. However, someone with the private key can generate arbitrarily many valid, canonical, and different signatures of the same message. @@ -343,10 +393,9 @@ Fault injection (also known as glitching) and power analysis may be used to manipulate the resulting signature and recover the secret key in some cases. This requires hardware access. -If attackers are expected to have such access and have the relevant -equipment, you could try using the incremental interface provided by -.Xr crypto_sign_init_first_pass 3monocypher -to mitigate the side-channel attacks. +We can try to mitigate this attack by prefixing all hashes a random data +block, +in a construction similar to Ed25519ctx. Note that there may still be other power-related side channels (such as if the CPU leaks information when an operation overflows a register) that must be considered. diff --git a/doc/man/man3/advanced/crypto_curve_to_hidden.3monocypher b/doc/crypto_elligator_map.3monocypher similarity index 91% rename from doc/man/man3/advanced/crypto_curve_to_hidden.3monocypher rename to doc/crypto_elligator_map.3monocypher index 4c91b68..ee37fd9 100644 --- a/doc/man/man3/advanced/crypto_curve_to_hidden.3monocypher +++ b/doc/crypto_elligator_map.3monocypher @@ -48,29 +48,29 @@ .\" with this software. If not, see .\" .\" -.Dd February 13, 2022 -.Dt CRYPTO_CURVE_TO_HIDDEN 3MONOCYPHER +.Dd January 26, 2023 +.Dt CRYPTO_ELLIGATOR_MAP 3MONOCYPHER .Os .Sh NAME -.Nm crypto_curve_to_hidden , -.Nm crypto_hidden_to_curve , -.Nm crypto_hidden_key_pair +.Nm crypto_elligator_map , +.Nm crypto_elligator_rev , +.Nm crypto_elligator_key_pair .Nd hiding of X25519 public keys .Sh SYNOPSIS .In monocypher.h +.Ft void +.Fo crypto_elligator_map +.Fa "uint8_t curve[32]" +.Fa "const uint8_t hidden[32]" +.Fc .Ft int -.Fo crypto_curve_to_hidden +.Fo crypto_elligator_rev .Fa "uint8_t hidden[32]" .Fa "const uint8_t curve[32]" .Fa "uint8_t tweak" .Fc .Ft void -.Fo crypto_hidden_to_curve -.Fa "uint8_t curve[32]" -.Fa "const uint8_t hidden[32]" -.Fc -.Ft void -.Fo crypto_hidden_key_pair +.Fo crypto_elligator_key_pair .Fa "uint8_t hidden[32]" .Fa "uint8_t secret_key[32]" .Fa "uint8_t seed[32]" @@ -106,7 +106,7 @@ This also means that these functions are not compatible with .Xr crypto_sign 3monocypher and related functions. .Pp -.Fn crypto_curve_to_hidden +.Fn crypto_elligator_rev takes a public key .Fa curve and a @@ -129,35 +129,35 @@ Even then, this operation fail because not all curve points are capable of being hidden. In this case, -.Fn crypto_curve_to_hidden +.Fn crypto_elligator_rev must be tried again with a new key pair, though .Fa tweak does not need to be changed. On average, two attempts are needed. Once a suitable public key has been found, -.Fn crypto_curve_to_hidden +.Fn crypto_elligator_rev always succeeds for it. Given the same values for .Fa tweak and .Fa curve , -.Fn crypto_curve_to_hidden +.Fn crypto_elligator_rev yields the same output value .Fa hidden . .Pp -.Fn crypto_hidden_to_curve +.Fn crypto_elligator_map performs the inverse operation: It decodes a hidden point to a curve point on Curve25519. .Pp -.Fn crypto_hidden_key_pair +.Fn crypto_elligator_key_pair is a convenience function that generates a secret key and its corresponding public key, which is effectively indistinguishable from random noise, from a random seed. .Em The execution time of this function is unpredictable because it may take many failures until a key pair could be generated successfully. -.Fn crypto_hidden_key_pair +.Fn crypto_elligator_key_pair uses .Xr crypto_x25519_dirty_fast 3monocypher internally; @@ -192,7 +192,7 @@ is wiped automatically. .It Fa tweak A 1-byte random number, which influences the final output of -.Fn crypto_curve_to_hidden . +.Fn crypto_elligator_rev . .El .Pp The @@ -201,14 +201,14 @@ and .Fa curve arguments may overlap or point at the same buffer. .Sh RETURN VALUES -.Fn crypto_curve_to_hidden +.Fn crypto_elligator_rev returns 0 on success and -1 if the given .Fa curve argument is unsuitable for hiding. .Pp -.Fn crypto_hidden_to_curve +.Fn crypto_elligator_map and -.Fn crypto_hidden_key_pair +.Fn crypto_elligator_key_pair return nothing. They cannot fail. .Sh EXAMPLES @@ -223,7 +223,7 @@ arc4random_buf(&tweak, 1); for (;;) { arc4random_buf(sk, 32); crypto_x25519_dirty_small(pk, sk); - if (crypto_curve_to_hidden(pk, pk, tweak) == 0) + if (crypto_elligator_rev(pk, pk, tweak) == 0) break; } /* Now save the secret key and send the hidden public key. */ @@ -236,7 +236,7 @@ uint8_t hidden_pk [32]; /* Their hidden public key */ uint8_t their_pk [32]; /* Their unhidden public key */ uint8_t your_sk [32]; /* Your secret key */ uint8_t shared_key[32]; /* Shared session key */ -crypto_hidden_to_curve(their_pk, hidden_pk); +crypto_elligator_map(their_pk, hidden_pk); crypto_x25519(shared_key, your_sk, their_pk); /* Wipe secrets if they are no longer needed */ crypto_wipe(your_sk, 32); @@ -268,9 +268,16 @@ The and .Fn crypto_hidden_key_pair functions first appeared in Monocypher 3.1.0. +In Monocypher 4.1.0, +they were renamed +.Fn crypto_elligator_rev , +.Fn crypto_elligator_map , +and +.Fn crypto_elligator_key_pair +respectively. .Sh SECURITY CONSIDERATIONS The secret keys for the public keys fed into -.Fn crypto_curve_to_hidden +.Fn crypto_elligator_rev .Sy must be chosen randomly rather than deterministically. Otherwise, the timing information given by the required number of diff --git a/doc/man/man3/optional/crypto_hmac_sha512.3monocypher b/doc/crypto_hmac_sha512.3monocypher similarity index 100% rename from doc/man/man3/optional/crypto_hmac_sha512.3monocypher rename to doc/crypto_hmac_sha512.3monocypher diff --git a/doc/man/man3/advanced/crypto_poly1305.3monocypher b/doc/crypto_poly1305.3monocypher similarity index 100% rename from doc/man/man3/advanced/crypto_poly1305.3monocypher rename to doc/crypto_poly1305.3monocypher diff --git a/doc/man/man3/optional/crypto_sha512.3monocypher b/doc/crypto_sha512.3monocypher similarity index 100% rename from doc/man/man3/optional/crypto_sha512.3monocypher rename to doc/crypto_sha512.3monocypher diff --git a/doc/man/man3/crypto_verify16.3monocypher b/doc/crypto_verify16.3monocypher similarity index 100% rename from doc/man/man3/crypto_verify16.3monocypher rename to doc/crypto_verify16.3monocypher diff --git a/doc/man/man3/crypto_wipe.3monocypher b/doc/crypto_wipe.3monocypher similarity index 100% rename from doc/man/man3/crypto_wipe.3monocypher rename to doc/crypto_wipe.3monocypher diff --git a/doc/man/man3/crypto_x25519.3monocypher b/doc/crypto_x25519.3monocypher similarity index 64% rename from doc/man/man3/crypto_x25519.3monocypher rename to doc/crypto_x25519.3monocypher index cadbe40..0fec5a7 100644 --- a/doc/man/man3/crypto_x25519.3monocypher +++ b/doc/crypto_x25519.3monocypher @@ -8,7 +8,7 @@ .\" .\" ---------------------------------------------------------------------------- .\" -.\" Copyright (c) 2017-2021, 2022 Loup Vaillant +.\" Copyright (c) 2017-2021, 2022-2023 Loup Vaillant .\" Copyright (c) 2017-2018 Michael Savage .\" Copyright (c) 2017, 2019-2020, 2022 Fabio Scotoni .\" Copyright (c) 2020 Richard Walmsley @@ -42,7 +42,7 @@ .\" .\" ---------------------------------------------------------------------------- .\" -.\" Written in 2017-2022 by Loup Vaillant, Michael Savage, Fabio Scotoni, +.\" Written in 2017-2023 by Loup Vaillant, Michael Savage, Fabio Scotoni, .\" Richard Walmsley and Samuel Lucas .\" .\" To the extent possible under law, the author(s) have dedicated all copyright @@ -53,12 +53,16 @@ .\" with this software. If not, see .\" .\" -.Dd February 23, 2022 +.Dd January 26, 2023 .Dt CRYPTO_X25519 3MONOCYPHER .Os .Sh NAME .Nm crypto_x25519 , -.Nm crypto_x25519_public_key +.Nm crypto_x25519_public_key , +.Nm crypto_x25519_dirty_fast , +.Nm crypto_x25519_dirty_small , +.Nm crypto_x25519_inverse , +.Nm crypto_x25519_to_eddsa .Nd X25519 key exchange (Public Key Cryptography) .Sh SYNOPSIS .In monocypher.h @@ -73,21 +77,36 @@ .Fa "uint8_t your_public_key[32]" .Fa "const uint8_t your_secret_key[32]" .Fc +.Ft void +.Fo crypto_x25519_dirty_fast +.Fa "uint8_t your_public_key[32]" +.Fa "const uint8_t your_secret_key[32]" +.Fc +.Ft void +.Fo crypto_x25519_dirty_small +.Fa "uint8_t your_public_key[32]" +.Fa "const uint8_t your_secret_key[32]" +.Fc +.Ft void +.Fo crypto_x25519_inverse +.Fa "uint8_t blind_salt[32]" +.Fa "const uint8_t private_key[32]" +.Fa "const uint8_t curve_point[32]" +.Fc +.Ft void +.Fo crypto_x25519_to_eddsa +.Fa "uint8_t eddsa[32]" +.Fa "const uint8_t x25519[32]" +.Fc .Sh DESCRIPTION .Fn crypto_x25519 -computes a shared secret with +performs an X25519 key exchange between .Fa your_secret_key and .Fa their_public_key . -It is a low-level primitive; -X25519 is a building block for protocols. -To perform a key exchange, -use a higher level protocol, -such as the X3DH key agreement protocol. -.Pp +It is a low-level building block for protocols such as X3DH. .Fn crypto_x25519_public_key -deterministically computes the public key from a random secret key. -.Pp +Generates a public key from a secret key. The arguments are: .Bl -tag -width Ds .It Fa raw_shared_secret @@ -108,14 +127,17 @@ See .Xr intro 3monocypher for advice about generating random bytes (use the operating system's random number generator). +.It Fa your_public_key +Your public key, generated by +.Fn crypto_x25519_public_key . .It Fa their_public_key The public key of the other party. +.El .Pp .Fa raw_shared_secret and .Fa your_secret_key may overlap if your secret is no longer required. -.El .Pp Some protocols, such as some password-authenticated key exchange (PAKE) protocols @@ -134,11 +156,15 @@ then abort the protocol if the output and the all-zero buffer are equal. Do not use the same secret key for both key exchanges and signatures. The public keys are different and revealing both may leak information. If there really is no room to store or derive two different secret keys, -consider generating a key pair for signatures and then converting it -with -.Xr crypto_from_eddsa_private 3monocypher -and -.Xr crypto_from_eddsa_public 3monocypher . +consider generating a key pair for signatures and then converting the +private half with +.Xr crypto_blake2b 3monocypher +or +.Xr crypto_sha512 3monocypher , +and the public half with +.Xr crypto_eddsa_to_x25519 3monocypher . +Or go the other way and implement XEdDSA with the help of +.Fn crypto_x25519_to_eddsa . .Sh RETURN VALUES .Fn crypto_x25519 and @@ -180,6 +206,81 @@ const uint8_t *key_2 = shared_keys + 32; /* Shared key 2 */ /* Wipe secrets if they are no longer needed */ crypto_wipe(shared_secret, 32); .Ed +.Sh INVERSE SCALAR MULTIPLICATION +The +.Fn crypto_x25519_inverse +function performs the scalar multiplication of the multiplicative +inverse of a scalar for X25519. +It is basically the reverse of +.Fn crypto_x25519 : +.Bd -literal -offset indent +uint8_t b [32]; /* Random scalar */ +uint8_t base [32]; /* Point on the prime order subgroup */ +crypto_x25519_public_key(base, b); + +uint8_t private_key[32]; /* Random secret key */ +uint8_t curve_point[32]; /* Point on the prime order subgroup */ +uint8_t blind_salt [32]; +crypto_x25519(curve_point, private_key, base); +crypto_x25519_inverse(blind_salt, private_key, curve_point); +assert(memcmp(blind_salt, base, 32) == 0); /* blind_salt == base */ +.Ed +.Pp +We can think of it as a scalar division that also clears the cofactor. +The arguments are: +.Bl -tag -width Ds +.It Fa blind_salt +The output point. +Guaranteed to be on the prime order subgroup. +The only possible low order result is a buffer full of zeroes. +.It Fa private_key +The private key (scalar) to use. +It is clamped, +inverted modulo the prime order of Curve25519, +cleared of its cofactor, +and finally used to multiply +.Fa curve_point . +.It Fa curve_point +The curve point to divide by +.Fa private_key . +.El +.Sh DIRTY PUBLIC KEY GENERATION +.Fn crypto_x25519_dirty_fast +and +.Fn crypto_x25519_dirty_small +do the same as +.Fn crypto_x25519_public_key , +with one key difference: +they also add a low order point to the public key. +Such public keys can be on the +.Em whole +curve, rather than just the main prime-order subgroup. +Yet they are fully compatible with +.Fn crypto_x25519 , +and will generate the same shared secrets as regular public keys. +.Em They do however leak information about the private key . +Only use them for ephemeral keys that need to be hidden as random noise, +in conjunction with +.Xr crypto_elligator_rev 3monocypher . +.Pp +Both functions do the same with different code size and memory +characteristics: +.Fn crypto_x25519_dirty_fast +uses multiple large temporary variables and functions that are +normally used internally for +.Xr crypto_sign 3monocypher . +Accordingly, it uses both more stack memory and more code +(unless the signing code is already compiled in elsewhere). +.Fn crypto_x25519_dirty_small +yields the same result with less code, less memory, +and about twice as much time as +.Fn crypto_x25519_dirty_fast . +.Sh CONVERSION TO EDDSA +The +.Fn crypto_x25519_to_eddsa +converts an X25519 public key to the corresponding EdDSA public key. +The sign bit of the resulting EdDSa key is set to zero (positive). +This can be used to implement the XEdDSA protocol from Signal. .Sh SEE ALSO .Xr intro 3monocypher .Sh STANDARDS @@ -190,6 +291,13 @@ The and .Fn crypto_x25519_public_key functions first appeared in Monocypher 0.1. +The +.Fn crypto_x25519_inverse , +.Fn crypto_x25519_dirty_fast , +.Fn crypto_x25519_dirty_small , +and +.Fn crypto_x25519_to_eddsa +functions first appeared in Monocypher 3.1.0. .Sh SECURITY CONSIDERATIONS If either of the long-term secret keys leaks, it may compromise .Em all past messages . diff --git a/doc/gen_doc.sh b/doc/gen_doc.sh new file mode 100755 index 0000000..183a377 --- /dev/null +++ b/doc/gen_doc.sh @@ -0,0 +1,87 @@ +#! /bin/sh + +# This file is dual-licensed. Choose whichever licence you want from +# the two licences listed below. +# +# 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, 2023, Loup Vaillant +# Copyright (c) 2017, 2019, 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, 2019 and 2023 by Loup Vaillant 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 +# + +set -e + +cd $(dirname "$0") + +# clean before +rm -rf "html" +rm -rf "man3" +find . -type l | xargs rm -f + +mkdir -p man3 +mkdir -p html +cp style.css html/ + +for source in $(find . -name "*.3monocypher" | sed 's|^\./||' | sort) +do + name=$(echo "$source" | sed 's/.3monocypher//') + + # Copy source file to the final man page directory + cp "$source" "man3/$source" + + # Generate HTML version, + mandoc \ + -Oman=%N.html,style=style.css \ + -Thtml "$source" \ + > "./html/$name.html" + + # Add all symbolic links + for link in $(grep "^\.Fo " "$source" | tail -n+2 | sed 's/^\.Fo //') + do + ln -s "$source" "man3/$link.3monocypher" + ln -s "$name.html" "html/$link.html" + done +done diff --git a/doc/man/man3/intro.3monocypher b/doc/intro.3monocypher similarity index 100% rename from doc/man/man3/intro.3monocypher rename to doc/intro.3monocypher diff --git a/doc/man/man3/advanced/crypto_chacha20_h.3monocypher b/doc/man/man3/advanced/crypto_chacha20_h.3monocypher deleted file mode 100644 index b4a3543..0000000 --- a/doc/man/man3/advanced/crypto_chacha20_h.3monocypher +++ /dev/null @@ -1,132 +0,0 @@ -.\" 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-2019, 2023 Loup Vaillant -.\" Copyright (c) 2017-2018 Michael Savage -.\" Copyright (c) 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-2023 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 -.\" -.\" -.Dd January 9, 2023 -.Dt CRYPTO_CHACHA20_H 3MONOCYPHER -.Os -.Sh NAME -.Nm crypto_chacha20_h -.Nd HChaCha20 special-purpose hashing -.Sh SYNOPSIS -.In monocypher.h -.Ft void -.Fo crypto_chacha20_h -.Fa "uint8_t out[32]" -.Fa "const uint8_t key[32]" -.Fa "const uint8_t in[16]" -.Fc -.Sh DESCRIPTION -.Fn crypto_chacha20_h -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. -Use -.Xr crypto_blake2b 3monocypher -instead. -.Pp -The arguments are: -.Bl -tag -width Ds -.It Fa key -A sufficiently random key, such as the output of -.Xr crypto_x25519 3monocypher . -.It Fa in -The space reserved for the ChaCha20 nonce and counter. -It does not have to be random. -.It Fa out -A cryptographically secure random number -.Em if -there is enough entropy in -.Fa key . -X25519 shared secrets have enough entropy. -.El -.Sh RETURN VALUES -This function returns nothing. -.Sh EXAMPLES -The following example assumes the existence of -.Fn arc4random_buf , -which fills the given buffer with cryptographically secure random bytes. -If -.Fn arc4random_buf -does not exist on your system, see -.Xr intro 3monocypher -for advice about how to generate cryptographically secure random bytes. -.Pp -Simple hash: -.Bd -literal -offset indent -uint8_t key[32]; /* Must have enough entropy */ -uint8_t in [16]; /* Does not have to be random */ -uint8_t out[32]; /* Will be random iff the above holds */ -arc4random_buf(key, 32); -crypto_chacha20_h(out, key, in); -/* Wipe secrets if they are no longer needed */ -crypto_wipe(key, 32); -crypto_wipe(in , 16); -.Ed -.Sh SEE ALSO -.Xr intro 3monocypher -.Sh STANDARDS -This function implements HChaCha20. -HChaCha20 derives from ChaCha20 the same way HSalsa20 derives from -Salsa20. -.Sh HISTORY -The -.Fn crypto_chacha20_h -function first appeared in Monocypher 0.1 as -.Fn crypto_chacha20_H . -It was renamed to -.Fn crypto_hchacha20 -in Monocypher 3.0.0, then -.Fn crypto_chacha20_h -in Monocypher 4.0.0. -.Sh CAVEATS -.Sy This is not a general-purpose cryptographic hash function . diff --git a/doc/man/man3/advanced/crypto_eddsa_to_x25519.3monocypher b/doc/man/man3/advanced/crypto_eddsa_to_x25519.3monocypher deleted file mode 100644 index 1f1e509..0000000 --- a/doc/man/man3/advanced/crypto_eddsa_to_x25519.3monocypher +++ /dev/null @@ -1,124 +0,0 @@ -.\" 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) 2020, 2022 Fabio Scotoni -.\" Copyright (c) 2023 Loup Vaillant -.\" 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 2020, 2022, and 2023 by Fabio Scotoni and Loup Vaillant -.\" -.\" 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 -.\" -.\" -.Dd January 7, 2023 -.Dt CRYPTO_FROM_EDDSA_TO_X25519 3MONOCYPHER -.Os -.Sh NAME -.Nm crypto_eddsa_to_x25519 , -.Nm crypto_x25519_to_eddsa -.Nd conversion of public keys between EdDSA and X25519 -.Sh SYNOPSIS -.In monocypher.h -.Ft void -.Fo crypto_eddsa_to_x25519 -.Fa "uint8_t x25519[32]" -.Fa "const uint8_t eddsa[32]" -.Fc -.Ft void -.Fo crypto_x25519_to_eddsa -.Fa "uint8_t eddsa[32]" -.Fa "const uint8_t x25519[32]" -.Fc -.Sh DESCRIPTION -These functions convert between public keys for use with -.Xr crypto_eddsa_sign 3monocypher -and keys for use with -.Xr crypto_x25519 3monocypher . -This may be useful in some resource-constrained contexts or when no -other key is available \(en for example when retrieving SSH public keys -from GitHub and reusing the SSH public keys as X25519 public keys. -.Pp -The -.Fn crypto_eddsa_to_x25519 -function converts an EdDSA public key to an X25519 public key. -The -.Fn crypto_x25519_to_eddsa -function converts an X25519 public key to an EdDSA public key. -.Pp -The arguments are: -.Bl -tag -width Ds -.It Fa eddsa -The EdDSA signing public key. -.It Fa x25519 -The X25519 key exchange public key. -.El -.Pp -The arguments may overlap or point at the same buffer. -.Sh RETURN VALUES -These functions return nothing. -They cannot fail. -.Sh SEE ALSO -.Xr crypto_x25519 3monocypher , -.Xr crypto_eddsa_key_pair 3monocypher , -.Xr intro 3monocypher -.Sh HISTORY -The -.Fn crypto_from_eddsa_private -and -.Fn crypto_from_eddsa_public -functions first appeared in Monocypher 3.1.0. -In Monocypher 4.0.0, -.Fn crypto_from_eddsa_private -was removed, -.Fn crypto_x25519_to_eddsa -was added, -and -.Fn crypto_from_eddsa_public -was renamed -.Fn crypto_eddsa_to_x25519 . -.Sh SECURITY CONSIDERATIONS -It is generally considered poor form to reuse the same key for different -purposes. -While this conversion is technically safe, -avoid these functions nonetheless unless you are particularly -resource-constrained or have some other kind of hard requirement. -It is otherwise an unnecessary risk factor. diff --git a/doc/man/man3/advanced/crypto_hidden_key_pair.3monocypher b/doc/man/man3/advanced/crypto_hidden_key_pair.3monocypher deleted file mode 120000 index 3717a86..0000000 --- a/doc/man/man3/advanced/crypto_hidden_key_pair.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_curve_to_hidden.3monocypher \ No newline at end of file diff --git a/doc/man/man3/advanced/crypto_hidden_to_curve.3monocypher b/doc/man/man3/advanced/crypto_hidden_to_curve.3monocypher deleted file mode 120000 index 3717a86..0000000 --- a/doc/man/man3/advanced/crypto_hidden_to_curve.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_curve_to_hidden.3monocypher \ No newline at end of file diff --git a/doc/man/man3/advanced/crypto_ietf_chacha20.3monocypher b/doc/man/man3/advanced/crypto_ietf_chacha20.3monocypher deleted file mode 100644 index 16473d4..0000000 --- a/doc/man/man3/advanced/crypto_ietf_chacha20.3monocypher +++ /dev/null @@ -1,151 +0,0 @@ -.\" 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) 2019-2021 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 2019-2021 by 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 -.\" -.\" -.Dd June 11, 2021 -.Dt CRYPTO_IETF_CHACHA20 3MONOCYPHER -.Os -.Sh NAME -.Nm crypto_ietf_chacha20 , -.Nm crypto_ietf_chacha20_ctr -.Nd IETF ChaCha20 encryption functions -.Sh SYNOPSIS -.In monocypher.h -.Ft void -.Fo crypto_ietf_chacha20 -.Fa "uint8_t *cipher_text" -.Fa "const uint8_t *plain_text" -.Fa "size_t text_size" -.Fa "const uint8_t key[32]" -.Fa "const uint8_t nonce[12]" -.Fc -.Ft uint32_t -.Fo crypto_ietf_chacha20_ctr -.Fa "uint8_t *cipher_text" -.Fa "const uint8_t *plain_text" -.Fa "size_t text_size" -.Fa "const uint8_t key[32]" -.Fa "const uint8_t nonce[12]" -.Fa "const uint32_t ctr" -.Fc -.Sh DESCRIPTION -These functions provide an interface for the ChaCha20 encryption -primitive as specified by the IETF in RFC 8439. -They are provided strictly for compatibility with existing systems -or strict standards compliance. -New programs are strongly encouraged to use -.Xr crypto_xchacha20 3monocypher -instead. -.Pp -ChaCha20 is a low-level primitive. -Consider using authenticated encryption, implemented by -.Xr crypto_lock 3monocypher . -.Pp -The -.Fn crypto_ietf_chacha20 -and -.Fn crypto_ietf_chacha20_ctr -functions behave the same as -.Xr crypto_chacha20 -and -.Xr crypto_chacha20_ctr , -respectively, -but their counter and nonce have different sizes. -The nonce encompasses 12 bytes and the counter is correspondingly -reduced to 4 bytes. -The short counter limits a single key and nonce pair to 256 GiB of -data. -A 12-bytes nonce is -.Em just barely too short -to be safely chosen at random; -use a message counter instead. -RFC 8439 also permits linear feedback shift registers to generate -nonces. -.Sh RETURN VALUES -.Fn crypto_ietf_chacha20 -returns nothing. -.Fn crypto_ietf_chacha20_ctr -returns the next -.Fa ctr -to use with the same key and nonce values; -this is always -.Fa text_size -divided by 64, -plus one if there was a remainder. -.Sh SEE ALSO -.Xr crypto_chacha20 3monocypher , -.Xr crypto_lock 3monocypher , -.Xr crypto_wipe 3monocypher , -.Xr intro 3monocypher -.Sh STANDARDS -These functions implement ChaCha20 as described in RFC 8439. -.Sh HISTORY -.Fn crypto_ietf_chacha20 -and -.Fn crypto_ietf_chacha20_ctr -were added in Monocypher 3.0.0. -.Sh SECURITY CONSIDERATIONS -These functions exhibit a nonce reuse issue if the internal counter -overflows, losing all confidentiality for the parts of the data for -which the nonces overlap. -When using crypto_ietf_chacha20(), -this occurs when encrypting more than 256 GiB of data and then -incrementing the nonce. -More specifically, this can be triggered by encrypting more than -512 bytes with crypto_ietf_chacha20_ctr() at ctr = 0xffffffff -then encrypting a message at nonce[0]+1 and ctr = 0; -it can be observed that the keystreams are identical. -.Pp -RFC 8439 only specifies that the upper limit of data per message is -256 GiB of data for a nonce pair with a counter starting at 0. -It does not specify what actions can or should be taken when this limit -is exceeded. -Encrypting more than 256 GiB of data is therefore -.Sy undefined behaviour . -Monocypher may change the way it handles counter overflows at any time. diff --git a/doc/man/man3/advanced/crypto_ietf_chacha20_ctr.3monocypher b/doc/man/man3/advanced/crypto_ietf_chacha20_ctr.3monocypher deleted file mode 120000 index b56752a..0000000 --- a/doc/man/man3/advanced/crypto_ietf_chacha20_ctr.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_ietf_chacha20.3monocypher \ No newline at end of file diff --git a/doc/man/man3/advanced/crypto_poly1305_final.3monocypher b/doc/man/man3/advanced/crypto_poly1305_final.3monocypher deleted file mode 120000 index 861ea25..0000000 --- a/doc/man/man3/advanced/crypto_poly1305_final.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_poly1305.3monocypher \ No newline at end of file diff --git a/doc/man/man3/advanced/crypto_poly1305_init.3monocypher b/doc/man/man3/advanced/crypto_poly1305_init.3monocypher deleted file mode 120000 index 861ea25..0000000 --- a/doc/man/man3/advanced/crypto_poly1305_init.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_poly1305.3monocypher \ No newline at end of file diff --git a/doc/man/man3/advanced/crypto_poly1305_update.3monocypher b/doc/man/man3/advanced/crypto_poly1305_update.3monocypher deleted file mode 120000 index 861ea25..0000000 --- a/doc/man/man3/advanced/crypto_poly1305_update.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_poly1305.3monocypher \ No newline at end of file diff --git a/doc/man/man3/advanced/crypto_x25519_dirty_fast.3monocypher b/doc/man/man3/advanced/crypto_x25519_dirty_fast.3monocypher deleted file mode 100644 index 2998f64..0000000 --- a/doc/man/man3/advanced/crypto_x25519_dirty_fast.3monocypher +++ /dev/null @@ -1,125 +0,0 @@ -.\" 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) 2020, 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 2020 and 2022 by 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 -.\" -.\" -.Dd February 13, 2022 -.Dt CRYPTO_X25519_DIRTY_FAST 3monocypher -.Os -.Sh NAME -.Nm crypto_x25519_dirty_fast , -.Nm crypto_x25519_dirty_small -.Nd generation of Curve25519 points with a low-order component -.Sh SYNOPSIS -.In monocypher.h -.Ft void -.Fo crypto_x25519_dirty_fast -.Fa "uint8_t pk[32]" -.Fa "const uint8_t sk[32]" -.Fc -.Ft void -.Fo crypto_x25519_dirty_small -.Fa "uint8_t pk[32]" -.Fa "const uint8_t sk[32]" -.Fc -.Sh DESCRIPTION -These functions are used in public key generation for -.Xr crypto_curve_to_hidden 3monocypher . -.Sy This is a highly advanced feature ; -unless you are reading this because you were referred here from -.Xr crypto_curve_to_hidden 3monocypher , -.Sy you likely have no reason to be using these functions -and are probably looking for -.Xr crypto_x25519 3monocypher -instead. -Expect elliptic curve jargon on this page. -.Pp -Both functions generate a Curve25519 public key -.Fa pk -from the given secret key -.Fa sk . -The public keys are on the -.Em whole -curve, rather than just the main prime-order subgroup. -Both do the same with different code size and memory characteristics: -.Fn crypto_x25519_dirty_fast -uses multiple large temporary variables and functions that are -normally used internally for -.Xr crypto_sign 3monocypher . -Accordingly, it uses both more memory (for the temporary variables) and -more code size (unless the signing code is already compiled in -elsewhere). -.Fn crypto_x25519_dirty_small -yields the same result with less code, less memory, and more time than -.Fn crypto_x25519_dirty_fast . -.Pp -The resulting public keys are to be used with -.Xr crypto_x25519 3monocypher , -which clears the cofactor. -.Sh RETURN VALUES -These functions have no return value. -They cannot fail. -.Sh SEE ALSO -.Xr crypto_curve_to_hidden 3monocypher , -.Xr crypto_x25519_public_key 3monocypher , -.Xr intro 3monocypher -.Sh HISTORY -The -.Fn crypto_x25519_dirty_fast -and -.Fn crypto_x25519_dirty_small -functions first appeared in Monocypher 3.1.0. -.Sh IMPLEMENTATION DETAILS -The slow variant is approximately an entire two times slower than the -fast variant. -When considering that, on average, two calls to this function will be -required for obtaining a valid key pair for -.Xr crypto_curve_to_hidden 3monocypher , -this adds up to an -.Em average -effective slowdown for key pair generation of a factor of four. diff --git a/doc/man/man3/advanced/crypto_x25519_dirty_small.3monocypher b/doc/man/man3/advanced/crypto_x25519_dirty_small.3monocypher deleted file mode 120000 index af980f3..0000000 --- a/doc/man/man3/advanced/crypto_x25519_dirty_small.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_x25519_dirty_fast.3monocypher \ No newline at end of file diff --git a/doc/man/man3/advanced/crypto_x25519_inverse.3monocypher b/doc/man/man3/advanced/crypto_x25519_inverse.3monocypher deleted file mode 100644 index 5cb093d..0000000 --- a/doc/man/man3/advanced/crypto_x25519_inverse.3monocypher +++ /dev/null @@ -1,103 +0,0 @@ -.\" 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) 2020, 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 2020 and 2022 by 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 -.\" -.\" -.Dd February 13, 2022 -.Dt CRYPTO_X25519_INVERSE 3MONOCYPHER -.Os -.Sh NAME -.Nm crypto_x25519_inverse -.Nd X25519 scalar multiplication with the multiplicative inverse of a scalar -.Sh SYNOPSIS -.In monocypher.h -.Ft void -.Fo crypto_x25519_inverse -.Fa "uint8_t blind_salt[32]" -.Fa "const uint8_t private_key[32]" -.Fa "const uint8_t curve_point[32]" -.Fc -.Sh DESCRIPTION -The -.Fn crypto_x25519_inverse -function performs scalar multiplication of the multiplicative inverse -of a scalar for X25519. -.Sy This is a highly advanced, specialized feature ; -unless you are implementing a protocol that requires this specifically, -.Sy you likely have no reason to be using these functions -and are probably looking for -.Xr crypto_x25519 3monocypher -instead. -Expect elliptic curve jargon on this page. -.Pp -This function is used, for example, with exponential blinding in -oblivious pseudo-random functions (OPRFs). -The arguments are: -.Bl -tag -width Ds -.It Fa blind_salt -The output point. -.It Fa private_key -The private key (scalar) to use. -First, the value is clamped, -then the clamped value's multiplicative inverse (modulo the curve order) -is determined. -The clamped value's multiplicative inverse then has its cofactor -cleared, -and that final value is then used for scalar multiplication. -.It Fa curve_point -The curve point on X25519 to multiply with the multiplicative inverse -(modulo the curve order) of -.Fa private_key . -.El -.Sh SEE ALSO -.Xr crypto_x25519 3monocypher , -.Xr intro 3monocypher -.Sh HISTORY -The -.Fn crypto_x25519_inverse -function first appeared in Monocypher 3.1.0. diff --git a/doc/man/man3/advanced/crypto_x25519_to_eddsa.3monocypher b/doc/man/man3/advanced/crypto_x25519_to_eddsa.3monocypher deleted file mode 120000 index 8d7c433..0000000 --- a/doc/man/man3/advanced/crypto_x25519_to_eddsa.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_eddsa_to_x25519.3monocypher \ No newline at end of file diff --git a/doc/man/man3/advanced/crypto_xchacha20.3monocypher b/doc/man/man3/advanced/crypto_xchacha20.3monocypher deleted file mode 120000 index 2dfb4d4..0000000 --- a/doc/man/man3/advanced/crypto_xchacha20.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_chacha20.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_aead_init_djb.3monocypher b/doc/man/man3/crypto_aead_init_djb.3monocypher deleted file mode 120000 index 52fef1a..0000000 --- a/doc/man/man3/crypto_aead_init_djb.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_aead_lock.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_aead_init_ietf.3monocypher b/doc/man/man3/crypto_aead_init_ietf.3monocypher deleted file mode 120000 index 52fef1a..0000000 --- a/doc/man/man3/crypto_aead_init_ietf.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_aead_lock.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_aead_read.3monocypher b/doc/man/man3/crypto_aead_read.3monocypher deleted file mode 120000 index 52fef1a..0000000 --- a/doc/man/man3/crypto_aead_read.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_aead_lock.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_aead_unlock.3monocypher b/doc/man/man3/crypto_aead_unlock.3monocypher deleted file mode 120000 index 52fef1a..0000000 --- a/doc/man/man3/crypto_aead_unlock.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_aead_lock.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_aead_write.3monocypher b/doc/man/man3/crypto_aead_write.3monocypher deleted file mode 120000 index 52fef1a..0000000 --- a/doc/man/man3/crypto_aead_write.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_aead_lock.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_blake2b_final.3monocypher b/doc/man/man3/crypto_blake2b_final.3monocypher deleted file mode 120000 index 63f57c0..0000000 --- a/doc/man/man3/crypto_blake2b_final.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_blake2b.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_blake2b_init.3monocypher b/doc/man/man3/crypto_blake2b_init.3monocypher deleted file mode 120000 index 63f57c0..0000000 --- a/doc/man/man3/crypto_blake2b_init.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_blake2b.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_blake2b_update.3monocypher b/doc/man/man3/crypto_blake2b_update.3monocypher deleted file mode 120000 index 63f57c0..0000000 --- a/doc/man/man3/crypto_blake2b_update.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_blake2b.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_check.3monocypher b/doc/man/man3/crypto_check.3monocypher deleted file mode 120000 index f359740..0000000 --- a/doc/man/man3/crypto_check.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_sign.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_sign_public_key.3monocypher b/doc/man/man3/crypto_sign_public_key.3monocypher deleted file mode 120000 index f359740..0000000 --- a/doc/man/man3/crypto_sign_public_key.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_sign.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_verify32.3monocypher b/doc/man/man3/crypto_verify32.3monocypher deleted file mode 120000 index 0d26e5d..0000000 --- a/doc/man/man3/crypto_verify32.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_verify16.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_verify64.3monocypher b/doc/man/man3/crypto_verify64.3monocypher deleted file mode 120000 index 0d26e5d..0000000 --- a/doc/man/man3/crypto_verify64.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_verify16.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_x25519_public_key.3monocypher b/doc/man/man3/crypto_x25519_public_key.3monocypher deleted file mode 120000 index cc26d9f..0000000 --- a/doc/man/man3/crypto_x25519_public_key.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_x25519.3monocypher \ No newline at end of file diff --git a/doc/man/man3/optional/crypto_ed25519_check.3monocypher b/doc/man/man3/optional/crypto_ed25519_check.3monocypher deleted file mode 120000 index f6e345b..0000000 --- a/doc/man/man3/optional/crypto_ed25519_check.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_ed25519_sign.3monocypher \ No newline at end of file diff --git a/doc/man/man3/optional/crypto_ed25519_public_key.3monocypher b/doc/man/man3/optional/crypto_ed25519_public_key.3monocypher deleted file mode 120000 index f6e345b..0000000 --- a/doc/man/man3/optional/crypto_ed25519_public_key.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_ed25519_sign.3monocypher \ No newline at end of file diff --git a/doc/man/man3/optional/crypto_hmac_sha512_final.3monocypher b/doc/man/man3/optional/crypto_hmac_sha512_final.3monocypher deleted file mode 120000 index fee9097..0000000 --- a/doc/man/man3/optional/crypto_hmac_sha512_final.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_hmac_sha512.3monocypher \ No newline at end of file diff --git a/doc/man/man3/optional/crypto_hmac_sha512_init.3monocypher b/doc/man/man3/optional/crypto_hmac_sha512_init.3monocypher deleted file mode 120000 index fee9097..0000000 --- a/doc/man/man3/optional/crypto_hmac_sha512_init.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_hmac_sha512.3monocypher \ No newline at end of file diff --git a/doc/man/man3/optional/crypto_hmac_sha512_update.3monocypher b/doc/man/man3/optional/crypto_hmac_sha512_update.3monocypher deleted file mode 120000 index fee9097..0000000 --- a/doc/man/man3/optional/crypto_hmac_sha512_update.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_hmac_sha512.3monocypher \ No newline at end of file diff --git a/doc/man/man3/optional/crypto_sha512_final.3monocypher b/doc/man/man3/optional/crypto_sha512_final.3monocypher deleted file mode 120000 index c7fecc6..0000000 --- a/doc/man/man3/optional/crypto_sha512_final.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_sha512.3monocypher \ No newline at end of file diff --git a/doc/man/man3/optional/crypto_sha512_init.3monocypher b/doc/man/man3/optional/crypto_sha512_init.3monocypher deleted file mode 120000 index c7fecc6..0000000 --- a/doc/man/man3/optional/crypto_sha512_init.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_sha512.3monocypher \ No newline at end of file diff --git a/doc/man/man3/optional/crypto_sha512_update.3monocypher b/doc/man/man3/optional/crypto_sha512_update.3monocypher deleted file mode 120000 index c7fecc6..0000000 --- a/doc/man/man3/optional/crypto_sha512_update.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_sha512.3monocypher \ No newline at end of file diff --git a/doc/man2html.sh b/doc/man2html.sh deleted file mode 100755 index bab2ba1..0000000 --- a/doc/man2html.sh +++ /dev/null @@ -1,149 +0,0 @@ -#! /bin/sh - -# This file is dual-licensed. Choose whichever licence you want from -# the two licences listed below. -# -# 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, Loup Vaillant -# Copyright (c) 2017, 2019, 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 and 2019 by Loup Vaillant 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 -# - -DIR=$(dirname "$0") - -# clean before -rm -rf "$DIR/html" - -convert() { - MANS=$1 - HTML=$2 - for name in $(ls -1 "$MANS/" | sed 's/.3monocypher//') - do - test -f "$MANS/$name.3monocypher" || continue - mandoc \ - -Oman=%N.html,style=style.css \ - -Thtml "$MANS/$name.3monocypher" \ - > "$DIR/html/$HTML/$name.html" - done - cp "$DIR/style.css" "$DIR/html/$HTML/" -} - -mkdir -p "$DIR/html" -mkdir -p "$DIR/html/advanced" -mkdir -p "$DIR/html/optional" -convert "$DIR/man/man3" "." -convert "$DIR/man/man3/advanced" "advanced" -convert "$DIR/man/man3/optional" "optional" - -substitute() { - HTML=$1 - for file in $(ls -1 "$HTML/" | grep ".html$") - do - sed \ - -e 's|href="intro.html"| href="../intro.html"| '\ - -e 's|href="crypto_argon2i_general.html"| href="../crypto_argon2i_general.html"| '\ - -e 's|href="crypto_argon2i.html"| href="../crypto_argon2i.html"| '\ - -e 's|href="crypto_blake2b_final.html"| href="../crypto_blake2b_final.html"| '\ - -e 's|href="crypto_blake2b_general.html"| href="../crypto_blake2b_general.html"| '\ - -e 's|href="crypto_blake2b_general_init.html"| href="../crypto_blake2b_general_init.html"| '\ - -e 's|href="crypto_blake2b.html"| href="../crypto_blake2b.html"| '\ - -e 's|href="crypto_blake2b_init.html"| href="../crypto_blake2b_init.html"| '\ - -e 's|href="crypto_blake2b_update.html"| href="../crypto_blake2b_update.html"| '\ - -e 's|href="crypto_check.html"| href="../crypto_check.html"| '\ - -e 's|href="crypto_lock_aead.html"| href="../crypto_lock_aead.html"| '\ - -e 's|href="crypto_lock.html"| href="../crypto_lock.html"| '\ - -e 's|href="crypto_sign.html"| href="../crypto_sign.html"| '\ - -e 's|href="crypto_sign_public_key.html"| href="../crypto_sign_public_key.html"| '\ - -e 's|href="crypto_unlock_aead.html"| href="../crypto_unlock_aead.html"| '\ - -e 's|href="crypto_unlock.html"| href="../crypto_unlock.html"| '\ - -e 's|href="crypto_verify16.html"| href="../crypto_verify16.html"| '\ - -e 's|href="crypto_verify32.html"| href="../crypto_verify32.html"| '\ - -e 's|href="crypto_verify64.html"| href="../crypto_verify64.html"| '\ - -e 's|href="crypto_wipe.html"| href="../crypto_wipe.html"| '\ - -e 's|href="crypto_x25519.html"| href="../crypto_x25519.html"| '\ - -e 's|href="crypto_chacha20_ctr.html"| href="../advanced/crypto_chacha20_ctr.html"| '\ - -e 's|href="crypto_chacha20_H.html"| href="../advanced/crypto_chacha20_H.html"| '\ - -e 's|href="crypto_chacha20.html"| href="../advanced/crypto_chacha20.html"| '\ - -e 's|href="crypto_check_final.html"| href="../advanced/crypto_check_final.html"| '\ - -e 's|href="crypto_check_init_custom_hash.html"| href="../advanced/crypto_check_init_custom_hash.html"| '\ - -e 's|href="crypto_check_init.html"| href="../advanced/crypto_check_init.html"| '\ - -e 's|href="crypto_check_update.html"| href="../advanced/crypto_check_update.html"| '\ - -e 's|href="crypto_curve_to_hidden.html"| href="../advanced/crypto_curve_to_hidden.html"| '\ - -e 's|href="crypto_from_eddsa_private.html"| href="../advanced/crypto_from_eddsa_private.html"| '\ - -e 's|href="crypto_from_eddsa_public.html"| href="../advanced/crypto_from_eddsa_public.html"| '\ - -e 's|href="crypto_hchacha20.html"| href="../advanced/crypto_hchacha20.html"| '\ - -e 's|href="crypto_hidden_key_pair.html"| href="../advanced/crypto_hidden_key_pair.html"| '\ - -e 's|href="crypto_hidden_to_curve.html"| href="../advanced/crypto_hidden_to_curve.html"| '\ - -e 's|href="crypto_ietf_chacha20_ctr.html"| href="../advanced/crypto_ietf_chacha20_ctr.html"| '\ - -e 's|href="crypto_ietf_chacha20.html"| href="../advanced/crypto_ietf_chacha20.html"| '\ - -e 's|href="crypto_poly1305_final.html"| href="../advanced/crypto_poly1305_final.html"| '\ - -e 's|href="crypto_poly1305.html"| href="../advanced/crypto_poly1305.html"| '\ - -e 's|href="crypto_poly1305_init.html"| href="../advanced/crypto_poly1305_init.html"| '\ - -e 's|href="crypto_poly1305_update.html"| href="../advanced/crypto_poly1305_update.html"| '\ - -e 's|href="crypto_sign_final.html"| href="../advanced/crypto_sign_final.html"| '\ - -e 's|href="crypto_sign_init_first_pass_custom_hash.html"| href="../advanced/crypto_sign_init_first_pass_custom_hash.html"|'\ - -e 's|href="crypto_sign_init_first_pass.html"| href="../advanced/crypto_sign_init_first_pass.html"| '\ - -e 's|href="crypto_sign_init_second_pass.html"| href="../advanced/crypto_sign_init_second_pass.html"| '\ - -e 's|href="crypto_sign_public_key_custom_hash.html"| href="../advanced/crypto_sign_public_key_custom_hash.html"| '\ - -e 's|href="crypto_sign_update.html"| href="../advanced/crypto_sign_update.html"| '\ - -e 's|href="crypto_x25519_dirty_fast.html"| href="../advanced/crypto_x25519_dirty_fast.html"| '\ - -e 's|href="crypto_x25519_dirty_small.html"| href="../advanced/crypto_x25519_dirty_small.html"| '\ - -e 's|href="crypto_x25519_inverse.html"| href="../advanced/crypto_x25519_inverse.html"| '\ - -e 's|href="crypto_x25519_public_key.html"| href="../advanced/crypto_x25519_public_key.html"| '\ - -e 's|href="crypto_xchacha20_ctr.html"| href="../advanced/crypto_xchacha20_ctr.html"| '\ - -e 's|href="crypto_xchacha20.html"| href="../advanced/crypto_xchacha20.html"| '\ - -i "$HTML/$file" - done -} - -substitute "$DIR/html" -substitute "$DIR/html/advanced" -substitute "$DIR/html/optional" - -for file in $(ls -1 "$DIR/html" | grep ".html$") -do - sed 's|href="../|href="|' -i "$DIR/html/$file" -done diff --git a/makefile b/makefile index 0eb0c3f..d079928 100644 --- a/makefile +++ b/makefile @@ -61,11 +61,6 @@ SONAME=libmonocypher.so.3 VERSION=__git__ -ifdef USE_ED25519 -LINK_ED25519=lib/monocypher-ed25519.o -INSTALL_ED25519=cp src/optional/monocypher-ed25519.h $(DESTDIR)/$(INCLUDEDIR) -endif - .PHONY: all library static-library dynamic-library \ install install-doc pkg-config-libhydrogen \ check test tis-ci ctgrind \ @@ -80,18 +75,14 @@ install: library src/monocypher.h monocypher.pc install-doc mkdir -p $(DESTDIR)/$(LIBDIR) mkdir -p $(DESTDIR)/$(PKGCONFIGDIR) cp -P lib/libmonocypher.a lib/libmonocypher.so* $(DESTDIR)/$(LIBDIR) - cp src/monocypher.h $(DESTDIR)/$(INCLUDEDIR) - $(INSTALL_ED25519) + cp src/monocypher.h $(DESTDIR)/$(INCLUDEDIR) + cp src/optional/monocypher-ed25519.h $(DESTDIR)/$(INCLUDEDIR) sed "s|PREFIX|$(PREFIX)|" monocypher.pc \ > $(DESTDIR)/$(PKGCONFIGDIR)/monocypher.pc install-doc: mkdir -p $(DESTDIR)/$(MANDIR) - cp -PR doc/man/man3/*.3monocypher $(DESTDIR)/$(MANDIR) - cp -PR doc/man/man3/advanced/*.3monocypher $(DESTDIR)/$(MANDIR) -ifdef USE_ED25519 - cp -PR doc/man/man3/optional/*.3monocypher $(DESTDIR)/$(MANDIR) -endif + cp -PR doc/man3/*.3monocypher $(DESTDIR)/$(MANDIR) pkg-config-libhydrogen: mkdir -p $(DESTDIR)/$(PKGCONFIGDIR) @@ -132,12 +123,12 @@ ctgrind: ctgrind.out valgrind ./ctgrind.out # Monocypher libraries -lib/libmonocypher.a: lib/monocypher.o $(LINK_ED25519) +lib/libmonocypher.a: lib/monocypher.o lib/monocypher-ed25519.o $(AR) cr $@ $^ lib/libmonocypher.so: lib/$(SONAME) @mkdir -p $(@D) ln -sf `basename $<` $@ -lib/$(SONAME): lib/monocypher.o $(LINK_ED25519) +lib/$(SONAME): lib/monocypher.o lib/monocypher-ed25519.o @mkdir -p $(@D) $(CC) $(CFLAGS) $(LDFLAGS) -shared -Wl,-soname,$(SONAME) -o $@ $^ lib/monocypher-ed25519.o: src/optional/monocypher-ed25519.c \ diff --git a/src/monocypher.c b/src/monocypher.c index fafa169..f6af5de 100644 --- a/src/monocypher.c +++ b/src/monocypher.c @@ -2279,7 +2279,7 @@ static void hash_reduce(u8 h[32], // h = HASH(R || public_key || message) % L // S = ((h * a) + r) % L // signature = R || S -void crypto_eddsa_sign(u8 signature [64], const u8 secret_key[32], +void crypto_eddsa_sign(u8 signature [64], const u8 secret_key[64], const u8 *message, size_t message_size) { u8 a[64]; // secret scalar and prefix @@ -2698,7 +2698,7 @@ void crypto_elligator_key_pair(u8 hidden[32], u8 secret_key[32], u8 seed[32]) crypto_chacha20_djb(buf, 0, 64, buf+32, zero, 0); crypto_x25519_dirty_fast(pk, buf); // or the "small" version } while(crypto_elligator_rev(buf+32, pk, buf[32])); - // Note that the return value of crypto_curve_to_hidden() is + // Note that the return value of crypto_elligator_rev() is // independent from its tweak parameter. // Therefore, buf[32] is not actually reused. Either we loop one // more time and buf[32] is used for the new seed, or we succeeded, diff --git a/src/monocypher.h b/src/monocypher.h index 15f1f3e..adeaafa 100644 --- a/src/monocypher.h +++ b/src/monocypher.h @@ -63,10 +63,6 @@ namespace MONOCYPHER_CPP_NAMESPACE { extern "C" { #endif -//////////////////////////// -/// High level interface /// -//////////////////////////// - // Constant time comparisons // ------------------------- @@ -189,6 +185,7 @@ void crypto_argon2(uint8_t *hash, uint32_t hash_size, void *work_area, crypto_argon2_inputs inputs, crypto_argon2_extras extras); + // Key exchange (X-25519) // ---------------------- @@ -200,25 +197,52 @@ void crypto_x25519(uint8_t raw_shared_secret[32], const uint8_t your_secret_key [32], const uint8_t their_public_key [32]); +// Conversion to EdDSA +void crypto_x25519_to_eddsa(uint8_t eddsa[32], const uint8_t x25519[32]); + +// scalar "division" +// Used for OPRF. Be aware that exponential blinding is less secure +// than Diffie-Hellman key exchange. +void crypto_x25519_inverse(uint8_t blind_salt [32], + const uint8_t private_key[32], + const uint8_t curve_point[32]); + +// "Dirty" versions of x25519_public_key(). +// Use with crypto_elligator_rev(). +// Leaks 3 bits of the private key. +void crypto_x25519_dirty_small(uint8_t pk[32], const uint8_t sk[32]); +void crypto_x25519_dirty_fast (uint8_t pk[32], const uint8_t sk[32]); + + +// Signatures +// ---------- -// Signatures (EdDSA with curve25519 + BLAKE2b) -// -------------------------------------------- +// EdDSA with curve25519 + BLAKE2b void crypto_eddsa_key_pair(uint8_t secret_key[64], uint8_t public_key[32], uint8_t seed[32]); void crypto_eddsa_sign(uint8_t signature [64], - const uint8_t secret_key[32], + const uint8_t secret_key[64], const uint8_t *message, size_t message_size); int crypto_eddsa_check(const uint8_t signature [64], const uint8_t public_key[32], const uint8_t *message, size_t message_size); +// Conversion to X25519 +void crypto_eddsa_to_x25519(uint8_t x25519[32], const uint8_t eddsa[32]); -//////////////////////////// -/// Low level primitives /// -//////////////////////////// +// EdDSA building blocks +void crypto_eddsa_trim_scalar(uint8_t out[32], const uint8_t in[32]); +void crypto_eddsa_reduce(uint8_t reduced[32], const uint8_t expanded[64]); +void crypto_eddsa_mul_add(uint8_t r[32], + const uint8_t a[32], + const uint8_t b[32], + const uint8_t c[32]); +void crypto_eddsa_scalarbase(uint8_t point[32], const uint8_t scalar[32]); +int crypto_eddsa_check_equation(const uint8_t signature[64], + const uint8_t public_key[32], + const uint8_t h_ram[32]); -// For experts only. You have been warned. // Chacha20 // -------- @@ -280,42 +304,6 @@ void crypto_poly1305_update(crypto_poly1305_ctx *ctx, void crypto_poly1305_final (crypto_poly1305_ctx *ctx, uint8_t mac[16]); -// X-25519 extras -// -------------- - -// "Dirty" versions of x25519_public_key() -// Only use to generate ephemeral keys you want to hide. -// Note that those functions leaks 3 bits of the private key. -void crypto_x25519_dirty_small(uint8_t pk[32], const uint8_t sk[32]); -void crypto_x25519_dirty_fast (uint8_t pk[32], const uint8_t sk[32]); - -// scalar "division" -// Used for OPRF. Be aware that exponential blinding is less secure -// than Diffie-Hellman key exchange. -void crypto_x25519_inverse(uint8_t blind_salt [32], - const uint8_t private_key[32], - const uint8_t curve_point[32]); - - -// EdDSA building blocks -// --------------------- -void crypto_eddsa_trim_scalar(uint8_t out[32], const uint8_t in[32]); -void crypto_eddsa_reduce(uint8_t reduced[32], const uint8_t expanded[64]); -void crypto_eddsa_mul_add(uint8_t r[32], - const uint8_t a[32], - const uint8_t b[32], - const uint8_t c[32]); -void crypto_eddsa_scalarbase(uint8_t point[32], const uint8_t scalar[32]); -int crypto_eddsa_check_equation(const uint8_t signature[64], - const uint8_t public_key[32], - const uint8_t h_ram[32]); - -// EdDSA <--> X25519 -// ----------------- -void crypto_eddsa_to_x25519(uint8_t x25519[32], const uint8_t eddsa[32]); -void crypto_x25519_to_eddsa(uint8_t eddsa[32], const uint8_t x25519[32]); - - // Elligator 2 // ----------- -- 2.47.3