Android_verify/lib/openssl/share/man/man3/EVP_PKEY_sign.3ossl

.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "EVP_PKEY_SIGN 3ossl"
.TH EVP_PKEY_SIGN 3ossl 2025-01-17 3.4.0 OpenSSL
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
EVP_PKEY_sign_init, EVP_PKEY_sign_init_ex, EVP_PKEY_sign_init_ex2,
EVP_PKEY_sign, EVP_PKEY_sign_message_init, EVP_PKEY_sign_message_update,
EVP_PKEY_sign_message_final \- sign using a public key algorithm
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/evp.h>
\&
\& int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx);
\& int EVP_PKEY_sign_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
\& int EVP_PKEY_sign_init_ex2(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo,
\&                            const OSSL_PARAM params[]);
\& int EVP_PKEY_sign_message_init(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo,
\&                                const OSSL_PARAM params[]);
\& int EVP_PKEY_sign_message_update(EVP_PKEY_CTX *ctx,
\&                                  unsigned char *in, size_t inlen);
\& int EVP_PKEY_sign_message_final(EVP_PKEY_CTX *ctx, unsigned char *sig,
\&                                 size_t *siglen, size_t sigsize);
\& int EVP_PKEY_sign(EVP_PKEY_CTX *ctx,
\&                   unsigned char *sig, size_t *siglen,
\&                   const unsigned char *tbs, size_t tbslen);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBEVP_PKEY_sign_init()\fR initializes a public key algorithm context \fIctx\fR for
signing using the algorithm given when the context was created
using \fBEVP_PKEY_CTX_new\fR\|(3) or variants thereof.  The algorithm is used to
fetch a \fBEVP_SIGNATURE\fR method implicitly, see "Implicit fetch" in \fBprovider\fR\|(7)
for more information about implicit fetches.
.PP
\&\fBEVP_PKEY_sign_init_ex()\fR is the same as \fBEVP_PKEY_sign_init()\fR but additionally
sets the passed parameters \fIparams\fR on the context before returning.
.PP
\&\fBEVP_PKEY_sign_init_ex2()\fR initializes a public key algorithm context \fIctx\fR for
signing a pre-computed message digest using the algorithm given by \fIalgo\fR and
the key given through \fBEVP_PKEY_CTX_new\fR\|(3) or \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3).
A context \fIctx\fR without a pre-loaded key cannot be used with this function.
This function provides almost the same functionality as \fBEVP_PKEY_sign_init_ex()\fR,
but is uniquely intended to be used with a pre-computed messsage digest, and
allows pre-determining the exact conditions for that message digest, if a
composite signature algorithm (such as RSA\-SHA256) was fetched.
Following a call to this function, setting parameters that modifies the digest
implementation or padding is not normally supported.
.PP
\&\fBEVP_PKEY_sign_message_init()\fR initializes a public key algorithm context \fIctx\fR
for signing an unlimited size message using the algorithm given by \fIalgo\fR and
the key given through \fBEVP_PKEY_CTX_new\fR\|(3) or \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3).
Passing the message is supported both in a one-shot fashion using
\&\fBEVP_PKEY_sign()\fR, and through the combination of \fBEVP_PKEY_sign_message_update()\fR
and \fBEVP_PKEY_sign_message_final()\fR.
This function enables using algorithms that can process input of arbitrary
length, such as ED25519, RSA\-SHA256 and similar.
.PP
\&\fBEVP_PKEY_sign_message_update()\fR adds \fIinlen\fR bytes from \fIin\fR to the data to be
processed for signature.  The signature algorithm specification and
implementation determine how the input bytes are processed and if there's a
limit on the total size of the input.  See "NOTES" below for a deeper
explanation.
.PP
\&\fBEVP_PKEY_sign_message_final()\fR signs the processed data and places the data in
\&\fIsig\fR, and the number of signature bytes in \fI*siglen\fR, if the number of
bytes doesn't surpass the size given by \fIsigsize\fR.
\&\fIsig\fR may be NULL, and in that case, only \fI*siglen\fR is updated with the
number of signature bytes.
.PP
\&\fBEVP_PKEY_sign()\fR is a one-shot function that can be used with all the init
functions above.
When initialization was done with \fBEVP_PKEY_sign_init()\fR, \fBEVP_PKEY_sign_init_ex()\fR
or \fBEVP_PKEY_sign_init_ex2()\fR, the data specified by \fItbs\fR and \fItbslen\fR is
signed after appropriate padding.
When initialization was done with \fBEVP_PKEY_sign_message_init()\fR, the data
specified by \fItbs\fR and \fItbslen\fR is digested by the implied message digest
algorithm, and the result is signed after appropriate padding.
If \fIsig\fR is NULL then the maximum size of the output buffer is written to the
\&\fIsiglen\fR parameter.
If \fIsig\fR is not NULL, then before the call the \fIsiglen\fR parameter should
contain the length of the \fIsig\fR buffer, and if the call is successful the
signature is written to \fIsig\fR and the amount of data written to \fIsiglen\fR.
.SH NOTES
.IX Header "NOTES"
.SS General
.IX Subsection "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.
.PP
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 \fBEVP_PKEY_sign_init_ex2()\fR or with \fBEVP_PKEY_sign_message_init()\fR.
.PP
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 \fBEVP_PKEY_CTX_set_signature_md\fR\|(3) and
\&\fBEVP_PKEY_CTX_set_rsa_padding\fR\|(3) and similar others), while an RSA\-SHA256
implementation usually has these details pre-set and immutable.
.PP
The functions described here can't be used to combine separate algorithms.  In
particular, neither \fBEVP_PKEY_CTX_set_signature_md\fR\|(3) nor the \fBOSSL_PARAM\fR
parameter "digest" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) 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 \fIctx\fR pre-loaded with an RSA pkey, or
an \fIalgo\fR that fetched \f(CW\*(C`RSA\*(C'\fR and try to specify SHA256 separately to get the
functionality of RSA\-SHA256.  If combining algorithms in that manner is
desired, please use \fBEVP_DigestSignInit\fR\|(3) and associated functions.
.SS "Performing multiple signatures"
.IX Subsection "Performing multiple signatures"
When initialized using \fBEVP_PKEY_sign_init_ex()\fR or  \fBEVP_PKEY_sign_init_ex2()\fR,
\&\fBEVP_PKEY_sign()\fR can be called more than once on the same context to have
several one-shot operations performed using the same parameters.
.PP
When initialized using \fBEVP_PKEY_sign_message_init()\fR, it's not possible to
call \fBEVP_PKEY_sign()\fR multiple times.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
All functions return 1 for success and 0 or a negative value for failure.
.PP
In particular, \fBEVP_PKEY_sign_init()\fR and its other variants may return \-2 to
indicate that the operation is not supported by the public key algorithm.
.SH EXAMPLES
.IX Header "EXAMPLES"
.SS "RSA with PKCS#1 padding for SHA256"
.IX Subsection "RSA with PKCS#1 padding for SHA256"
Sign data using RSA with PKCS#1 padding and a SHA256 digest as input:
.PP
.Vb 2
\& #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 */
.Ve
.SS "RSA\-SHA256 with a pre-computed digest"
.IX Subsection "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 \f(CW\*(C`sha256WithRSAEncryption\*(C'\fR,
for which the padding is pre-determined to be \fBRSA_PKCS1_PADDING\fR, and the
input digest is assumed to have been computed using SHA256.
.PP
.Vb 2
\& #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 */
.Ve
.SS "RSA\-SHA256, one-shot"
.IX Subsection "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
\&\f(CW\*(C`sha256WithRSAEncryption\*(C'\fR, for which the padding is pre-determined to be
\&\fBRSA_PKCS1_PADDING\fR.
.PP
.Vb 2
\& #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 */
.Ve
.SS "RSA\-SHA256, using update and final"
.IX Subsection "RSA-SHA256, using update and final"
This is the same as the previous example, but allowing stream-like
functionality.
.PP
.Vb 2
\& #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 */
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBEVP_PKEY_CTX_new\fR\|(3),
\&\fBEVP_PKEY_CTX_ctrl\fR\|(3),
\&\fBEVP_PKEY_encrypt\fR\|(3),
\&\fBEVP_PKEY_decrypt\fR\|(3),
\&\fBEVP_PKEY_verify\fR\|(3),
\&\fBEVP_PKEY_verify_recover\fR\|(3),
\&\fBEVP_PKEY_derive\fR\|(3)
.SH HISTORY
.IX Header "HISTORY"
The \fBEVP_PKEY_sign_init()\fR and \fBEVP_PKEY_sign()\fR functions were added in
OpenSSL 1.0.0.
.PP
The \fBEVP_PKEY_sign_init_ex()\fR function was added in OpenSSL 3.0.
.PP
The \fBEVP_PKEY_sign_init_ex2()\fR, \fBEVP_PKEY_sign_message_init()\fR,
\&\fBEVP_PKEY_sign_message_update()\fR and \fBEVP_PKEY_sign_message_final()\fR functions
where added in OpenSSL 3.4.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2006\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
<https://www.openssl.org/source/license.html>.