Update build for OpenSSL-1.0.0a.
[dragonfly.git] / secure / lib / libcrypto / man / PKCS7_sign.3
index eab32b0..4a413ea 100644 (file)
@@ -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 \{\
 .\" ========================================================================
 .\"
 .IX Title "PKCS7_sign 3"
-.TH PKCS7_sign 3 "2010-02-27" "0.9.8m" "OpenSSL"
+.TH PKCS7_sign 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
 PKCS7_sign \- create a PKCS#7 signedData structure
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
-\&\s-1PKCS7\s0 *PKCS7_sign(X509 *signcert, \s-1EVP_PKEY\s0 *pkey, \s-1STACK_OF\s0(X509) *certs, \s-1BIO\s0 *data, int flags);
+.Vb 1
+\& #include <openssl/pkcs7.h>
+\&
+\& PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags);
+.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
-The \s-1SHA1\s0 digest algorithm is currently always used.
+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
-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.
+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
+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)
@@ -223,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