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