General¶

Some signature implementations only accumulate the input data and do no further processing before signing it (they expect the input to be a digest), while others compress the data, typically by internally producing a digest, and signing the result. Some of them support both modes of operation at the same time. The caller is expected to know how the chosen algorithm is supposed to behave and under what conditions.

For example, an RSA implementation can be expected to only expect a message digest as input, while ED25519 can be expected to process the input with a hash, i.e. to produce the message digest internally, and while RSA-SHA256 can be expected to handle either mode of operation, depending on if the operation was initialized with EVP_PKEY_sign_init_ex2() or with EVP_PKEY_sign_message_init().

Similarly, an RSA implementation usually expects additional details to be set, like the message digest algorithm that the input is supposed to be digested with, as well as the padding mode (see EVP_PKEY_CTX_set_signature_md(3) and EVP_PKEY_CTX_set_rsa_padding(3) and similar others), while an RSA-SHA256 implementation usually has these details pre-set and immutable.

The functions described here can't be used to combine separate algorithms. In particular, neither EVP_PKEY_CTX_set_signature_md(3) nor the OSSL_PARAM parameter "digest" (OSSL_SIGNATURE_PARAM_DIGEST) can be used to combine a signature algorithm with a hash algorithm to process the input. In other words, it's not possible to specify a ctx pre-loaded with an RSA pkey, or an algo that fetched "RSA" and try to specify SHA256 separately to get the functionality of RSA-SHA256. If combining algorithms in that manner is desired, please use EVP_DigestSignInit(3) and associated functions.

Performing multiple signatures¶

When initialized using EVP_PKEY_sign_init_ex() or EVP_PKEY_sign_init_ex2(), EVP_PKEY_sign() can be called more than once on the same context to have several one-shot operations performed using the same parameters.

When initialized using EVP_PKEY_sign_message_init(), it's not possible to call EVP_PKEY_sign() multiple times.

RSA with PKCS#1 padding for SHA256¶

Sign data using RSA with PKCS#1 padding and a SHA256 digest as input:

 #include <openssl/evp.h>
 #include <openssl/rsa.h>
 EVP_PKEY_CTX *ctx;
 /* md is a SHA-256 digest in this example. */
 unsigned char *md, *sig;
 size_t mdlen = 32, siglen;
 EVP_PKEY *signing_key;
 /*
  * NB: assumes signing_key and md are set up before the next
  * step. signing_key must be an RSA private key and md must
  * point to the SHA-256 digest to be signed.
  */
 ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
 if (ctx == NULL)
     /* Error occurred */
 if (EVP_PKEY_sign_init(ctx) <= 0)
     /* Error */
 if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
     /* Error */
 if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
     /* Error */
 /* Determine buffer length */
 if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0)
     /* Error */
 sig = OPENSSL_malloc(siglen);
 if (sig == NULL)
     /* malloc failure */
 if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0)
     /* Error */
 /* Signature is siglen bytes written to buffer sig */

RSA-SHA256 with a pre-computed digest¶

Sign a digest with RSA-SHA256 using one-shot functions. To be noted is that RSA-SHA256 is assumed to be an implementation of "sha256WithRSAEncryption", for which the padding is pre-determined to be RSA_PKCS1_PADDING, and the input digest is assumed to have been computed using SHA256.

 #include <openssl/evp.h>
 #include <openssl/rsa.h>
 EVP_PKEY_CTX *ctx;
 /* md is a SHA-256 digest in this example. */
 unsigned char *md, *sig;
 size_t mdlen = 32, siglen;
 EVP_PKEY *signing_key;
 /*
  * NB: assumes signing_key and md are set up before the next
  * step. signing_key must be an RSA private key and md must
  * point to the SHA-256 digest to be signed.
  */
 ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
 alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL);
 if (ctx == NULL)
     /* Error occurred */
 if (EVP_PKEY_sign_init_ex2(ctx, alg, NULL) <= 0)
     /* Error */
 /* Determine buffer length */
 if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0)
     /* Error */
 sig = OPENSSL_malloc(siglen);
 if (sig == NULL)
     /* malloc failure */
 if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0)
     /* Error */
 /* Signature is siglen bytes written to buffer sig */

RSA-SHA256, one-shot¶

Sign a document with RSA-SHA256 using one-shot functions. To be noted is that RSA-SHA256 is assumed to be an implementation of "sha256WithRSAEncryption", for which the padding is pre-determined to be RSA_PKCS1_PADDING.

 #include <openssl/evp.h>
 #include <openssl/rsa.h>
 EVP_PKEY_CTX *ctx;
 /* in is the input in this example. */
 unsigned char *in, *sig;
 /* inlen is the length of the input in this example. */
 size_t inlen, siglen;
 EVP_PKEY *signing_key;
 EVP_SIGNATURE *alg;
 /*
  * NB: assumes signing_key, in and inlen are set up before
  * the next step. signing_key must be an RSA private key,
  * in must point to data to be digested and signed, and
  * inlen must be the size of the data in bytes.
  */
 ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
 alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL);
 if (ctx == NULL || alg == NULL)
     /* Error occurred */
 if (EVP_PKEY_sign_message_init(ctx, alg, NULL) <= 0)
     /* Error */
 /* Determine sig buffer length */
 if (EVP_PKEY_sign(ctx, NULL, &siglen, in, inlen) <= 0)
     /* Error */
 sig = OPENSSL_malloc(siglen);
 if (sig == NULL)
     /* malloc failure */
 if (EVP_PKEY_sign(ctx, sig, &siglen, in, inlen) <= 0)
     /* Error */
 /* Signature is siglen bytes written to buffer sig */

RSA-SHA256, using update and final¶

This is the same as the previous example, but allowing stream-like functionality.

 #include <openssl/evp.h>
 #include <openssl/rsa.h>
 EVP_PKEY_CTX *ctx;
 /* in is the input in this example. */
 unsigned char *in, *sig;
 /* inlen is the length of the input in this example. */
 size_t inlen, siglen;
 EVP_PKEY *signing_key;
 EVP_SIGNATURE *alg;
 /*
  * NB: assumes signing_key, in and inlen are set up before
  * the next step. signing_key must be an RSA private key,
  * in must point to data to be digested and signed, and
  * inlen must be the size of the data in bytes.
  */
 ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
 alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL);
 if (ctx == NULL || alg == NULL)
     /* Error occurred */
 if (EVP_PKEY_sign_message_init(ctx, alg, NULL) <= 0)
     /* Error */
 while (inlen > 0) {
     if (EVP_PKEY_sign_message_update(ctx, in, inlen)) <= 0)
         /* Error */
     if (inlen > 256) {
         inlen -= 256;
         in += 256;
     } else {
         inlen = 0;
     }
 }
 /* Determine sig buffer length */
 if (EVP_PKEY_sign_message_final(ctx, NULL, &siglen) <= 0)
     /* Error */
 sig = OPENSSL_malloc(siglen);
 if (sig == NULL)
     /* malloc failure */
 if (EVP_PKEY_sign_message_final(ctx, sig, &siglen) <= 0)
     /* Error */
 /* Signature is siglen bytes written to buffer sig */