diff options
author | jkim <jkim@FreeBSD.org> | 2012-07-12 19:30:53 +0000 |
---|---|---|
committer | jkim <jkim@FreeBSD.org> | 2012-07-12 19:30:53 +0000 |
commit | e393e47b1e23744a7d0ed999afb5d137070f5f8f (patch) | |
tree | 9739a803477c4610ec6628d914bdcc55fbb3602a /secure/lib/libcrypto/man/PKCS7_sign.3 | |
parent | a8b00dea2cde4c3d96e6ed1de530ddff21012266 (diff) | |
parent | 532b4084cb8cac5e6d91d42aa6a497dd4ba4a4f5 (diff) | |
download | FreeBSD-src-e393e47b1e23744a7d0ed999afb5d137070f5f8f.zip FreeBSD-src-e393e47b1e23744a7d0ed999afb5d137070f5f8f.tar.gz |
Merge OpenSSL 1.0.1c.
Approved by: benl (maintainer)
Diffstat (limited to 'secure/lib/libcrypto/man/PKCS7_sign.3')
-rw-r--r-- | secure/lib/libcrypto/man/PKCS7_sign.3 | 115 |
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 |