crypto/openssl/doc/crypto/EVP_PKEY_derive.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret.
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/evp.h>
  10
  11  int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
  12  int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
  13  int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
  14
  15 =head1 DESCRIPTION
  16
  17 The EVP_PKEY_derive_init() function initializes a public key algorithm
  18 context using key B<pkey> for shared secret derivation.
  19
  20 The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally
  21 be a public key.
  22
  23 The EVP_PKEY_derive() derives a shared secret using B<ctx>.
  24 If B<key> is B<NULL> then the maximum size of the output buffer is written to
  25 the B<keylen> parameter. If B<key> is not B<NULL> then before the call the
  26 B<keylen> parameter should contain the length of the B<key> buffer, if the call
  27 is successful the shared secret is written to B<key> and the amount of data
  28 written to B<keylen>.
  29
  30 =head1 NOTES
  31
  32 After the call to EVP_PKEY_derive_init() algorithm specific control
  33 operations can be performed to set any appropriate parameters for the
  34 operation.
  35
  36 The function EVP_PKEY_derive() can be called more than once on the same
  37 context if several operations are performed using the same parameters.
  38
  39 =head1 RETURN VALUES
  40
  41 EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0
  42 or a negative value for failure. In particular a return value of -2
  43 indicates the operation is not supported by the public key algorithm.
  44
  45 =head1 EXAMPLE
  46
  47 Derive shared secret (for example DH or EC keys):
  48
  49  #include <openssl/evp.h>
  50  #include <openssl/rsa.h>
  51
  52  EVP_PKEY_CTX *ctx;
  53  unsigned char *skey;
  54  size_t skeylen;
  55  EVP_PKEY *pkey, *peerkey;
  56  /* NB: assumes pkey, peerkey have been already set up */
  57
  58  ctx = EVP_PKEY_CTX_new(pkey);
  59  if (!ctx)
  60         /* Error occurred */
  61  if (EVP_PKEY_derive_init(ctx) <= 0)
  62         /* Error */
  63  if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0)
  64         /* Error */
  65
  66  /* Determine buffer length */
  67  if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0)
  68         /* Error */
  69
  70  skey = OPENSSL_malloc(skeylen);
  71
  72  if (!skey)
  73         /* malloc failure */
  74
  75  if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0)
  76         /* Error */
  77
  78  /* Shared secret is skey bytes written to buffer skey */
  79
  80 =head1 SEE ALSO
  81
  82 L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
  83 L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
  84 L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
  85 L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
  86 L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
  87 L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
  88
  89 =head1 HISTORY
  90
  91 These functions were first added to OpenSSL 1.0.0.
  92
  93 =cut