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 OpenSSL license (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