=head1 NOTES
-Only RSA keys are supported in PKCS#7 and envelopedData so the recipient certificates
-supplied to this function must all contain RSA public keys, though they do not have to
-be signed using the RSA algorithm.
+Only RSA keys are supported in PKCS#7 and envelopedData so the recipient
+certificates supplied to this function must all contain RSA public keys, though
+they do not have to be signed using the RSA algorithm.
-EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use because
-most clients will support it.
+EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use
+because most clients will support it.
-Some old "export grade" clients may only support weak encryption using 40 or 64 bit
-RC2. These can be used by passing EVP_rc2_40_cbc() and EVP_rc2_64_cbc() respectively.
+Some old "export grade" clients may only support weak encryption using 40 or 64
+bit RC2. These can be used by passing EVP_rc2_40_cbc() and EVP_rc2_64_cbc()
+respectively.
-The algorithm passed in the B<cipher> parameter must support ASN1 encoding of its
-parameters.
+The algorithm passed in the B<cipher> parameter must support ASN1 encoding of
+its parameters.
-Many browsers implement a "sign and encrypt" option which is simply an S/MIME
+Many browsers implement a "sign and encrypt" option which is simply an S/MIME
envelopedData containing an S/MIME signed message. This can be readily produced
by storing the S/MIME signed message in a memory BIO and passing it to
PKCS7_encrypt().
The following flags can be passed in the B<flags> parameter.
-If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended
-to the data.
+If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are
+prepended to the data.
-Normally the supplied content is translated into MIME canonical format (as required
-by the S/MIME specifications) if B<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. If B<PKCS7_BINARY> is set then B<PKCS7_TEXT> is ignored.
+Normally the supplied content is translated into MIME canonical format (as
+required by the S/MIME specifications) if B<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. If B<PKCS7_BINARY> is set then
+B<PKCS7_TEXT> is ignored.
-=head1 RETURN VALUES
+If the B<PKCS7_STREAM> flag is set a partial B<PKCS7> structure is output
+suitable for streaming I/O: no data is read from the BIO B<in>.
-PKCS7_encrypt() returns either a valid PKCS7 structure or NULL if an error occurred.
-The error can be obtained from ERR_get_error(3).
+=head1 NOTES
+
+If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
+complete and outputting its contents via a function that does not
+properly finalize the B<PKCS7> structure will give unpredictable
+results.
-=head1 BUGS
+Several functions including SMIME_write_PKCS7(), d2i_PKCS7_bio_stream(),
+PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization
+can be performed by obtaining the streaming ASN1 B<BIO> directly using
+BIO_new_PKCS7().
-The lack of single pass processing and need to hold all data in memory as
-mentioned in PKCS7_sign() also applies to PKCS7_verify().
+=head1 RETURN VALUES
+
+PKCS7_encrypt() returns either a PKCS7 structure or NULL if an error occurred.
+The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
=head1 HISTORY
PKCS7_decrypt() was added to OpenSSL 0.9.5
+The B<PKCS7_STREAM> flag was first supported in OpenSSL 0.9.9.
=cut
=head1 DESCRIPTION
-PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert>
-
is the certificate to sign with, B<pkey> is the corresponsding private key.
-B<certs> is an optional additional set of certificates to include in the
-PKCS#7 structure (for example any intermediate CAs in the chain).
+PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> is
+the certificate to sign with, B<pkey> is the corresponsding private key.
+B<certs> is an optional additional set of certificates to include in the PKCS#7
+structure (for example any intermediate CAs in the chain).
The data to be signed is read from BIO B<data>.
=head1 NOTES
-Any of the following flags (ored together) can be passed in the B<flags> parameter.
+Any of the following flags (ored together) can be passed in the B<flags>
+parameter.
Many S/MIME clients expect the signed content to include valid MIME headers. If
the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended
to the data.
If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the
-PKCS7 structure, the signer's certificate must still be supplied in the B<signcert>
-parameter though. This can reduce the size of the signature if the signers certificate
-can be obtained by other means: for example a previously signed message.
+PKCS7 structure, the signer's certificate must still be supplied in the
+B<signcert> parameter though. This can reduce the size of the signature if the
+signers certificate can be obtained by other means: for example a previously
+signed message.
+
+The data being signed is included in the PKCS7 structure, unless
+B<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 B<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 autenticatedAttributes
+including the signing time, the PKCS#7 content type and the supported list of
+ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no
+authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just
+the SMIMECapabilities are omitted.
-The data being signed is included in the PKCS7 structure, unless B<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 B<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.
+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.
-The signedData structure includes several PKCS#7 autenticatedAttributes including
-the signing time, the PKCS#7 content type and the supported list of ciphers in
-an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no authenticatedAttributes
-will be used. If B<PKCS7_NOSMIMECAP> is set then just the SMIMECapabilities are
-omitted.
+If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is
+just initialized ready to perform the signing operation. The signing is however
+B<not> performed and the data to be signed is not read from the B<data>
+parameter. Signing is deferred until after the data has been written. In this
+way data can be signed in a single pass.
-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 B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to
+which additional signers and capabilities can be added before finalization.
-If the flags B<PKCS7_PARTSIGN> is set then the returned B<PKCS7> structure
-is just initialized ready to perform the signing operation. The signing
-is however B<not> performed and the data to be signed is not read from
-the B<data> parameter. Signing is deferred until after the data has been
-written. In this way data can be signed in a single pass. Currently the
-flag B<PKCS7_DETACHED> B<must> also be set.
=head1 NOTES
-Currently the flag B<PKCS7_PARTSIGN> is only supported for detached
-data. If this flag is set the returned B<PKCS7> structure is B<not>
-complete and outputting its contents via a function that does not
-properly finalize the B<PKCS7> structure will give unpredictable
-results.
+If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
+complete and outputting its contents via a function that does not properly
+finalize the B<PKCS7> structure will give unpredictable results.
-At present only the SMIME_write_PKCS7() function properly finalizes the
-structure.
+Several functions including SMIME_write_PKCS7(), d2i_PKCS7_bio_stream(),
+PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization
+can be performed by obtaining the streaming ASN1 B<BIO> directly using
+BIO_new_PKCS7().
-=head1 BUGS
+If a signer is specified it will use the default digest for the signing
+algorithm. This is B<SHA1> for both RSA and DSA keys.
-PKCS7_sign() is somewhat limited. It does not support multiple signers, some
-advanced attributes such as counter signatures are not supported.
+In OpenSSL 0.9.9 the B<certs>, B<signcert> and B<pkey> parameters can all be
+B<NULL> if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added
+using the function B<PKCS7_sign_add_signer()>. B<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.
-The SHA1 digest algorithm is currently always used.
+In OpenSSL 0.9.9 if B<signcert> and B<pkey> are NULL then a certificates only
+PKCS#7 structure is output.
-When the signed data is not detached it will be stored in memory within the
-B<PKCS7> structure. This effectively limits the size of messages which can be
-signed due to memory restraints. There should be a way to sign data without
-having to hold it all in memory, this would however require fairly major
-revisions of the OpenSSL ASN1 code.
+In versions of OpenSSL before 0.9.9 the B<signcert> and B<pkey> parameters must
+B<NOT> be NULL.
+=head1 BUGS
+
+Some advanced attributes such as counter signatures are not supported.
=head1 RETURN VALUES
-PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error occurred.
-The error can be obtained from ERR_get_error(3).
+PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error
+occurred. The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
PKCS7_sign() was added to OpenSSL 0.9.5
-The B<PKCS7_PARTSIGN> flag was added in OpenSSL 0.9.8
+The B<PKCS7_PARTIAL> flag was added in OpenSSL 0.9.9
+
+The B<PKCS7_STREAM> flag was added in OpenSSL 0.9.9
=cut
projects / openssl.git / commitdiff