EVP: Make the SIGNATURE implementation leaner
[openssl.git] / doc / man3 / EVP_PKEY_verify.pod
index bf122c7..ed63cda 100644 (file)
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public key algorithm
+EVP_PKEY_verify_init, EVP_PKEY_verify
+- signature verification using a public key algorithm
 
 =head1 SYNOPSIS
 
@@ -10,18 +11,21 @@ EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public ke
 
  int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx);
  int EVP_PKEY_verify(EVP_PKEY_CTX *ctx,
-                        const unsigned char *sig, size_t siglen,
-                        const unsigned char *tbs, size_t tbslen);
+                     const unsigned char *sig, size_t siglen,
+                     const unsigned char *tbs, size_t tbslen);
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_verify_init() function initializes a public key algorithm
-context using key B<pkey> for a signature verification operation.
+EVP_PKEY_verify_init() initializes a public key algorithm context I<ctx> for
+signing using the algorithm given when the context was created
+using L<EVP_PKEY_CTX_new(3)> or variants thereof.  The algorithm is used to
+fetch a B<EVP_SIGNATURE> method implicitly, see L<provider(7)/Implicit fetch>
+for more information about implict fetches.
 
 The EVP_PKEY_verify() function performs a public key verification operation
-using B<ctx>. The signature is specified using the B<sig> and
-B<siglen> parameters. The verified data (i.e. the data believed originally
-signed) is specified using the B<tbs> and B<tbslen> parameters.
+using I<ctx>. The signature is specified using the I<sig> and
+I<siglen> parameters. The verified data (i.e. the data believed originally
+signed) is specified using the I<tbs> and I<tbslen> parameters.
 
 =head1 NOTES
 
@@ -36,7 +40,7 @@ context if several operations are performed using the same parameters.
 
 EVP_PKEY_verify_init() and EVP_PKEY_verify() return 1 if the verification was
 successful and 0 if it failed. Unlike other functions the return value 0 from
-EVP_PKEY_verify() only indicates that the signature did not not verify
+EVP_PKEY_verify() only indicates that the signature did not verify
 successfully (that is tbs did not match the original data or the signature was
 of invalid form) it is not an indication of a more serious error.
 
@@ -44,7 +48,7 @@ A negative value indicates an error other that signature verification failure.
 In particular a return value of -2 indicates the operation is not supported by
 the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Verify signature using PKCS#1 and SHA256 digest:
 
@@ -55,11 +59,12 @@ Verify signature using PKCS#1 and SHA256 digest:
  unsigned char *md, *sig;
  size_t mdlen, siglen;
  EVP_PKEY *verify_key;
+
  /*
   * NB: assumes verify_key, sig, siglen md and mdlen 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_init(ctx) <= 0)
@@ -88,13 +93,14 @@ L<EVP_PKEY_derive(3)>
 
 =head1 HISTORY
 
-These functions were first added to OpenSSL 1.0.0.
+EVP_PKEY_verify_init_ex() was added in OpenSSL 3.0.
+All other functions were added in OpenSSL 1.0.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>.