diff options
| -rw-r--r-- | lib/libcrypto/man/X25519.3 | 183 |
1 files changed, 85 insertions, 98 deletions
diff --git a/lib/libcrypto/man/X25519.3 b/lib/libcrypto/man/X25519.3 index 6292d33ff5b..b2812149b1c 100644 --- a/lib/libcrypto/man/X25519.3 +++ b/lib/libcrypto/man/X25519.3 @@ -1,112 +1,99 @@ -.\" $OpenBSD: X25519.3,v 1.2 2018/03/30 01:03:51 schwarze Exp $ -.\" full merge up to: OpenSSL man7/X25519 69687aa8 Mar 28 23:57:28 2017 +0200 -.\" selective merge up to: OpenSSL f929439f Mar 15 12:19:16 2018 +0000 +.\" $OpenBSD: X25519.3,v 1.3 2018/03/30 18:38:22 schwarze Exp $ +.\" contains some text from: BoringSSL curve25519.h, curve25519.c +.\" content also checked up to: OpenSSL f929439f Mar 15 12:19:16 2018 +0000 .\" -.\" This file was written by Dr. Stephen Henson <steve@openssl.org> -.\" and Matt Caswell <matt@openssl.org>. -.\" Copyright (c) 2017, 2018 The OpenSSL Project. All rights reserved. +.\" Copyright (c) 2015 Google Inc. +.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org> .\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. .\" -.\" 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. -.\" -.\" 3. All advertising materials mentioning features or use of this -.\" software must display the following acknowledgment: -.\" "This product includes software developed by the OpenSSL Project -.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" -.\" -.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to -.\" endorse or promote products derived from this software without -.\" prior written permission. For written permission, please contact -.\" openssl-core@openssl.org. -.\" -.\" 5. Products derived from this software may not be called "OpenSSL" -.\" nor may "OpenSSL" appear in their names without prior written -.\" permission of the OpenSSL Project. -.\" -.\" 6. Redistributions of any form whatsoever must retain the following -.\" acknowledgment: -.\" "This product includes software developed by the OpenSSL Project -.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY -.\" EXPRESSED 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 OpenSSL PROJECT OR -.\" ITS 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. +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd $Mdocdate: March 30 2018 $ .Dt X25519 3 .Os .Sh NAME -.Nm X25519 -.Nd EVP_PKEY X25519 support +.Nm X25519 , +.Nm X25519_keypair +.Nd Elliptic Curve Diffie-Hellman primitive based on Curve25519 +.Sh SYNOPSIS +.Ft int +.Fo X25519 +.Fa "uint8_t out_shared_key[X25519_KEY_LENGTH]" +.Fa "const uint8_t private_key[X25519_KEY_LENGTH]" +.Fa "const uint8_t peer_public_value[X25519_KEY_LENGTH]" +.Fc +.Ft void +.Fo X25519_keypair +.Fa "uint8_t out_public_value[X25519_KEY_LENGTH]" +.Fa "uint8_t out_private_key[X25519_KEY_LENGTH]" +.Fc .Sh DESCRIPTION -The -.Nm -.Vt EVP_PKEY -implementation supports key generation and key derivation using X25519. -It has associated private and public key formats compatible with -draft-ietf-curdle-pkix-03. -.Pp -No additional parameters can be set during key generation. -.Pp -The peer public key must be set using -.Xr EVP_PKEY_derive_set_peer 3 -when performing key derivation. -.Pp -A context for the -.Nm -algorithm can be obtained by calling: +Curve25519 is an elliptic curve over a prime field specified in RFC 7748. +The prime field is defined by the prime number 2^255 - 19. .Pp -.Dl EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(NID_X25519, NULL); +.Fn X25519 +is the Diffie-Hellman primitive built from Curve25519 as described +in RFC 7748 section 5. +Section 6.1 describes the intended use in an Elliptic Curve Diffie-Hellman +(ECDH) protocol. .Pp -X25519 private keys can be loaded from a PKCS#8 private key file using -.Xr PEM_read_bio_PrivateKey 3 -or similar functions. -Setting a private key also sets the associated public key. +.Fn X25519 +writes a shared key to +.Fa out_shared_key +that is calculated from the given +.Fa private_key +and the +.Fa peer_public_value +by scalar multiplication. +Do not use the shared key directly, rather use a key derivation +function and also include the two public values as inputs. .Pp -X25519 public keys can be loaded from a SubjectPublicKeyInfo -structure in a PEM file using -.Xr PEM_read_bio_PUBKEY 3 -or similar functions. -.Sh EXAMPLES -Generate an -.Nm -private key and write it to standard output in PEM format: -.Bd -literal -#include <openssl/evp.h> -#include <openssl/pem.h> - -EVP_PKEY *pkey = NULL; -EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(NID_X25519, NULL); -EVP_PKEY_keygen_init(pctx); -EVP_PKEY_keygen(pctx, &pkey); -EVP_PKEY_CTX_free(pctx); -PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL); -.Ed +.Fn X25519_keypair +sets +.Fa out_public_value +and +.Fa out_private_key +to a freshly generated public/private key pair. +First, the +.Fa out_private_key +is generated with +.Xr arc4random_buf 3 . +Then, the opposite of the masking described in RFC 7748 section 5 +is applied to it to make sure that the generated private key is never +correctly masked. +The purpose is to cause incorrect implementations on the peer side +to consistently fail. +Correct implementations will decode the key correctly even when it is +not correctly masked. +Finally, the +.Fa out_public_value +is calculated from the +.Fa out_private_key +by multiplying it with the Montgomery base point +.Vt uint8_t u[32] No = Brq 9 . .Pp -The key derivation example in -.Xr EVP_PKEY_derive 3 -can be used with -.Nm . +The size of a public and private key is +.Dv X25519_KEY_LENGTH No = 32 +bytes each. +.Sh RETURN VALUES +.Fn X25519 +returns 1 on success or 0 on error. +Failure can occur when the input is a point of small order. .Sh SEE ALSO -.Xr EVP_PKEY_CTX_new 3 , -.Xr EVP_PKEY_derive 3 , -.Xr EVP_PKEY_keygen 3 , -.Xr PEM_read_bio_PrivateKey 3 +.Rs +.%A D. J. Bernstein +.%R A state-of-the-art Diffie-Hellman function:\ + How do I use Curve25519 in my own software? +.%U http://cr.yp.to/ecdh.html +.Re +.Sh STANDARDS +RFC 7748: Elliptic Curves for Security |