Change EVP_PKEY_CTX_new_provided() to take a library context too.

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

diff --git a/doc/man3/EVP_PKEY_verify_recover.pod b/doc/man3/EVP_PKEY_verify_recover.pod
index beb5b614a9b0f446f8ce52847ba0478999e0f7f9..737c372dd19774885c150143275d1ef462b53098 100644 (file)
--- a/doc/man3/EVP_PKEY_verify_recover.pod
+++ b/doc/man3/EVP_PKEY_verify_recover.pod
@@ -2,21 +2,36 @@
 
 =head1 NAME
 
-EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using a public key algorithm
+EVP_PKEY_verify_recover_init_ex, EVP_PKEY_verify_recover_init,
+EVP_PKEY_verify_recover - recover signature using a public key algorithm
 
 =head1 SYNOPSIS
 
  #include <openssl/evp.h>
 
+ int EVP_PKEY_verify_recover_init_ex(EVP_PKEY_CTX *ctx,
+                                     EVP_SIGNATURE *signature);
  int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx);
  int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx,
-                        unsigned char *rout, size_t *routlen,
-                        const unsigned char *sig, size_t siglen);
+                             unsigned char *rout, size_t *routlen,
+                             const unsigned char *sig, size_t siglen);
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_verify_recover_init() function initializes a public key algorithm
-context using key B<pkey> for a verify recover operation.
+The EVP_PKEY_verify_recover_init_ex() function initializes a public key
+algorithm context for performing signature signed data recovery using the
+signature algorithm B<signature>.
+The signature algorithm B<signature> should be fetched using a call to
+L<EVP_SIGNATURE_fetch(3)>.
+The EVP_PKEY object associated with B<ctx> must be compatible with that
+algorithm.
+B<signature> may be NULL in which case the EVP_SIGNATURE 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_verify_recover_init() function is the same as
+EVP_PKEY_verify_recover_init_ex() except that the EVP_SIGNATURE algorithm is
+always implicitly fetched.
 
 The EVP_PKEY_verify_recover() function recovers signed data
 using B<ctx>. The signature is specified using the B<sig> and
@@ -49,7 +64,7 @@ EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() return 1 for succes
 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
 
 Recover digest originally signed using PKCS#1 and SHA256 digest:
 
@@ -60,11 +75,12 @@ Recover digest originally signed using PKCS#1 and SHA256 digest:
  unsigned char *rout, *sig;
  size_t routlen, siglen;
  EVP_PKEY *verify_key;
+
  /*
   * NB: assumes verify_key, sig and siglen are already set up
   * and that verify_key is an RSA public key
   */
- ctx = EVP_PKEY_CTX_new(verify_key);
+ ctx = EVP_PKEY_CTX_new(verify_key, NULL /* no engine */);
  if (!ctx)
      /* Error occurred */
  if (EVP_PKEY_verify_recover_init(ctx) <= 0)
@@ -99,13 +115,13 @@ L<EVP_PKEY_derive(3)>
 
 =head1 HISTORY
 
-These functions were first added to OpenSSL 1.0.0.
+These functions were added in OpenSSL 1.0.0.
 
 =head1 COPYRIGHT
 
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2013-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>.