1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948PKCS7_sign - create a PKCS#7 signedData structure 6*2175Sjp161948 7*2175Sjp161948=head1 SYNOPSIS 8*2175Sjp161948 9*2175Sjp161948PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags); 10*2175Sjp161948 11*2175Sjp161948=head1 DESCRIPTION 12*2175Sjp161948 13*2175Sjp161948PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> 14*2175Sjp161948is the certificate to sign with, B<pkey> is the corresponsding private key. 15*2175Sjp161948B<certs> is an optional additional set of certificates to include in the 16*2175Sjp161948PKCS#7 structure (for example any intermediate CAs in the chain). 17*2175Sjp161948 18*2175Sjp161948The data to be signed is read from BIO B<data>. 19*2175Sjp161948 20*2175Sjp161948B<flags> is an optional set of flags. 21*2175Sjp161948 22*2175Sjp161948=head1 NOTES 23*2175Sjp161948 24*2175Sjp161948Any of the following flags (ored together) can be passed in the B<flags> parameter. 25*2175Sjp161948 26*2175Sjp161948Many S/MIME clients expect the signed content to include valid MIME headers. If 27*2175Sjp161948the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended 28*2175Sjp161948to the data. 29*2175Sjp161948 30*2175Sjp161948If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the 31*2175Sjp161948PKCS7 structure, the signer's certificate must still be supplied in the B<signcert> 32*2175Sjp161948parameter though. This can reduce the size of the signature if the signers certificate 33*2175Sjp161948can be obtained by other means: for example a previously signed message. 34*2175Sjp161948 35*2175Sjp161948The data being signed is included in the PKCS7 structure, unless B<PKCS7_DETACHED> 36*2175Sjp161948is set in which case it is omitted. This is used for PKCS7 detached signatures 37*2175Sjp161948which are used in S/MIME plaintext signed messages for example. 38*2175Sjp161948 39*2175Sjp161948Normally the supplied content is translated into MIME canonical format (as required 40*2175Sjp161948by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation occurs. This 41*2175Sjp161948option should be used if the supplied data is in binary format otherwise the translation 42*2175Sjp161948will corrupt it. 43*2175Sjp161948 44*2175Sjp161948The signedData structure includes several PKCS#7 autenticatedAttributes including 45*2175Sjp161948the signing time, the PKCS#7 content type and the supported list of ciphers in 46*2175Sjp161948an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no authenticatedAttributes 47*2175Sjp161948will be used. If B<PKCS7_NOSMIMECAP> is set then just the SMIMECapabilities are 48*2175Sjp161948omitted. 49*2175Sjp161948 50*2175Sjp161948If present the SMIMECapabilities attribute indicates support for the following 51*2175Sjp161948algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any 52*2175Sjp161948of these algorithms is disabled then it will not be included. 53*2175Sjp161948 54*2175Sjp161948If the flags B<PKCS7_PARTSIGN> is set then the returned B<PKCS7> structure 55*2175Sjp161948is just initialized ready to perform the signing operation. The signing 56*2175Sjp161948is however B<not> performed and the data to be signed is not read from 57*2175Sjp161948the B<data> parameter. Signing is deferred until after the data has been 58*2175Sjp161948written. In this way data can be signed in a single pass. Currently the 59*2175Sjp161948flag B<PKCS7_DETACHED> B<must> also be set. 60*2175Sjp161948 61*2175Sjp161948=head1 NOTES 62*2175Sjp161948 63*2175Sjp161948Currently the flag B<PKCS7_PARTSIGN> is only supported for detached 64*2175Sjp161948data. If this flag is set the returned B<PKCS7> structure is B<not> 65*2175Sjp161948complete and outputting its contents via a function that does not 66*2175Sjp161948properly finalize the B<PKCS7> structure will give unpredictable 67*2175Sjp161948results. 68*2175Sjp161948 69*2175Sjp161948At present only the SMIME_write_PKCS7() function properly finalizes the 70*2175Sjp161948structure. 71*2175Sjp161948 72*2175Sjp161948=head1 BUGS 73*2175Sjp161948 74*2175Sjp161948PKCS7_sign() is somewhat limited. It does not support multiple signers, some 75*2175Sjp161948advanced attributes such as counter signatures are not supported. 76*2175Sjp161948 77*2175Sjp161948The SHA1 digest algorithm is currently always used. 78*2175Sjp161948 79*2175Sjp161948When the signed data is not detached it will be stored in memory within the 80*2175Sjp161948B<PKCS7> structure. This effectively limits the size of messages which can be 81*2175Sjp161948signed due to memory restraints. There should be a way to sign data without 82*2175Sjp161948having to hold it all in memory, this would however require fairly major 83*2175Sjp161948revisions of the OpenSSL ASN1 code. 84*2175Sjp161948 85*2175Sjp161948 86*2175Sjp161948=head1 RETURN VALUES 87*2175Sjp161948 88*2175Sjp161948PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error occurred. 89*2175Sjp161948The error can be obtained from ERR_get_error(3). 90*2175Sjp161948 91*2175Sjp161948=head1 SEE ALSO 92*2175Sjp161948 93*2175Sjp161948L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)> 94*2175Sjp161948 95*2175Sjp161948=head1 HISTORY 96*2175Sjp161948 97*2175Sjp161948PKCS7_sign() was added to OpenSSL 0.9.5 98*2175Sjp161948 99*2175Sjp161948The B<PKCS7_PARTSIGN> flag was added in OpenSSL 0.9.8 100*2175Sjp161948 101*2175Sjp161948=cut 102