Sortix nightly manual
This manual documents Sortix nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
X25519(3) | Library Functions Manual | X25519(3) |
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
ECDH_compute_key(3) 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 SecurityFebruary 18, 2022 | Debian |