1=pod 2 3=head1 NAME 4 5EVP_PKEY_verify_init, EVP_PKEY_verify_init_ex, EVP_PKEY_verify_init_ex2, 6EVP_PKEY_verify, EVP_PKEY_verify_message_init, EVP_PKEY_verify_message_update, 7EVP_PKEY_verify_message_final, EVP_PKEY_CTX_set_signature - signature 8verification using a public key algorithm 9 10=head1 SYNOPSIS 11 12 #include <openssl/evp.h> 13 14 int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx); 15 int EVP_PKEY_verify_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); 16 int EVP_PKEY_verify_init_ex2(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo, 17 const OSSL_PARAM params[]); 18 int EVP_PKEY_verify_message_init(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo, 19 const OSSL_PARAM params[]); 20 int EVP_PKEY_CTX_set_signature(EVP_PKEY_CTX *pctx, 21 const unsigned char *sig, size_t siglen); 22 int EVP_PKEY_verify_message_update(EVP_PKEY_CTX *ctx, 23 unsigned char *in, size_t inlen); 24 int EVP_PKEY_verify_message_final(EVP_PKEY_CTX *ctx); 25 int EVP_PKEY_verify(EVP_PKEY_CTX *ctx, 26 const unsigned char *sig, size_t siglen, 27 const unsigned char *tbs, size_t tbslen); 28 29=head1 DESCRIPTION 30 31EVP_PKEY_verify_init() initializes a public key algorithm context I<ctx> for 32verification using the algorithm given when the context was created 33using L<EVP_PKEY_CTX_new(3)> or variants thereof. The algorithm is used to 34fetch a B<EVP_SIGNATURE> method implicitly, see L<provider(7)/Implicit fetch> 35for more information about implicit fetches. 36 37EVP_PKEY_verify_init_ex() is the same as EVP_PKEY_verify_init() but additionally 38sets the passed parameters I<params> on the context before returning. 39 40EVP_PKEY_verify_init_ex2() is the same as EVP_PKEY_verify_init_ex(), but works 41with an explicitly fetched B<EVP_SIGNATURE> I<algo>. 42A context I<ctx> without a pre-loaded key cannot be used with this function. 43Depending on what algorithm was fetched, certain details revolving around the 44treatment of the input to EVP_PKEY_verify() may be pre-determined, and in that 45case, those details may normally not be changed. 46See L</NOTES> below for a deeper explanation. 47 48EVP_PKEY_verify_message_init() initializes a public key algorithm context 49I<ctx> for verifying an unlimited size message using the algorithm given by 50I<algo> and the key given through L<EVP_PKEY_CTX_new(3)> or 51L<EVP_PKEY_CTX_new_from_pkey(3)>. 52Passing the message is supported both in a one-shot fashion using 53EVP_PKEY_verify(), and through the combination of EVP_PKEY_verify_update() and 54EVP_PKEY_verify_final(). 55This function enables using algorithms that can process input of arbitrary 56length, such as ED25519, RSA-SHA256 and similar. 57 58EVP_PKEY_CTX_set_signature() specifies the I<siglen> bytes long signature 59I<sig> to be verified against by EVP_PKEY_verify_final(). 60It I<must> be used together with EVP_PKEY_verify_update() and 61EVP_PKEY_verify_final(). 62See L</NOTES> below for a deeper explanation. 63 64EVP_PKEY_verify_update() adds I<inlen> bytes from I<in> to the data to be 65processed for verification. The signature algorithm specification and 66implementation determine how the input bytes are processed and if there's a 67limit on the total size of the input. See L</NOTES> below for a deeper 68explanation. 69 70EVP_PKEY_verify_final() verifies the processed data, given only I<ctx>. 71The signature to verify against must have been given with 72EVP_PKEY_CTX_set_signature(). 73 74EVP_PKEY_verify() is a one-shot function that performs the same thing as 75EVP_PKEY_CTX_set_signature() call with I<sig> and I<siglen> as parameters, 76followed by a single EVP_PKEY_verify_update() call with I<tbs> and I<tbslen>, 77followed by EVP_PKEY_verify_final() call. 78 79=head1 NOTES 80 81=begin comment 82 83These notes are largely replicated in EVP_PKEY_sign.pod, please keep them 84in sync. 85 86=end comment 87 88=head2 General 89 90Some signature implementations only accumulate the input data and do no 91further processing before verifying it (they expect the input to be a digest), 92while others compress the data, typically by internally producing a digest, 93and signing the result, which is then verified against a given signature. 94Some of them support both modes of operation at the same time. 95The caller is expected to know how the chosen algorithm is supposed to behave 96and under what conditions. 97 98For example, an RSA implementation can be expected to only expect a digest as 99input, while ED25519 can be expected to process the input with a hash, i.e. 100to produce the digest internally, and while RSA-SHA256 can be expected to 101handle either mode of operation, depending on if the operation was initialized 102with EVP_PKEY_verify_init_ex2() or with EVP_PKEY_verify_message_init(). 103 104Similarly, an RSA implementation usually expects additional details to be set, 105like the message digest algorithm that the input is supposed to be digested 106with, as well as the padding mode (see L<EVP_PKEY_CTX_set_signature_md(3)> and 107L<EVP_PKEY_CTX_set_rsa_padding(3)> and similar others), while an RSA-SHA256 108implementation usually has these details pre-set and immutable. 109 110The functions described here can't be used to combine separate algorithms. In 111particular, neither L<EVP_PKEY_CTX_set_signature_md(3)> nor the B<OSSL_PARAM> 112parameter "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) can be used to combine a 113signature algorithm with a hash algorithm to process the input. In other 114words, it's not possible to specify a I<ctx> pre-loaded with an RSA pkey, or 115an I<algo> that fetched C<RSA> and try to specify SHA256 separately to get the 116functionality of RSA-SHA256. If combining algorithms in that manner is 117desired, please use L<EVP_DigestVerifyInit(3)> and associated functions, or 118L<EVP_VerifyInit(3)> and associated functions. 119 120=head2 Performing multiple verifications 121 122When initialized using EVP_PKEY_verify_init_ex() or EVP_PKEY_verify_init_ex2(), 123EVP_PKEY_verify() can be called more than once on the same context to have 124several one-shot operations performed using the same parameters. 125 126When initialized using EVP_PKEY_verify_message_init(), it's not possible to 127call EVP_PKEY_verify() multiple times. 128 129=head2 On EVP_PKEY_CTX_set_signature() 130 131Some signature algorithms (such as LMS) require the signature verification 132data be specified before verifying the message. 133Other algorithms allow the signature to be specified late. 134To allow either way (which may depend on the application's flow of input), the 135signature to be verified against I<must> be specified using this function when 136using EVP_PKEY_verify_message_update() and EVP_PKEY_verify_message_final() to 137perform the verification. 138 139=head1 RETURN VALUES 140 141All functions return 1 for success and 0 or a negative value for failure. 142However, unlike other functions, the return value 0 from EVP_PKEY_verify(), 143EVP_PKEY_verify_recover() and EVP_PKEY_verify_message_final() only indicates 144that the signature did not verify successfully (that is tbs did not match the 145original data or the signature was of invalid form) it is not an indication of 146a more serious error. 147 148A negative value indicates an error other that signature verification failure. 149In particular a return value of -2 indicates the operation is not supported by 150the public key algorithm. 151 152=head1 EXAMPLES 153 154=begin comment 155 156These examples are largely replicated in EVP_PKEY_sign.pod, please keep them 157in sync. 158 159=end comment 160 161=head2 RSA with PKCS#1 padding for SHA256 162 163Verify signature using PKCS#1 padding and a SHA256 digest as input: 164 165 #include <openssl/evp.h> 166 #include <openssl/rsa.h> 167 168 EVP_PKEY_CTX *ctx; 169 unsigned char *md, *sig; 170 size_t mdlen, siglen; 171 EVP_PKEY *verify_key; 172 173 /* 174 * NB: assumes verify_key, sig, siglen md and mdlen are already set up 175 * and that verify_key is an RSA public key 176 */ 177 ctx = EVP_PKEY_CTX_new(verify_key, NULL /* no engine */); 178 if (ctx == NULL) 179 /* Error occurred */ 180 if (EVP_PKEY_verify_init(ctx) <= 0) 181 /* Error */ 182 if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) 183 /* Error */ 184 if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) 185 /* Error */ 186 187 /* Perform operation */ 188 ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen); 189 190 /* 191 * ret == 1 indicates success, 0 verify failure and < 0 for some 192 * other error. 193 */ 194 195=head2 RSA-SHA256 with a pre-computed digest 196 197Verify a digest with RSA-SHA256 using one-shot functions. To be noted is that 198RSA-SHA256 is assumed to be an implementation of C<sha256WithRSAEncryption>, 199for which the padding is pre-determined to be B<RSA_PKCS1_PADDING>, and the 200input digest is assumed to have been computed using SHA256. 201 202 #include <openssl/evp.h> 203 #include <openssl/rsa.h> 204 205 EVP_PKEY_CTX *ctx; 206 /* md is a SHA-256 digest in this example. */ 207 unsigned char *md, *sig; 208 size_t mdlen = 32, siglen; 209 EVP_PKEY *signing_key; 210 211 /* 212 * NB: assumes verify_key, sig, siglen, md and mdlen are already set up 213 * and that verify_key is an RSA public key 214 */ 215 ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); 216 alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL); 217 218 if (ctx == NULL) 219 /* Error occurred */ 220 if (EVP_PKEY_verify_init_ex2(ctx, alg, NULL) <= 0) 221 /* Error */ 222 223 /* Determine buffer length */ 224 if (EVP_PKEY_verify(ctx, sig, siglen, md, mdlen) <= 0) 225 /* Error or signature doesn't verify */ 226 227 /* Perform operation */ 228 ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen); 229 230 /* 231 * ret == 1 indicates success, 0 verify failure and < 0 for some 232 * other error. 233 */ 234 235=head2 RSA-SHA256, one-shot 236 237Verify a document with RSA-SHA256 using one-shot functions. 238To be noted is that RSA-SHA256 is assumed to be an implementation of 239C<sha256WithRSAEncryption>, for which the padding is pre-determined to be 240B<RSA_PKCS1_PADDING>. 241 242 #include <openssl/evp.h> 243 #include <openssl/rsa.h> 244 245 EVP_PKEY_CTX *ctx; 246 /* in the input in this example. */ 247 unsigned char *in, *sig; 248 /* inlen is the length of the input in this example. */ 249 size_t inlen, siglen; 250 EVP_PKEY *signing_key; 251 EVP_SIGNATURE *alg; 252 253 /* 254 * NB: assumes signing_key, in and inlen are set up before 255 * the next step. signing_key must be an RSA private key, 256 * in must point to data to be digested and signed, and 257 * inlen must be the size of the data in bytes. 258 */ 259 ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); 260 alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL); 261 262 if (ctx == NULL || alg == NULL) 263 /* Error occurred */ 264 if (EVP_PKEY_verify_message_init(ctx, alg, NULL) <= 0) 265 /* Error */ 266 267 /* Perform operation */ 268 ret = EVP_PKEY_verify(ctx, sig, siglen, in, inlen); 269 270 /* 271 * ret == 1 indicates success, 0 verify failure and < 0 for some 272 * other error. 273 */ 274 275=head2 RSA-SHA256, using update and final 276 277This is the same as the previous example, but allowing stream-like 278functionality. 279 280 #include <openssl/evp.h> 281 #include <openssl/rsa.h> 282 283 EVP_PKEY_CTX *ctx; 284 /* in is the input in this example. */ 285 unsigned char *in, *sig; 286 /* inlen is the length of the input in this example. */ 287 size_t inlen, siglen; 288 EVP_PKEY *signing_key; 289 EVP_SIGNATURE *alg; 290 291 /* 292 * NB: assumes signing_key, in and inlen are set up before 293 * the next step. signing_key must be an RSA private key, 294 * in must point to data to be digested and signed, and 295 * inlen must be the size of the data in bytes. 296 */ 297 ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); 298 alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL); 299 300 if (ctx == NULL || alg == NULL) 301 /* Error occurred */ 302 if (EVP_PKEY_verify_message_init(ctx, alg, NULL) <= 0) 303 /* Error */ 304 305 /* We have the signature, specify it early */ 306 EVP_PKEY_CTX_set_signature(ctx, sig, siglen); 307 308 /* Perform operation */ 309 while (inlen > 0) { 310 if (EVP_PKEY_verify_message_update(ctx, in, inlen)) <= 0) 311 /* Error */ 312 if (inlen > 256) { 313 inlen -= 256; 314 in += 256; 315 } else { 316 inlen = 0; 317 } 318 } 319 ret = EVP_PKEY_verify_message_final(ctx); 320 321 /* 322 * ret == 1 indicates success, 0 verify failure and < 0 for some 323 * other error. 324 */ 325 326 327=head1 SEE ALSO 328 329L<EVP_PKEY_CTX_new(3)>, 330L<EVP_PKEY_encrypt(3)>, 331L<EVP_PKEY_decrypt(3)>, 332L<EVP_PKEY_sign(3)>, 333L<EVP_PKEY_verify_recover(3)>, 334L<EVP_PKEY_derive(3)> 335 336=head1 HISTORY 337 338The EVP_PKEY_verify_init() and EVP_PKEY_verify() functions were added in 339OpenSSL 1.0.0. 340 341The EVP_PKEY_verify_init_ex() function was added in OpenSSL 3.0. 342 343The EVP_PKEY_verify_init_ex2(), EVP_PKEY_verify_message_init(), 344EVP_PKEY_verify_message_update(), EVP_PKEY_verify_message_final() and 345EVP_PKEY_CTX_set_signature() functions where added in OpenSSL 3.4. 346 347=head1 COPYRIGHT 348 349Copyright 2006-2024 The OpenSSL Project Authors. All Rights Reserved. 350 351Licensed under the Apache License 2.0 (the "License"). You may not use 352this file except in compliance with the License. You can obtain a copy 353in the file LICENSE in the source distribution or at 354L<https://www.openssl.org/source/license.html>. 355 356=cut 357
