EVP: Make the SIGNATURE implementation leaner
[openssl.git] / 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 EVP_PKEY_verify_init_ex() was added in OpenSSL 3.0.
97 All other functions were added in OpenSSL 1.0.0.
98
99 =head1 COPYRIGHT
100
101 Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
102
103 Licensed under the Apache License 2.0 (the "License").  You may not use
104 this file except in compliance with the License.  You can obtain a copy
105 in the file LICENSE in the source distribution or at
106 L<https://www.openssl.org/source/license.html>.
107
108 =cut