diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2007-04-13 12:57:48 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2007-04-13 12:57:48 +0000 |
commit | 4cfb986f279eab2479b7b818bc1e4c3fe63849ef (patch) | |
tree | ad49fb7ff969b7b7650ee075c84fd3ef3ab61f98 /doc | |
parent | 9cfc8a9d5cb95c44251eff88d794482f8e413820 (diff) | |
download | openssl-4cfb986f279eab2479b7b818bc1e4c3fe63849ef.tar.gz |
Update docs.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/PKCS7_encrypt.pod | 57 | ||||
-rw-r--r-- | 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<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 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<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 |