From: Fabio Scotoni <34964387+fscoto@users.noreply.github.com> Date: Tue, 24 Mar 2020 12:40:07 +0000 (+0100) Subject: Document Elligator and related plus X25519 inverse X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=ecb4ded08191f46ddc0c50bcfa1c6242f82acf87;p=Monocypher.git Document Elligator and related plus X25519 inverse --- diff --git a/doc/man/man3/crypto_curve_to_hidden.3monocypher b/doc/man/man3/crypto_curve_to_hidden.3monocypher new file mode 100644 index 0000000..b1abe7e --- /dev/null +++ b/doc/man/man3/crypto_curve_to_hidden.3monocypher @@ -0,0 +1,283 @@ +.\" 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 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 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 March 24, 2020 +.Dt CRYPTO_CURVE_TO_HIDDEN 3MONOCYPHER +.Os +.Sh NAME +.Nm crypto_curve_to_hidden , +.Nm crypto_hidden_to_curve , +.Nm crypto_hidden_key_pair +.Nd hiding of X25519 public keys +.Sh SYNOPSIS +.In monocypher.h +.Ft int +.Fo crypto_curve_to_hidden +.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 +.Fa "uint8_t hidden[32]" +.Fa "uint8_t secret_key[32]" +.Fa "uint8_t seed[32]" +.Fc +.Sh DESCRIPTION +These functions allow obfuscating X25519 public keys by making +them appear effectively indistinguishable from random noise. +This is of interest for key exchange protocols that require +indistinguishability from randomness, such as padded uniform random +blobs (PURBs) and exponential blinding in oblivious pseudo-random +functions (OPRFs). +This is an +.Em advanced feature +\(en unless you are implementing an protocol that requires +indistinguishability of all communications from random noise, +consider +.Xr crypto_key_exchange 3monocypher +instead. +.Pp +For understanding what these functions do, it is important to note that +a +.Dq public key +in this context refers to a +.Em point on Curve25519 . +This also means that these functions yield data unsuitable for use with +.Xr crypto_sign 3monocypher +and related functions. +.Pp +.Fn crypto_curve_to_hidden +takes a public key +.Fa curve +and a +.Fa tweak , +hiding the public key it so that it is effectively indistinguishable +from random noise. +Note that only +.Xr crypto_x25519_dangerous_fast 3monocypher +or +.Xr crypto_x25519_dangerous_small 3monocypher +to generate a suitable public key; +the +.Xr crypto_x25519 3monocypher +function is insufficient. +The +.Fa tweak +must be chosen at random. +Even then, this operation +.Em may +fail: +Not all curve points are capable of being hidden. +In this case, +.Fn crypto_curve_to_hidden +must be tried again with a new key pair. +On average, two attempts are needed. +Once a suitable public key has been found, +.Fn crypto_curve_to_hidden +always succeeds it. +Given the same values for +.Fa tweak +and +.Fa curve , +.Fn crypto_curve_to_hidden +yields the same output value +.Fa hidden . +.Pp +.Fn crypto_hidden_to_curve +performs the inverse operation: +It decodes a hidden point to a curve point on Curve25519. +.Pp +.Fn crypto_hidden_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. +The +.Em 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 +uses +.Xr crypto_x25519_dangerous_fast 3monocypher +internally; +if code size is an important concern, +its functionality can be replicated with +.Xr crypto_x25519_dangerous_fast 3monocypher +instead. +.Pp +The arguments are: +.Bl -tag -width Ds +.It Fa curve +A point on the curve, which is a Curve25519 public key generated with +either +.Xr crypto_x25519_dangerous_fast 3monocypher +or +.Xr crypto_x25519_dangerous_small 3monocypher . +.It Fa hidden +The hidden encoding of a point on the curve which is effectively +indistinguishable from random. +.It Fa secret_key +The secret key that was generated from the given +.Fa seed . +.It Fa seed +A 32-byte random number from which to derive a key pair. +See +.Xr intro 3monocypher +for advice about generating random bytes (use the operating system's +random number generator). +The +.Fa seed +is wiped automatically. +.It Fa tweak +A 1-byte random number, +which influences the final output of +.Fn crypto_curve_to_hidden . +.El +.Pp +The +.Fa hidden , +.Fa curve , +and +.Fa tweak +arguments may overlap or point at the same buffer. +.Sh RETURN VALUES +.Fn crypto_curve_to_hidden +returns 0 on success, -1 if the given +.Fa curve +argument is unsuitable for hiding. +.Pp +.Fn crypto_hidden_to_curve +and +.Fn crypto_hidden_key_pair +return nothing; they cannot fail. +.Sh EXAMPLES +Generate a key pair manually using +.Xr crypto_x25519_dangerous_small 3monocypher +instead of its fast variant: +.Bd -literal -offset indent +uint8_t sk [32]; /* Secret key output */ +uint8_t pk [32]; /* Hidden public key output */ +uint8_t tweak; /* Random tweak input */ +arc4random_buf(tweak, 1); +for (;;) { + arc4random_buf(sk, 32); + crypto_x25519_dangerous_small(pk, sk); + if (crypto_curve_to_hidden(pk, pk, tweak) == 0) + break; +} +/* Now save either: + * - the key pair (sk, pk), or + * - the secret key and tweak (sk, tweak) to reliably + * re-generate the same value of pk. + */ +.Ed +.Pp +Performing a key exchange with the other party's public key having been +hidden: +.Bd -literal -offset indent +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_tshared_key[32]; /* Shared session key */ +crypto_hidden_to_curve(their_pk, hidden_pk); +crypto_key_exchange(shared_key, your_sk, their_pk); +/* Wipe secrets if they are no longer needed */ +crypto_wipe(your_sk, 32); +.Ed +.Sh SEE ALSO +.Xr crypto_key_exchange 3monocypher , +.Xr crypto_x25519 3monocypher , +.Xr crypto_x25519_dangerous_small 3monocypher , +.Xr intro 3monocypher +.Sh STANDARDS +These functions implement the Elligator 2 mapping for Curve25519. +This mapping is incompatible with both the hash-to-curve Internet draft +and the implementation of Elligator 2 in libsodium. +Elligator 2 was described in: +.Rs +.%A Daniel J. Bernstein +.%A Mike Hamburg +.%A Anna Krasnova +.%A Tanja Lange +.%T Elligator: Elliptic-curve points indistinguishable from uniform random strings +.%J CCS '13: Proceedings of the 2013 ACM SIGSAC conference on Computer & communications security +.%I Association for Computing Machinery +.%D 2013 +.%P pp. 967\(en980 +.Re +.Sh HISTORY +The +.Fn crypto_curve_to_hidden , +.Fn crypto_hidden_to_curve , +and +.Fn crypto_hidden_key_pair +functions first appeared in Monocypher 3.1.0. +.Sh SECURITY CONSIDERATIONS +The secret keys for the public keys fed into +.Fn crypto_curve_to_hidden +.Sy must be chosen randomly , +rather than deterministically. +Otherwise, the timing information given by the required number of +retries also leaks information on the secret keys. +.Pp +This function +.Em helps +build highly difficult-to-analyze protocols, +but it is insufficient by itself: +Other metadata, such as the amount of bytes sent in a packet or the size +of the 32-byte random-looking string that represents the curve point +itself, can be very strong indicators of the use of cryptography. +Consider using appropriate padding algorithms, such as PADME, +and obscure other metadata as much as possible. diff --git a/doc/man/man3/crypto_hidden_key_pair.3monocypher b/doc/man/man3/crypto_hidden_key_pair.3monocypher new file mode 120000 index 0000000..3717a86 --- /dev/null +++ b/doc/man/man3/crypto_hidden_key_pair.3monocypher @@ -0,0 +1 @@ +crypto_curve_to_hidden.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_hidden_to_curve.3monocypher b/doc/man/man3/crypto_hidden_to_curve.3monocypher new file mode 120000 index 0000000..3717a86 --- /dev/null +++ b/doc/man/man3/crypto_hidden_to_curve.3monocypher @@ -0,0 +1 @@ +crypto_curve_to_hidden.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_x25519_dangerous_fast.3monocypher b/doc/man/man3/crypto_x25519_dangerous_fast.3monocypher new file mode 100644 index 0000000..21dded2 --- /dev/null +++ b/doc/man/man3/crypto_x25519_dangerous_fast.3monocypher @@ -0,0 +1,135 @@ +.\" 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 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 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 March 24, 2020 +.Dt CRYPTO_X25519_DANGEROUS_FAST 3monocypher +.Os +.Sh NAME +.Nm crypto_x25519_dangerous_fast , +.Nm crypto_x25519_dangerous_small +.Nd generation of Curve25519 points including low-order points +.Sh SYNOPSIS +.In monocypher.h +.Ft void +.Fo crypto_hidden_to_curve_fast +.Fa "uint8_t pk[32]" +.Fa "const uint8_t sk[32]" +.Fc +.Ft void +.Fo crypto_hidden_to_curve_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_key_exchange 3monocypher +or +.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. +but do the same with different code size and memory characteristics: +.Fn crypto_x25519_dangerous_fast +uses multiple large temporary variables and uses 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_dangerous_small +yields the same result, but does so using less time and memory at a +large performance penalty compared to +.Fn crypto_x25519_dangerous_fast . +.Pp +The resulting public keys +.Em may +be used with +.Xr crypto_x25519 3monocypher +and +.Xr crypto_key_exchange 3monocypher , +which clear the cofactor, +but are dangerous for other uses because they contain low-order points, +and may trip up other implementations of X25519. +.Sh RETURN VALUES +These functions have no return value. +They cannot fail. +.Sh SEE ALSO +.Xr crypto_curve_to_hidden 3monocypher , +.Xr crypto_key_exchange 3monocypher , +.Xr crypto_x25519 3monocypher , +.Xr intro 3monocypher +.Sh HISTORY +The +.Fn crypto_x25519_dangerous_fast +and +.Fn crypto_x25519_dangerous_small +functions first appeared in Monocypher 3.1.0. +.Sh IMPLEMENTATION DETAILS +The slow variant is approximately an entire 1.8 times slower than the +fast variant. +When considering that, on average, two calls to this function will be +required for obtaining a valid keypair for +.Xr crypto_curve_to_hidden 3monocypher , +this adds up to an +.Em average +effective slowdown for key pair generation of a factor of 3.6. diff --git a/doc/man/man3/crypto_x25519_dangerous_small.3monocypher b/doc/man/man3/crypto_x25519_dangerous_small.3monocypher new file mode 120000 index 0000000..f4390db --- /dev/null +++ b/doc/man/man3/crypto_x25519_dangerous_small.3monocypher @@ -0,0 +1 @@ +crypto_x25519_dangerous_fast.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_x25519_inverse.3monocypher b/doc/man/man3/crypto_x25519_inverse.3monocypher new file mode 100644 index 0000000..862cbd1 --- /dev/null +++ b/doc/man/man3/crypto_x25519_inverse.3monocypher @@ -0,0 +1,102 @@ +.\" 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 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 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 March 24, 2020 +.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" +.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_key_exchange 3monocypher +or +.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. +This value's cofactor is cleared first, +the multiplicative inverse (modulo the curve order) has its cofactor +cleared and 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/intro.3monocypher b/doc/man/man3/intro.3monocypher index 1dd1077..b9054a4 100644 --- a/doc/man/man3/intro.3monocypher +++ b/doc/man/man3/intro.3monocypher @@ -50,7 +50,7 @@ .\" with this software. If not, see .\" .\" -.Dd February 5, 2020 +.Dd March 24, 2020 .Dt INTRO 3MONOCYPHER .Os .Sh NAME @@ -101,6 +101,11 @@ implements X25519, an elliptic curve Diffie Hellman key exchange algorithm based on Curve25519. X25519 derives a shared secret from two private/public key pairs. It is fast, simple, and relatively easy to implement securely. +.Pp +For specialized protocols that require indistinguishability from random +noise, +.Xr crypto_curve_to_hidden 3monocypher +gives the option to disguise X25519 public keys as random noise. .Ss Public key signatures .Xr crypto_sign 3monocypher and @@ -151,7 +156,10 @@ and .Xr crypto_check_init 3monocypher , .Xr crypto_check_init_custom_hash 3monocypher , .Xr crypto_check_update 3monocypher , +.Xr crypto_curve_to_hidden 3monocypher , .Xr crypto_hchacha20 3monocypher , +.Xr crypto_hidden_key_pair 3monocypher , +.Xr crypto_hidden_to_curve 3monocypher , .Xr crypto_ietf_chacha20 3monocypher , .Xr crypto_ietf_chacha20_ctr 3monocypher , .Xr crypto_key_exchange 3monocypher , @@ -176,6 +184,9 @@ and .Xr crypto_verify64 3monocypher , .Xr crypto_wipe 3monocypher , .Xr crypto_x25519 3monocypher , +.Xr crypto_x25519_dangerous_fast 3monocypher , +.Xr crypto_x25519_dangerous_small 3monocypher , +.Xr crypto_x25519_inverse 3monocypher , .Xr crypto_x25519_public_key 3monocypher , .Xr crypto_xchacha20 3monocypher , .Xr crypto_xchacha20_ctr 3monocypher