| Index: openssl/doc/crypto/PKCS7_encrypt.pod
|
| ===================================================================
|
| --- openssl/doc/crypto/PKCS7_encrypt.pod (revision 105093)
|
| +++ openssl/doc/crypto/PKCS7_encrypt.pod (working copy)
|
| @@ -18,44 +18,56 @@
|
|
|
| =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.
|
|
|
| +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>.
|
| +
|
| +=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.
|
| +
|
| +Several functions including SMIME_write_PKCS7(), i2d_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 RETURN VALUES
|
|
|
| -PKCS7_encrypt() returns either a valid PKCS7 structure or NULL if an error occurred.
|
| +PKCS7_encrypt() returns either a PKCS7 structure or NULL if an error occurred.
|
| The error can be obtained from ERR_get_error(3).
|
|
|
| -=head1 BUGS
|
| -
|
| -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 SEE ALSO
|
|
|
| L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>
|
| @@ -63,5 +75,6 @@
|
| =head1 HISTORY
|
|
|
| PKCS7_decrypt() was added to OpenSSL 0.9.5
|
| +The B<PKCS7_STREAM> flag was first supported in OpenSSL 1.0.0.
|
|
|
| =cut
|
|
|