X25519(3) | Library Functions Manual | X25519(3) |

`X25519`

, `X25519_keypair`

—
Elliptic Curve Diffie-Hellman primitive based on
Curve25519

`#include <openssl/curve25519.h>`

`int`

`X25519`

(`uint8_t
out_shared_key[X25519_KEY_LENGTH]`, `const uint8_t
private_key[X25519_KEY_LENGTH]`, `const uint8_t
peer_public_value[X25519_KEY_LENGTH]`);

`void`

`X25519_keypair`

(`uint8_t
out_public_value[X25519_KEY_LENGTH]`, `uint8_t
out_private_key[X25519_KEY_LENGTH]`);

`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.

`X25519`

() writes a shared key to
`out_shared_key` that is calculated from the given
`private_key` and the
`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.

`X25519_keypair`

() sets
`out_public_value` and
`out_private_key` to a freshly generated public/private
key pair. First, the `out_private_key` is generated with
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
`out_public_value` is calculated from the
`out_private_key` by multiplying it with the Montgomery
base point `uint8_t u[32]` =
{9}.

The size of a public and private key is
`X25519_KEY_LENGTH`

= 32 bytes
each.

`X25519`

() returns 1 on success or 0 on error. Failure can
occur when the input is a point of small order.
D. J. Bernstein, A state-of-the-art Diffie-Hellman function: How do I use Curve25519 in my own software?, http://cr.yp.to/ecdh.html.

August 10, 2018 | OpenBSD-current |