1.\" $OpenBSD: X25519.3,v 1.5 2019/08/19 13:08:26 schwarze Exp $ 2.\" contains some text from: BoringSSL curve25519.h, curve25519.c 3.\" content also checked up to: OpenSSL f929439f Mar 15 12:19:16 2018 +0000 4.\" 5.\" Copyright (c) 2015 Google Inc. 6.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org> 7.\" 8.\" Permission to use, copy, modify, and/or distribute this software for any 9.\" purpose with or without fee is hereby granted, provided that the above 10.\" copyright notice and this permission notice appear in all copies. 11.\" 12.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES 13.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 14.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR 15.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 16.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 17.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 18.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 19.\" 20.Dd $Mdocdate: August 19 2019 $ 21.Dt X25519 3 22.Os 23.Sh NAME 24.Nm X25519 , 25.Nm X25519_keypair 26.Nd Elliptic Curve Diffie-Hellman primitive based on Curve25519 27.Sh SYNOPSIS 28.In openssl/curve25519.h 29.Ft int 30.Fo X25519 31.Fa "uint8_t out_shared_key[X25519_KEY_LENGTH]" 32.Fa "const uint8_t private_key[X25519_KEY_LENGTH]" 33.Fa "const uint8_t peer_public_value[X25519_KEY_LENGTH]" 34.Fc 35.Ft void 36.Fo X25519_keypair 37.Fa "uint8_t out_public_value[X25519_KEY_LENGTH]" 38.Fa "uint8_t out_private_key[X25519_KEY_LENGTH]" 39.Fc 40.Sh DESCRIPTION 41Curve25519 is an elliptic curve over a prime field specified in RFC 7748. 42The prime field is defined by the prime number 2^255 - 19. 43.Pp 44.Fn X25519 45is the Diffie-Hellman primitive built from Curve25519 as described 46in RFC 7748 section 5. 47Section 6.1 describes the intended use in an Elliptic Curve Diffie-Hellman 48(ECDH) protocol. 49.Pp 50.Fn X25519 51writes a shared key to 52.Fa out_shared_key 53that is calculated from the given 54.Fa private_key 55and the 56.Fa peer_public_value 57by scalar multiplication. 58Do not use the shared key directly, rather use a key derivation 59function and also include the two public values as inputs. 60.Pp 61.Fn X25519_keypair 62sets 63.Fa out_public_value 64and 65.Fa out_private_key 66to a freshly generated public/private key pair. 67First, the 68.Fa out_private_key 69is generated with 70.Xr arc4random_buf 3 . 71Then, the opposite of the masking described in RFC 7748 section 5 72is applied to it to make sure that the generated private key is never 73correctly masked. 74The purpose is to cause incorrect implementations on the peer side 75to consistently fail. 76Correct implementations will decode the key correctly even when it is 77not correctly masked. 78Finally, the 79.Fa out_public_value 80is calculated from the 81.Fa out_private_key 82by multiplying it with the Montgomery base point 83.Vt uint8_t u[32] No = Brq 9 . 84.Pp 85The size of a public and private key is 86.Dv X25519_KEY_LENGTH No = 32 87bytes each. 88.Sh RETURN VALUES 89.Fn X25519 90returns 1 on success or 0 on error. 91Failure can occur when the input is a point of small order. 92.Sh SEE ALSO 93.Xr ECDH_compute_key 3 94.Rs 95.%A D. J. Bernstein 96.%R A state-of-the-art Diffie-Hellman function:\ 97 How do I use Curve25519 in my own software? 98.%U http://cr.yp.to/ecdh.html 99.Re 100.Sh STANDARDS 101RFC 7748: Elliptic Curves for Security 102