1 files changed, 64 insertions, 51 deletions
diff --git a/secure/lib/libcrypto/man/PKCS7_sign.3 b/secure/lib/libcrypto/man/PKCS7_sign.3
index 4a74d95..6a32613 100644
--- a/secure/lib/libcrypto/man/PKCS7_sign.3
+++ b/secure/lib/libcrypto/man/PKCS7_sign.3
@@ -124,7 +124,7 @@
 .\" ========================================================================
 .\"
 .IX Title "PKCS7_sign 3"
-.TH PKCS7_sign 3 "2012-05-10" "0.9.8x" "OpenSSL"
+.TH PKCS7_sign 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
@@ -140,78 +140,89 @@ PKCS7_sign \- create a PKCS#7 signedData structure
 .Ve
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
-\&\fIPKCS7_sign()\fR creates and returns a PKCS#7 signedData structure. \fBsigncert\fR
-is the certificate to sign with, \fBpkey\fR is the corresponsding private key.
-\&\fBcerts\fR is an optional additional set of certificates to include in the
-PKCS#7 structure (for example any intermediate CAs in the chain).
+\&\fIPKCS7_sign()\fR creates and returns a PKCS#7 signedData structure. \fBsigncert\fR is
+the certificate to sign with, \fBpkey\fR is the corresponsding private key.
+\&\fBcerts\fR is an optional additional set of certificates to include in the PKCS#7
+structure (for example any intermediate CAs in the chain).
 .PP
 The data to be signed is read from \s-1BIO\s0 \fBdata\fR.
 .PP
 \&\fBflags\fR is an optional set of flags.
 .SH "NOTES"
 .IX Header "NOTES"
-Any of the following flags (ored together) can be passed in the \fBflags\fR parameter.
+Any of the following flags (ored together) can be passed in the \fBflags\fR
+parameter.
 .PP
 Many S/MIME clients expect the signed content to include valid \s-1MIME\s0 headers. 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
 If \fB\s-1PKCS7_NOCERTS\s0\fR is set the signer's certificate will not be included in the
-\&\s-1PKCS7\s0 structure, the signer's certificate must still be supplied in the \fBsigncert\fR
-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.
+\&\s-1PKCS7\s0 structure, the signer's certificate must still be supplied in the
+\&\fBsigncert\fR 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.
 .PP
-The data being signed is included in the \s-1PKCS7\s0 structure, unless \fB\s-1PKCS7_DETACHED\s0\fR 
-is set in which case it is omitted. This is used for \s-1PKCS7\s0 detached signatures
-which are used in S/MIME plaintext signed messages for example.
+The data being signed is included in the \s-1PKCS7\s0 structure, unless
+\&\fB\s-1PKCS7_DETACHED\s0\fR is set in which case it is omitted. This is used for \s-1PKCS7\s0
+detached signatures which are used in S/MIME plaintext signed messages for
+example.
 .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.
+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.
 .PP
-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 \fB\s-1PKCS7_NOATTR\s0\fR is set then no authenticatedAttributes
-will be used. If \fB\s-1PKCS7_NOSMIMECAP\s0\fR is set then just the SMIMECapabilities are
-omitted.
+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 \fB\s-1PKCS7_NOATTR\s0\fR is set then no
+authenticatedAttributes will be used. If \fB\s-1PKCS7_NOSMIMECAP\s0\fR is set then just
+the SMIMECapabilities are omitted.
 .PP
 If present the SMIMECapabilities attribute indicates support for the following
-algorithms: triple \s-1DES\s0, 128 bit \s-1RC2\s0, 64 bit \s-1RC2\s0, \s-1DES\s0 and 40 bit \s-1RC2\s0. If any
-of these algorithms is disabled then it will not be included.
-.PP
-If the flags \fB\s-1PKCS7_PARTSIGN\s0\fR is set then the returned \fB\s-1PKCS7\s0\fR structure
-is just initialized ready to perform the signing operation. The signing
-is however \fBnot\fR performed and the data to be signed is not read from
-the \fBdata\fR 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 \fB\s-1PKCS7_DETACHED\s0\fR \fBmust\fR also be set.
+algorithms: triple \s-1DES\s0, 128 bit \s-1RC2\s0, 64 bit \s-1RC2\s0, \s-1DES\s0 and 40 bit \s-1RC2\s0. If any of
+these algorithms is disabled then it will not be included.
+.PP
+If the flags \fB\s-1PKCS7_STREAM\s0\fR is set then the returned \fB\s-1PKCS7\s0\fR structure is
+just initialized ready to perform the signing operation. The signing is however
+\&\fBnot\fR performed and the data to be signed is not read from the \fBdata\fR
+parameter. Signing is deferred until after the data has been written. In this
+way data can be signed in a single pass.
+.PP
+If the \fB\s-1PKCS7_PARTIAL\s0\fR flag is set a partial \fB\s-1PKCS7\s0\fR structure is output to
+which additional signers and capabilities can be added before finalization.
 .SH "NOTES"
 .IX Header "NOTES"
-Currently the flag \fB\s-1PKCS7_PARTSIGN\s0\fR is only supported for detached
-data. If this flag 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
-At present only the \fISMIME_write_PKCS7()\fR function properly finalizes the
-structure.
-.SH "BUGS"
-.IX Header "BUGS"
-\&\fIPKCS7_sign()\fR is somewhat limited. It does not support multiple signers, some
-advanced attributes such as counter signatures are not supported.
+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.
 .PP
-The \s-1SHA1\s0 digest algorithm is currently always used.
+If a signer is specified it will use the default digest for the signing
+algorithm. This is \fB\s-1SHA1\s0\fR for both \s-1RSA\s0 and \s-1DSA\s0 keys.
 .PP
-When the signed data is not detached it will be stored in memory within the
-\&\fB\s-1PKCS7\s0\fR 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 \s-1ASN1\s0 code.
+In OpenSSL 1.0.0 the \fBcerts\fR, \fBsigncert\fR and \fBpkey\fR parameters can all be
+\&\fB\s-1NULL\s0\fR if the \fB\s-1PKCS7_PARTIAL\s0\fR flag is set. One or more signers can be added
+using the function \fB\f(BIPKCS7_sign_add_signer()\fB\fR. \fB\f(BIPKCS7_final()\fB\fR must also be
+called to finalize the structure if streaming is not enabled. Alternative
+signing digests can also be specified using this method.
+.PP
+In OpenSSL 1.0.0 if \fBsigncert\fR and \fBpkey\fR are \s-1NULL\s0 then a certificates only
+PKCS#7 structure is output.
+.PP
+In versions of OpenSSL before 1.0.0 the \fBsigncert\fR and \fBpkey\fR parameters must
+\&\fB\s-1NOT\s0\fR be \s-1NULL\s0.
+.SH "BUGS"
+.IX Header "BUGS"
+Some advanced attributes such as counter signatures are not supported.
 .SH "RETURN VALUES"
 .IX Header "RETURN VALUES"
-\&\fIPKCS7_sign()\fR returns either a valid \s-1PKCS7\s0 structure or \s-1NULL\s0 if an error occurred.
-The error can be obtained from \fIERR_get_error\fR\|(3).
+\&\fIPKCS7_sign()\fR returns either a valid \s-1PKCS7\s0 structure or \s-1NULL\s0 if an error
+occurred.  The error can be obtained from \fIERR_get_error\fR\|(3).
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"
 \&\fIERR_get_error\fR\|(3), \fIPKCS7_verify\fR\|(3)
@@ -219,4 +230,6 @@ The error can be obtained from \fIERR_get_error\fR\|(3).
 .IX Header "HISTORY"
 \&\fIPKCS7_sign()\fR was added to OpenSSL 0.9.5
 .PP
-The \fB\s-1PKCS7_PARTSIGN\s0\fR flag was added in OpenSSL 0.9.8
+The \fB\s-1PKCS7_PARTIAL\s0\fR flag was added in OpenSSL 1.0.0
+.PP
+The \fB\s-1PKCS7_STREAM\s0\fR flag was added in OpenSSL 1.0.0