X-Git-Url: https://gitweb.dragonflybsd.org/dragonfly.git/blobdiff_plain/5e4280d05cad56ce9c9d259d23e209d60609f371..0118528260d190c273d4e793f523e81db6dd8587:/secure/lib/libcrypto/man/PKCS7_encrypt.3

diff --git a/secure/lib/libcrypto/man/PKCS7_encrypt.3 b/secure/lib/libcrypto/man/PKCS7_encrypt.3
index 1415fa57c3..961c299ace 100644
--- a/secure/lib/libcrypto/man/PKCS7_encrypt.3
+++ b/secure/lib/libcrypto/man/PKCS7_encrypt.3
@@ -1,15 +1,7 @@
-.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
+.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
 .de Sp \" Vertical space (when we can't use .PP)
 .if t .sp .5v
 .if n .sp
@@ -53,7 +45,7 @@
 .el       .ds Aq '
 .\"
 .\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
 .ie \nF \{\
@@ -132,7 +124,7 @@
 .\" ========================================================================
 .\"
 .IX Title "PKCS7_encrypt 3"
-.TH PKCS7_encrypt 3 "2010-02-27" "0.9.8m" "OpenSSL"
+.TH PKCS7_encrypt 3 "2010-06-01" "1.0.0a" "OpenSSL"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -141,7 +133,11 @@
 PKCS7_encrypt \- create a PKCS#7 envelopedData structure
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
-\&\s-1PKCS7\s0 *PKCS7_encrypt(\s-1STACK_OF\s0(X509) *certs, \s-1BIO\s0 *in, const \s-1EVP_CIPHER\s0 *cipher, int flags);
+.Vb 1
+\& #include <openssl/pkcs7.h>
+\&
+\& PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags);
+.Ve
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 \&\fIPKCS7_encrypt()\fR creates and returns a PKCS#7 envelopedData structure. \fBcerts\fR
@@ -149,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.
+.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
-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.
+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.