Add public API docs for newly added EVP_SIGNATURE related functions

[openssl.git] / doc / man3 / EVP_PKEY_derive.pod

diff --git a/doc/man3/EVP_PKEY_derive.pod b/doc/man3/EVP_PKEY_derive.pod
index f70a0b8d9b888b525f26f2c57b9273064b3cca9b..832498ba76fde57711411b47af1b79f752d94e62 100644 (file)
--- a/doc/man3/EVP_PKEY_derive.pod
+++ b/doc/man3/EVP_PKEY_derive.pod
@@ -2,20 +2,33 @@
 
 =head1 NAME
 
-EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret
+EVP_PKEY_derive_init, EVP_PKEY_derive_init_ex, EVP_PKEY_derive_set_peer,
+EVP_PKEY_derive - derive public key algorithm shared secret
 
 =head1 SYNOPSIS
 
  #include <openssl/evp.h>
 
+ int EVP_PKEY_derive_init_ex(EVP_PKEY_CTX *ctx, EVP_KEYEXCH *exchange);
  int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
  int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
  int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_derive_init() function initializes a public key algorithm
-context using key B<pkey> for shared secret derivation.
+The EVP_PKEY_derive_init_ex() function initializes a public key algorithm
+context for shared secret derivation using the key exchange algorithm
+B<exchange>.
+The key exchange algorithm B<exchange> should be fetched using a call to
+L<EVP_KEYEXCH_fetch(3)>.
+The EVP_PKEY object associated with B<ctx> must be compatible with that
+algorithm.
+B<exchange> may be NULL in which case the EVP_KEYEXCH algorithm is fetched
+implicitly based on the type of EVP_PKEY associated with B<ctx>.
+See L<provider(7)/Implicit fetch> for more information about implict fetches.
+
+The EVP_PKEY_derive_init() function is the same as EVP_PKEY_derive_init_ex()
+except that the EVP_KEYEXCH algorithm is always implicitly fetched.
 
 The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally
 be a public key.
@@ -29,20 +42,21 @@ written to B<keylen>.
 
 =head1 NOTES
 
-After the call to EVP_PKEY_derive_init() algorithm specific control
-operations can be performed to set any appropriate parameters for the
-operation.
+After the call to EVP_PKEY_derive_init() or EVP_PKEY_derive_init_ex() algorithm
+specific control operations can be performed to set any appropriate parameters
+for the operation.
 
 The function EVP_PKEY_derive() can be called more than once on the same
 context if several operations are performed using the same parameters.
 
 =head1 RETURN VALUES
 
-EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0
-or a negative value for failure. In particular a return value of -2
-indicates the operation is not supported by the public key algorithm.
+EVP_PKEY_derive_init_ex(), EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1
+for success and 0 or a negative value for failure.
+In particular a return value of -2 indicates the operation is not supported by
+the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Derive shared secret (for example DH or EC keys):
 
@@ -50,30 +64,31 @@ Derive shared secret (for example DH or EC keys):
  #include <openssl/rsa.h>
 
  EVP_PKEY_CTX *ctx;
+ ENGINE *eng;
  unsigned char *skey;
  size_t skeylen;
  EVP_PKEY *pkey, *peerkey;
- /* NB: assumes pkey, peerkey have been already set up */
+ /* NB: assumes pkey, eng, peerkey have been already set up */
 
- ctx = EVP_PKEY_CTX_new(pkey);
+ ctx = EVP_PKEY_CTX_new(pkey, eng);
  if (!ctx)
-        /* Error occurred */
+     /* Error occurred */
  if (EVP_PKEY_derive_init(ctx) <= 0)
-        /* Error */
+     /* Error */
  if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0)
-        /* Error */
+     /* Error */
 
  /* Determine buffer length */
  if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0)
-        /* Error */
+     /* Error */
 
  skey = OPENSSL_malloc(skeylen);
 
  if (!skey)
-        /* malloc failure */
+     /* malloc failure */
 
  if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0)
-        /* Error */
+     /* Error */
 
  /* Shared secret is skey bytes written to buffer skey */
 
@@ -85,16 +100,18 @@ L<EVP_PKEY_decrypt(3)>,
 L<EVP_PKEY_sign(3)>,
 L<EVP_PKEY_verify(3)>,
 L<EVP_PKEY_verify_recover(3)>,
+L<EVP_KEYEXCH_fetch(3)>
 
 =head1 HISTORY
 
-These functions were first added to OpenSSL 1.0.0.
+These functions were added in OpenSSL 1.0.0. The EVP_PKEY_derive_init_ex()
+function was added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.