From 4cfb986f279eab2479b7b818bc1e4c3fe63849ef Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Fri, 13 Apr 2007 12:57:48 +0000 Subject: [PATCH] Update docs. --- doc/crypto/PKCS7_encrypt.pod | 57 +++++++++++------- doc/crypto/PKCS7_sign.pod | 111 +++++++++++++++++++---------------- 2 files changed, 97 insertions(+), 71 deletions(-) diff --git a/doc/crypto/PKCS7_encrypt.pod b/doc/crypto/PKCS7_encrypt.pod index 7e67f9576a..c17cb8d1e9 100644 --- a/doc/crypto/PKCS7_encrypt.pod +++ b/doc/crypto/PKCS7_encrypt.pod @@ -18,43 +18,55 @@ B is the symmetric cipher to use. B 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 parameter must support ASN1 encoding of its -parameters. +The algorithm passed in the B 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 parameter. -If the B flag is set MIME headers for type B are prepended -to the data. +If the B flag is set MIME headers for type B are +prepended to the data. -Normally the supplied content is translated into MIME canonical format (as required -by the S/MIME specifications) if B 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 is set then B is ignored. +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if B 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 is set then +B is ignored. -=head1 RETURN VALUES +If the B flag is set a partial B structure is output +suitable for streaming I/O: no data is read from the BIO B. -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 is set the returned B structure is B +complete and outputting its contents via a function that does not +properly finalize the B 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 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, L =head1 HISTORY PKCS7_decrypt() was added to OpenSSL 0.9.5 +The B flag was first supported in OpenSSL 0.9.9. =cut diff --git a/doc/crypto/PKCS7_sign.pod b/doc/crypto/PKCS7_sign.pod index 21b1710370..b10df26044 100644 --- a/doc/crypto/PKCS7_sign.pod +++ b/doc/crypto/PKCS7_sign.pod @@ -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 -is the certificate to sign with, B is the corresponsding private key. -B 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 is +the certificate to sign with, B is the corresponsding private key. +B 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. @@ -23,72 +23,83 @@ B is an optional set of flags. =head1 NOTES -Any of the following flags (ored together) can be passed in the B parameter. +Any of the following flags (ored together) can be passed in the B +parameter. Many S/MIME clients expect the signed content to include valid MIME headers. If the B flag is set MIME headers for type B are prepended to the data. If B 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 -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 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 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 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 is set then no +authenticatedAttributes will be used. If B is set then just +the SMIMECapabilities are omitted. -The data being signed is included in the PKCS7 structure, unless B -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 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 is set then no authenticatedAttributes -will be used. If B is set then just the SMIMECapabilities are -omitted. +If the flags B is set then the returned B structure is +just initialized ready to perform the signing operation. The signing is however +B performed and the data to be signed is not read from the B +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 flag is set a partial B structure is output to +which additional signers and capabilities can be added before finalization. -If the flags B is set then the returned B structure -is just initialized ready to perform the signing operation. The signing -is however B performed and the data to be signed is not read from -the B 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 B also be set. =head1 NOTES -Currently the flag B is only supported for detached -data. If this flag is set the returned B structure is B -complete and outputting its contents via a function that does not -properly finalize the B structure will give unpredictable -results. +If the flag B is set the returned B structure is B +complete and outputting its contents via a function that does not properly +finalize the B 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 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 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, B and B parameters can all be +B if the B flag is set. One or more signers can be added +using the function B. B 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 and B 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 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 and B parameters must +B 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, L PKCS7_sign() was added to OpenSSL 0.9.5 -The B flag was added in OpenSSL 0.9.8 +The B flag was added in OpenSSL 0.9.9 + +The B flag was added in OpenSSL 0.9.9 =cut -- 2.25.1