doc/man3/EVP_PKEY_verify.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY_verify_init, EVP_PKEY_verify
   6 - signature verification using a public key algorithm
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/evp.h>
  11
  12  int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx);
  13  int EVP_PKEY_verify(EVP_PKEY_CTX *ctx,
  14                      const unsigned char *sig, size_t siglen,
  15                      const unsigned char *tbs, size_t tbslen);
  16
  17 =head1 DESCRIPTION
  18
  19 EVP_PKEY_verify_init() initializes a public key algorithm context I<ctx> for
  20 signing using the algorithm given when the context was created
  21 using L<EVP_PKEY_CTX_new(3)> or variants thereof.  The algorithm is used to
  22 fetch a B<EVP_SIGNATURE> method implicitly, see L<provider(7)/Implicit fetch>
  23 for more information about implict fetches.
  24
  25 The EVP_PKEY_verify() function performs a public key verification operation
  26 using I<ctx>. The signature is specified using the I<sig> and
  27 I<siglen> parameters. The verified data (i.e. the data believed originally
  28 signed) is specified using the I<tbs> and I<tbslen> parameters.
  29
  30 =head1 NOTES
  31
  32 After the call to EVP_PKEY_verify_init() algorithm specific control
  33 operations can be performed to set any appropriate parameters for the
  34 operation.
  35
  36 The function EVP_PKEY_verify() 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_verify_init() and EVP_PKEY_verify() return 1 if the verification was
  42 successful and 0 if it failed. Unlike other functions the return value 0 from
  43 EVP_PKEY_verify() only indicates that the signature did not verify
  44 successfully (that is tbs did not match the original data or the signature was
  45 of invalid form) it is not an indication of a more serious error.
  46
  47 A negative value indicates an error other that signature verification failure.
  48 In particular a return value of -2 indicates the operation is not supported by
  49 the public key algorithm.
  50
  51 =head1 EXAMPLES
  52
  53 Verify signature using PKCS#1 and SHA256 digest:
  54
  55  #include <openssl/evp.h>
  56  #include <openssl/rsa.h>
  57
  58  EVP_PKEY_CTX *ctx;
  59  unsigned char *md, *sig;
  60  size_t mdlen, siglen;
  61  EVP_PKEY *verify_key;
  62
  63  /*
  64   * NB: assumes verify_key, sig, siglen md and mdlen are already set up
  65   * and that verify_key is an RSA public key
  66   */
  67  ctx = EVP_PKEY_CTX_new(verify_key, NULL /* no engine */);
  68  if (!ctx)
  69      /* Error occurred */
  70  if (EVP_PKEY_verify_init(ctx) <= 0)
  71      /* Error */
  72  if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
  73      /* Error */
  74  if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
  75      /* Error */
  76
  77  /* Perform operation */
  78  ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen);
  79
  80  /*
  81   * ret == 1 indicates success, 0 verify failure and < 0 for some
  82   * other error.
  83   */
  84
  85 =head1 SEE ALSO
  86
  87 L<EVP_PKEY_CTX_new(3)>,
  88 L<EVP_PKEY_encrypt(3)>,
  89 L<EVP_PKEY_decrypt(3)>,
  90 L<EVP_PKEY_sign(3)>,
  91 L<EVP_PKEY_verify_recover(3)>,
  92 L<EVP_PKEY_derive(3)>
  93
  94 =head1 HISTORY
  95
  96 These functions were added in OpenSSL 1.0.0.
  97
  98 =head1 COPYRIGHT
  99
 100 Copyright 2006-2020 The OpenSSL Project Authors. All Rights Reserved.
 101
 102 Licensed under the Apache License 2.0 (the "License").  You may not use
 103 this file except in compliance with the License.  You can obtain a copy
 104 in the file LICENSE in the source distribution or at
 105 L<https://www.openssl.org/source/license.html>.
 106
 107 =cut