monocypher-*/
**/__pycache__/**
doc/html/
+doc/man3/
tests/vectors.h
.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]"
.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]"
.\" ----------------------------------------------------------------------------
.\"
.\" 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.
.\"
.\" with this software. If not, see
.\" <https://creativecommons.org/publicdomain/zero/1.0/>
.\"
-.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"
.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"
.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"
.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.
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
\(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;
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);
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 */
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);
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
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.
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.
.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
.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
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 ,
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 .
.\"
.\" ----------------------------------------------------------------------------
.\"
-.\" 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.
.\"
.\" ----------------------------------------------------------------------------
.\"
-.\" 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
.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
.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.
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
.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
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 ,
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.
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.
.\" with this software. If not, see
.\" <https://creativecommons.org/publicdomain/zero/1.0/>
.\"
-.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]"
.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
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;
.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
.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
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. */
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);
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
.\"
.\" ----------------------------------------------------------------------------
.\"
-.\" 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
.\"
.\" ----------------------------------------------------------------------------
.\"
-.\" 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
.\" with this software. If not, see
.\" <https://creativecommons.org/publicdomain/zero/1.0/>
.\"
-.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
.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
.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
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
/* 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
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 .
--- /dev/null
+#! /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
+# <https://creativecommons.org/publicdomain/zero/1.0/>
+
+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
+++ /dev/null
-.\" 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
-.\" <https://creativecommons.org/publicdomain/zero/1.0/>
-.\"
-.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 .
+++ /dev/null
-.\" 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
-.\" <https://creativecommons.org/publicdomain/zero/1.0/>
-.\"
-.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.
+++ /dev/null
-crypto_curve_to_hidden.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_curve_to_hidden.3monocypher
\ No newline at end of file
+++ /dev/null
-.\" 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
-.\" <https://creativecommons.org/publicdomain/zero/1.0/>
-.\"
-.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.
+++ /dev/null
-crypto_ietf_chacha20.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_poly1305.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_poly1305.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_poly1305.3monocypher
\ No newline at end of file
+++ /dev/null
-.\" 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
-.\" <https://creativecommons.org/publicdomain/zero/1.0/>
-.\"
-.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.
+++ /dev/null
-crypto_x25519_dirty_fast.3monocypher
\ No newline at end of file
+++ /dev/null
-.\" 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
-.\" <https://creativecommons.org/publicdomain/zero/1.0/>
-.\"
-.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.
+++ /dev/null
-crypto_eddsa_to_x25519.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_chacha20.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_aead_lock.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_aead_lock.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_aead_lock.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_aead_lock.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_aead_lock.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_blake2b.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_blake2b.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_blake2b.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_sign.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_sign.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_verify16.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_verify16.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_x25519.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_ed25519_sign.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_ed25519_sign.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_hmac_sha512.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_hmac_sha512.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_hmac_sha512.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_sha512.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_sha512.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_sha512.3monocypher
\ No newline at end of file
+++ /dev/null
-#! /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
-# <https://creativecommons.org/publicdomain/zero/1.0/>
-
-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
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 \
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)
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 \
// 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
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,
extern "C" {
#endif
-////////////////////////////
-/// High level interface ///
-////////////////////////////
-
// Constant time comparisons
// -------------------------
crypto_argon2_inputs inputs,
crypto_argon2_extras extras);
+
// Key exchange (X-25519)
// ----------------------
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
// --------
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
// -----------
projects / Monocypher.git / commitdiff