diff options
Diffstat (limited to 'src/lib/libcrypto/doc/PKCS7_sign.pod')
-rw-r--r-- | src/lib/libcrypto/doc/PKCS7_sign.pod | 115 |
1 files changed, 65 insertions, 50 deletions
diff --git a/src/lib/libcrypto/doc/PKCS7_sign.pod b/src/lib/libcrypto/doc/PKCS7_sign.pod index ffd0c734b0..64a35144f8 100644 --- a/src/lib/libcrypto/doc/PKCS7_sign.pod +++ b/src/lib/libcrypto/doc/PKCS7_sign.pod | |||
@@ -6,14 +6,16 @@ PKCS7_sign - create a PKCS#7 signedData structure | |||
6 | 6 | ||
7 | =head1 SYNOPSIS | 7 | =head1 SYNOPSIS |
8 | 8 | ||
9 | PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags); | 9 | #include <openssl/pkcs7.h> |
10 | |||
11 | PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags); | ||
10 | 12 | ||
11 | =head1 DESCRIPTION | 13 | =head1 DESCRIPTION |
12 | 14 | ||
13 | PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> | 15 | PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> is |
14 | is the certificate to sign with, B<pkey> is the corresponsding private key. | 16 | the certificate to sign with, B<pkey> is the corresponsding private key. |
15 | B<certs> is an optional additional set of certificates to include in the | 17 | B<certs> is an optional additional set of certificates to include in the PKCS#7 |
16 | PKCS#7 structure (for example any intermediate CAs in the chain). | 18 | structure (for example any intermediate CAs in the chain). |
17 | 19 | ||
18 | The data to be signed is read from BIO B<data>. | 20 | The data to be signed is read from BIO B<data>. |
19 | 21 | ||
@@ -21,72 +23,83 @@ B<flags> is an optional set of flags. | |||
21 | 23 | ||
22 | =head1 NOTES | 24 | =head1 NOTES |
23 | 25 | ||
24 | Any of the following flags (ored together) can be passed in the B<flags> parameter. | 26 | Any of the following flags (ored together) can be passed in the B<flags> |
27 | parameter. | ||
25 | 28 | ||
26 | Many S/MIME clients expect the signed content to include valid MIME headers. If | 29 | Many S/MIME clients expect the signed content to include valid MIME headers. If |
27 | the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended | 30 | the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended |
28 | to the data. | 31 | to the data. |
29 | 32 | ||
30 | If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the | 33 | If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the |
31 | PKCS7 structure, the signer's certificate must still be supplied in the B<signcert> | 34 | PKCS7 structure, the signer's certificate must still be supplied in the |
32 | parameter though. This can reduce the size of the signature if the signers certificate | 35 | B<signcert> parameter though. This can reduce the size of the signature if the |
33 | can be obtained by other means: for example a previously signed message. | 36 | signers certificate can be obtained by other means: for example a previously |
34 | 37 | signed message. | |
35 | The data being signed is included in the PKCS7 structure, unless B<PKCS7_DETACHED> | 38 | |
36 | is set in which case it is omitted. This is used for PKCS7 detached signatures | 39 | The data being signed is included in the PKCS7 structure, unless |
37 | which are used in S/MIME plaintext signed messages for example. | 40 | B<PKCS7_DETACHED> is set in which case it is omitted. This is used for PKCS7 |
41 | detached signatures which are used in S/MIME plaintext signed messages for | ||
42 | example. | ||
43 | |||
44 | Normally the supplied content is translated into MIME canonical format (as | ||
45 | required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation | ||
46 | occurs. This option should be used if the supplied data is in binary format | ||
47 | otherwise the translation will corrupt it. | ||
48 | |||
49 | The signedData structure includes several PKCS#7 autenticatedAttributes | ||
50 | including the signing time, the PKCS#7 content type and the supported list of | ||
51 | ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no | ||
52 | authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just | ||
53 | the SMIMECapabilities are omitted. | ||
38 | 54 | ||
39 | Normally the supplied content is translated into MIME canonical format (as required | 55 | If present the SMIMECapabilities attribute indicates support for the following |
40 | by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation occurs. This | 56 | algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of |
41 | option should be used if the supplied data is in binary format otherwise the translation | 57 | these algorithms is disabled then it will not be included. |
42 | will corrupt it. | ||
43 | 58 | ||
44 | The signedData structure includes several PKCS#7 autenticatedAttributes including | 59 | If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is |
45 | the signing time, the PKCS#7 content type and the supported list of ciphers in | 60 | just initialized ready to perform the signing operation. The signing is however |
46 | an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no authenticatedAttributes | 61 | B<not> performed and the data to be signed is not read from the B<data> |
47 | will be used. If B<PKCS7_NOSMIMECAP> is set then just the SMIMECapabilities are | 62 | parameter. Signing is deferred until after the data has been written. In this |
48 | omitted. | 63 | way data can be signed in a single pass. |
49 | 64 | ||
50 | If present the SMIMECapabilities attribute indicates support for the following | 65 | If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to |
51 | algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any | 66 | which additional signers and capabilities can be added before finalization. |
52 | of these algorithms is disabled then it will not be included. | ||
53 | 67 | ||
54 | If the flags B<PKCS7_PARTSIGN> is set then the returned B<PKCS7> structure | ||
55 | is just initialized ready to perform the signing operation. The signing | ||
56 | is however B<not> performed and the data to be signed is not read from | ||
57 | the B<data> parameter. Signing is deferred until after the data has been | ||
58 | written. In this way data can be signed in a single pass. Currently the | ||
59 | flag B<PKCS7_DETACHED> B<must> also be set. | ||
60 | 68 | ||
61 | =head1 NOTES | 69 | =head1 NOTES |
62 | 70 | ||
63 | Currently the flag B<PKCS7_PARTSIGN> is only supported for detached | 71 | If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not> |
64 | data. If this flag is set the returned B<PKCS7> structure is B<not> | 72 | complete and outputting its contents via a function that does not properly |
65 | complete and outputting its contents via a function that does not | 73 | finalize the B<PKCS7> structure will give unpredictable results. |
66 | properly finalize the B<PKCS7> structure will give unpredictable | ||
67 | results. | ||
68 | 74 | ||
69 | At present only the SMIME_write_PKCS7() function properly finalizes the | 75 | Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), |
70 | structure. | 76 | PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization |
77 | can be performed by obtaining the streaming ASN1 B<BIO> directly using | ||
78 | BIO_new_PKCS7(). | ||
71 | 79 | ||
72 | =head1 BUGS | 80 | If a signer is specified it will use the default digest for the signing |
81 | algorithm. This is B<SHA1> for both RSA and DSA keys. | ||
82 | |||
83 | In OpenSSL 1.0.0 the B<certs>, B<signcert> and B<pkey> parameters can all be | ||
84 | B<NULL> if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added | ||
85 | using the function B<PKCS7_sign_add_signer()>. B<PKCS7_final()> must also be | ||
86 | called to finalize the structure if streaming is not enabled. Alternative | ||
87 | signing digests can also be specified using this method. | ||
73 | 88 | ||
74 | PKCS7_sign() is somewhat limited. It does not support multiple signers, some | 89 | In OpenSSL 1.0.0 if B<signcert> and B<pkey> are NULL then a certificates only |
75 | advanced attributes such as counter signatures are not supported. | 90 | PKCS#7 structure is output. |
76 | 91 | ||
77 | The SHA1 digest algorithm is currently always used. | 92 | In versions of OpenSSL before 1.0.0 the B<signcert> and B<pkey> parameters must |
93 | B<NOT> be NULL. | ||
78 | 94 | ||
79 | When the signed data is not detached it will be stored in memory within the | 95 | =head1 BUGS |
80 | B<PKCS7> structure. This effectively limits the size of messages which can be | ||
81 | signed due to memory restraints. There should be a way to sign data without | ||
82 | having to hold it all in memory, this would however require fairly major | ||
83 | revisions of the OpenSSL ASN1 code. | ||
84 | 96 | ||
97 | Some advanced attributes such as counter signatures are not supported. | ||
85 | 98 | ||
86 | =head1 RETURN VALUES | 99 | =head1 RETURN VALUES |
87 | 100 | ||
88 | PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error occurred. | 101 | PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error |
89 | The error can be obtained from ERR_get_error(3). | 102 | occurred. The error can be obtained from ERR_get_error(3). |
90 | 103 | ||
91 | =head1 SEE ALSO | 104 | =head1 SEE ALSO |
92 | 105 | ||
@@ -96,6 +109,8 @@ L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)> | |||
96 | 109 | ||
97 | PKCS7_sign() was added to OpenSSL 0.9.5 | 110 | PKCS7_sign() was added to OpenSSL 0.9.5 |
98 | 111 | ||
99 | The B<PKCS7_PARTSIGN> flag was added in OpenSSL 0.9.8 | 112 | The B<PKCS7_PARTIAL> flag was added in OpenSSL 1.0.0 |
113 | |||
114 | The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0 | ||
100 | 115 | ||
101 | =cut | 116 | =cut |