doc/man3/EVP_PKEY_verify.pod

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