Reuse already defined macros
[openssl.git] / doc / man7 / X25519.pod
1 =pod
2
3 =head1 NAME
4
5 X25519,
6 X448
7 - EVP_PKEY X25519 and X448 support
8
9 =head1 DESCRIPTION
10
11 The B<X25519> and B<X448> EVP_PKEY implementation supports key generation and
12 key derivation using B<X25519> and B<X448>. It has associated private and public
13 key formats compatible with draft-ietf-curdle-pkix-03.
14
15 No additional parameters can be set during key generation.
16
17 The peer public key must be set using EVP_PKEY_derive_set_peer() when
18 performing key derivation.
19
20 =head1 NOTES
21
22 A context for the B<X25519> algorithm can be obtained by calling:
23
24  EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X25519, NULL);
25
26 For the B<X448> algorithm a context can be obtained by calling:
27
28  EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X448, NULL);
29
30 X25519 or X448 private keys can be set directly using
31 L<EVP_PKEY_new_raw_private_key(3)> or loaded from a PKCS#8 private key file
32 using L<PEM_read_bio_PrivateKey(3)> (or similar function). Completely new keys
33 can also be generated (see the example below). Setting a private key also sets
34 the associated public key.
35
36 X25519 or X448 public keys can be set directly using
37 L<EVP_PKEY_new_raw_public_key(3)> or loaded from a SubjectPublicKeyInfo
38 structure in a PEM file using L<PEM_read_bio_PUBKEY(3)> (or similar function).
39
40 =head1 EXAMPLE
41
42 This example generates an B<X25519> private key and writes it to standard
43 output in PEM format:
44
45  #include <openssl/evp.h>
46  #include <openssl/pem.h>
47  ...
48  EVP_PKEY *pkey = NULL;
49  EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X25519, NULL);
50  EVP_PKEY_keygen_init(pctx);
51  EVP_PKEY_keygen(pctx, &pkey);
52  EVP_PKEY_CTX_free(pctx);
53  PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL);
54
55 The key derivation example in L<EVP_PKEY_derive(3)> can be used with
56 B<X25519> and B<X448>.
57
58 =head1 SEE ALSO
59
60 L<EVP_PKEY_CTX_new(3)>,
61 L<EVP_PKEY_keygen(3)>,
62 L<EVP_PKEY_derive(3)>,
63 L<EVP_PKEY_derive_set_peer(3)>
64
65 =head1 COPYRIGHT
66
67 Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
68
69 Licensed under the Apache License 2.0 (the "License").  You may not use
70 this file except in compliance with the License.  You can obtain a copy
71 in the file LICENSE in the source distribution or at
72 L<https://www.openssl.org/source/license.html>.
73
74 =cut