diff options
Diffstat (limited to 'secure/lib/libcrypto/man/PKCS7_encrypt.3')
-rw-r--r-- | secure/lib/libcrypto/man/PKCS7_encrypt.3 | 57 |
1 files changed, 35 insertions, 22 deletions
diff --git a/secure/lib/libcrypto/man/PKCS7_encrypt.3 b/secure/lib/libcrypto/man/PKCS7_encrypt.3 index 1ded608..5c7d7d8 100644 --- a/secure/lib/libcrypto/man/PKCS7_encrypt.3 +++ b/secure/lib/libcrypto/man/PKCS7_encrypt.3 @@ -124,7 +124,7 @@ .\" ======================================================================== .\" .IX Title "PKCS7_encrypt 3" -.TH PKCS7_encrypt 3 "2012-05-10" "0.9.8x" "OpenSSL" +.TH PKCS7_encrypt 3 "2012-05-10" "1.0.1c" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -145,44 +145,57 @@ is a list of recipient certificates. \fBin\fR is the content to be encrypted. \&\fBcipher\fR is the symmetric cipher to use. \fBflags\fR is an optional set of flags. .SH "NOTES" .IX Header "NOTES" -Only \s-1RSA\s0 keys are supported in PKCS#7 and envelopedData so the recipient certificates -supplied to this function must all contain \s-1RSA\s0 public keys, though they do not have to -be signed using the \s-1RSA\s0 algorithm. +Only \s-1RSA\s0 keys are supported in PKCS#7 and envelopedData so the recipient +certificates supplied to this function must all contain \s-1RSA\s0 public keys, though +they do not have to be signed using the \s-1RSA\s0 algorithm. .PP -\&\fIEVP_des_ede3_cbc()\fR (triple \s-1DES\s0) is the algorithm of choice for S/MIME use because -most clients will support it. +\&\fIEVP_des_ede3_cbc()\fR (triple \s-1DES\s0) is the algorithm of choice for S/MIME use +because most clients will support it. .PP -Some old \*(L"export grade\*(R" clients may only support weak encryption using 40 or 64 bit -\&\s-1RC2\s0. These can be used by passing \fIEVP_rc2_40_cbc()\fR and \fIEVP_rc2_64_cbc()\fR respectively. +Some old \*(L"export grade\*(R" clients may only support weak encryption using 40 or 64 +bit \s-1RC2\s0. These can be used by passing \fIEVP_rc2_40_cbc()\fR and \fIEVP_rc2_64_cbc()\fR +respectively. .PP -The algorithm passed in the \fBcipher\fR parameter must support \s-1ASN1\s0 encoding of its -parameters. +The algorithm passed in the \fBcipher\fR parameter must support \s-1ASN1\s0 encoding of +its parameters. .PP -Many browsers implement a \*(L"sign and encrypt\*(R" option which is simply an S/MIME +Many browsers implement a \*(L"sign and encrypt\*(R" 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 \s-1BIO\s0 and passing it to \&\fIPKCS7_encrypt()\fR. .PP The following flags can be passed in the \fBflags\fR parameter. .PP -If the \fB\s-1PKCS7_TEXT\s0\fR flag is set \s-1MIME\s0 headers for type \fBtext/plain\fR are prepended -to the data. +If the \fB\s-1PKCS7_TEXT\s0\fR flag is set \s-1MIME\s0 headers for type \fBtext/plain\fR are +prepended to the data. .PP -Normally the supplied content is translated into \s-1MIME\s0 canonical format (as required -by the S/MIME specifications) if \fB\s-1PKCS7_BINARY\s0\fR 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 \fB\s-1PKCS7_BINARY\s0\fR is set then \fB\s-1PKCS7_TEXT\s0\fR is ignored. +Normally the supplied content is translated into \s-1MIME\s0 canonical format (as +required by the S/MIME specifications) if \fB\s-1PKCS7_BINARY\s0\fR 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 \fB\s-1PKCS7_BINARY\s0\fR is set then +\&\fB\s-1PKCS7_TEXT\s0\fR is ignored. +.PP +If the \fB\s-1PKCS7_STREAM\s0\fR flag is set a partial \fB\s-1PKCS7\s0\fR structure is output +suitable for streaming I/O: no data is read from the \s-1BIO\s0 \fBin\fR. +.SH "NOTES" +.IX Header "NOTES" +If the flag \fB\s-1PKCS7_STREAM\s0\fR is set the returned \fB\s-1PKCS7\s0\fR structure is \fBnot\fR +complete and outputting its contents via a function that does not +properly finalize the \fB\s-1PKCS7\s0\fR structure will give unpredictable +results. +.PP +Several functions including \fISMIME_write_PKCS7()\fR, \fIi2d_PKCS7_bio_stream()\fR, +\&\fIPEM_write_bio_PKCS7_stream()\fR finalize the structure. Alternatively finalization +can be performed by obtaining the streaming \s-1ASN1\s0 \fB\s-1BIO\s0\fR directly using +\&\fIBIO_new_PKCS7()\fR. .SH "RETURN VALUES" .IX Header "RETURN VALUES" -\&\fIPKCS7_encrypt()\fR returns either a valid \s-1PKCS7\s0 structure or \s-1NULL\s0 if an error occurred. +\&\fIPKCS7_encrypt()\fR returns either a \s-1PKCS7\s0 structure or \s-1NULL\s0 if an error occurred. The error can be obtained from \fIERR_get_error\fR\|(3). -.SH "BUGS" -.IX Header "BUGS" -The lack of single pass processing and need to hold all data in memory as -mentioned in \fIPKCS7_sign()\fR also applies to \fIPKCS7_verify()\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIERR_get_error\fR\|(3), \fIPKCS7_decrypt\fR\|(3) .SH "HISTORY" .IX Header "HISTORY" \&\fIPKCS7_decrypt()\fR was added to OpenSSL 0.9.5 +The \fB\s-1PKCS7_STREAM\s0\fR flag was first supported in OpenSSL 1.0.0. |