|PKCS7_SIGN(3)||Library Functions Manual||PKCS7_SIGN(3)|
create a PKCS#7 signedData structure
EVP_PKEY *pkey, STACK_OF(X509)
*certs, BIO *data, int
PKCS7_sign() creates and returns a PKCS#7
signedData structure. signcert is the certificate to
sign with, pkey is the corresponding private key.
certs is an optional additional set of certificates to
include in the PKCS#7 structure (for example any intermediate CAs in the
The data to be signed is read from BIO data.
flags is an optional set of flags.
Any of the following flags (OR'ed together) can be passed in the flags parameter.
Many S/MIME clients expect the signed content to include valid
MIME headers. If the
PKCS7_TEXT flag is set, MIME
headers for type text/plain are prepended to the data.
PKCS7_NOCERTS is set, the signer's
certificate will not be included in the PKCS7 structure, though the signer's
certificate must still be supplied in the signcert
parameter. This can reduce the size of the signature if the signer's
certificate can be obtained by other means: for example a previously signed
The data being signed is included in the
PKCS7 structure, unless
PKCS7_DETACHED is set, in which case it is omitted.
This is used for PKCS7 detached signatures which are used in S/MIME
plaintext signed messages for example.
Normally the supplied content is translated into MIME canonical
format (as required by the S/MIME specifications). If
PKCS7_BINARY is set, no translation occurs. This
option should be used if the supplied data is in binary format; otherwise,
the translation will corrupt it.
The signedData structure includes several PKCS#7
authenticatedAttributes including the signing time, the PKCS#7 content type
and the supported list of ciphers in an SMIMECapabilities attribute. If
PKCS7_NOATTR is set, then no authenticatedAttributes
will be used. If
PKCS7_NOSMIMECAP is set, then just
the SMIMECapabilities are omitted.
If present, the SMIMECapabilities attribute indicates support for the following algorithms: triple DES, 128-bit RC2, 64-bit RC2, DES and 40-bit RC2. If any of these algorithms is disabled then it will not be included.
If the flags
PKCS7_STREAM is set, then the
returned PKCS7 structure is just initialized ready to
perform the signing operation. The signing is however not
performed and the data to be signed is not read from the
data parameter. Signing is deferred until after the
data has been written. In this way data can be signed in a single pass.
PKCS7_PARTIAL flag is set, a
partial PKCS7 structure is output to which additional
signers and capabilities can be added before finalization.
If the flag
PKCS7_STREAM is set, the
returned PKCS7 structure is not
complete and outputting its contents via a function that does not properly
finalize the PKCS7 structure will give unpredictable
Several functions, including
finalize the structure. Alternatively finalization can be performed by
obtaining the streaming ASN.1 BIO directly using
If a signer is specified, it will use the default digest for the signing algorithm. This is SHA1 for both RSA and DSA keys.
In OpenSSL 1.0.0, the certs,
signcert, and pkey parameters
can all be
NULL if the
PKCS7_PARTIAL flag is set. One or more signers can
be added using the function
PKCS7_final() must also be called to finalize the
structure if streaming is not enabled. Alternative signing digests can also
be specified using this method.
In OpenSSL 1.0.0, if signcert and
NULL, then a
certificate-only PKCS#7 structure is output.
In versions of OpenSSL before 1.0.0 the
signcert and pkey parameters
must NOT be
PKCS7_sign() returns either a valid
PKCS7 structure or
NULL if an
error occurred. The error can be obtained from
PKCS7_sign() first appeared in OpenSSL
0.9.5 and have been available since OpenBSD 2.7.
PKCS7_STREAM flags were added in OpenSSL 1.0.0.
Some advanced attributes such as counter signatures are not supported.
|June 10, 2019||OpenBSD-current|