## NAME

`X25519`

,
`X25519_keypair`

—
Elliptic Curve Diffie-Hellman primitive
based on Curve25519

## SYNOPSIS

```
#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]`);

## DESCRIPTION

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.

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

## RETURN VALUES

`X25519`

() returns 1 on success or 0 on
error. Failure can occur when the input is a point of small order.

## SEE ALSO

D. J. Bernstein, A state-of-the-art Diffie-Hellman function: How do I use Curve25519 in my own software?, https://cr.yp.to/ecdh.html.

## STANDARDS

RFC 7748: Elliptic Curves for Security