1=pod 2 3=head1 NAME 4 5PKCS7_sign - create a PKCS#7 signedData structure 6 7=head1 SYNOPSIS 8 9 #include <openssl/pkcs7.h> 10 11 PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags); 12 13=head1 DESCRIPTION 14 15PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> is 16the certificate to sign with, B<pkey> is the corresponsding private key. 17B<certs> is an optional additional set of certificates to include in the PKCS#7 18structure (for example any intermediate CAs in the chain). 19 20The data to be signed is read from BIO B<data>. 21 22B<flags> is an optional set of flags. 23 24=head1 NOTES 25 26Any of the following flags (ored together) can be passed in the B<flags> 27parameter. 28 29Many S/MIME clients expect the signed content to include valid MIME headers. If 30the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended 31to the data. 32 33If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the 34PKCS7 structure, the signer's certificate must still be supplied in the 35B<signcert> parameter though. This can reduce the size of the signature if the 36signers certificate can be obtained by other means: for example a previously 37signed message. 38 39The data being signed is included in the PKCS7 structure, unless 40B<PKCS7_DETACHED> is set in which case it is omitted. This is used for PKCS7 41detached signatures which are used in S/MIME plaintext signed messages for 42example. 43 44Normally the supplied content is translated into MIME canonical format (as 45required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation 46occurs. This option should be used if the supplied data is in binary format 47otherwise the translation will corrupt it. 48 49The signedData structure includes several PKCS#7 autenticatedAttributes 50including the signing time, the PKCS#7 content type and the supported list of 51ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no 52authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just 53the SMIMECapabilities are omitted. 54 55If present the SMIMECapabilities attribute indicates support for the following 56algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of 57these algorithms is disabled then it will not be included. 58 59If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is 60just initialized ready to perform the signing operation. The signing is however 61B<not> performed and the data to be signed is not read from the B<data> 62parameter. Signing is deferred until after the data has been written. In this 63way data can be signed in a single pass. 64 65If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to 66which additional signers and capabilities can be added before finalization. 67 68 69=head1 NOTES 70 71If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not> 72complete and outputting its contents via a function that does not properly 73finalize the B<PKCS7> structure will give unpredictable results. 74 75Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), 76PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization 77can be performed by obtaining the streaming ASN1 B<BIO> directly using 78BIO_new_PKCS7(). 79 80If a signer is specified it will use the default digest for the signing 81algorithm. This is B<SHA1> for both RSA and DSA keys. 82 83In OpenSSL 1.0.0 the B<certs>, B<signcert> and B<pkey> parameters can all be 84B<NULL> if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added 85using the function B<PKCS7_sign_add_signer()>. B<PKCS7_final()> must also be 86called to finalize the structure if streaming is not enabled. Alternative 87signing digests can also be specified using this method. 88 89In OpenSSL 1.0.0 if B<signcert> and B<pkey> are NULL then a certificates only 90PKCS#7 structure is output. 91 92In versions of OpenSSL before 1.0.0 the B<signcert> and B<pkey> parameters must 93B<NOT> be NULL. 94 95=head1 BUGS 96 97Some advanced attributes such as counter signatures are not supported. 98 99=head1 RETURN VALUES 100 101PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error 102occurred. The error can be obtained from ERR_get_error(3). 103 104=head1 SEE ALSO 105 106L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)> 107 108=head1 HISTORY 109 110PKCS7_sign() was added to OpenSSL 0.9.5 111 112The B<PKCS7_PARTIAL> flag was added in OpenSSL 1.0.0 113 114The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0 115 116=cut 117