Update docs.
authorDr. Stephen Henson <steve@openssl.org>
Fri, 13 Apr 2007 12:57:48 +0000 (12:57 +0000)
committerDr. Stephen Henson <steve@openssl.org>
Fri, 13 Apr 2007 12:57:48 +0000 (12:57 +0000)
doc/crypto/PKCS7_encrypt.pod
doc/crypto/PKCS7_sign.pod

index 7e67f95..c17cb8d 100644 (file)
@@ -18,43 +18,55 @@ B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
 
 =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
 
@@ -63,5 +75,6 @@ L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>
 =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
index 21b1710..b10df26 100644 (file)
@@ -12,10 +12,10 @@ PKCS7_sign - create a PKCS#7 signedData structure
 
 =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>.
 
@@ -23,72 +23,83 @@ B<flags> is an optional set of flags.
 
 =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
 
@@ -98,6 +109,8 @@ L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)>
 
 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