]>
Commit | Line | Data |
---|---|---|
e33ffaca DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
1bc74519 | 5 | CMS_sign - create a CMS SignedData structure |
e33ffaca DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/cms.h> | |
10 | ||
e9b77246 BB |
11 | CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, |
12 | BIO *data, unsigned int flags); | |
e33ffaca DSH |
13 | |
14 | =head1 DESCRIPTION | |
15 | ||
360bb61d | 16 | CMS_sign() creates and returns a CMS SignedData structure. B<signcert> is |
c420fab5 | 17 | the certificate to sign with, B<pkey> is the corresponding private key. |
e33ffaca DSH |
18 | B<certs> is an optional additional set of certificates to include in the CMS |
19 | structure (for example any intermediate CAs in the chain). Any or all of | |
20 | these parameters can be B<NULL>, see B<NOTES> below. | |
21 | ||
22 | The data to be signed is read from BIO B<data>. | |
23 | ||
24 | B<flags> is an optional set of flags. | |
25 | ||
26 | =head1 NOTES | |
27 | ||
28 | Any of the following flags (ored together) can be passed in the B<flags> | |
29 | parameter. | |
30 | ||
31 | Many S/MIME clients expect the signed content to include valid MIME headers. If | |
32 | the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are prepended | |
33 | to the data. | |
34 | ||
35 | If B<CMS_NOCERTS> is set the signer's certificate will not be included in the | |
36 | CMS_ContentInfo structure, the signer's certificate must still be supplied in | |
37 | the B<signcert> parameter though. This can reduce the size of the signature if | |
38 | the signers certificate can be obtained by other means: for example a | |
39 | previously signed message. | |
40 | ||
41 | The data being signed is included in the CMS_ContentInfo structure, unless | |
42 | B<CMS_DETACHED> is set in which case it is omitted. This is used for | |
43 | CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed | |
44 | messages for example. | |
45 | ||
46 | Normally the supplied content is translated into MIME canonical format (as | |
47 | required by the S/MIME specifications) if B<CMS_BINARY> is set no translation | |
48 | occurs. This option should be used if the supplied data is in binary format | |
49 | otherwise the translation will corrupt it. | |
50 | ||
360bb61d | 51 | The SignedData structure includes several CMS signedAttributes including the |
e33ffaca DSH |
52 | signing time, the CMS content type and the supported list of ciphers in an |
53 | SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes | |
54 | will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are | |
55 | omitted. | |
56 | ||
57 | If present the SMIMECapabilities attribute indicates support for the following | |
38d3a738 DSH |
58 | algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 |
59 | bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. | |
60 | If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is | |
61 | not loaded. | |
e33ffaca DSH |
62 | |
63 | OpenSSL will by default identify signing certificates using issuer name | |
64 | and serial number. If B<CMS_USE_KEYID> is set it will use the subject key | |
65 | identifier value instead. An error occurs if the signing certificate does not | |
66 | have a subject key identifier extension. | |
67 | ||
68 | If the flags B<CMS_STREAM> is set then the returned B<CMS_ContentInfo> | |
69 | structure is just initialized ready to perform the signing operation. The | |
70 | signing is however B<not> performed and the data to be signed is not read from | |
71 | the B<data> parameter. Signing is deferred until after the data has been | |
72 | written. In this way data can be signed in a single pass. | |
73 | ||
74 | If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is | |
75 | output to which additional signers and capabilities can be added before | |
76 | finalization. | |
77 | ||
78 | If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is | |
79 | B<not> complete and outputting its contents via a function that does not | |
80 | properly finalize the B<CMS_ContentInfo> structure will give unpredictable | |
81 | results. | |
82 | ||
9034c56c | 83 | Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), |
e33ffaca DSH |
84 | PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization |
85 | can be performed by obtaining the streaming ASN1 B<BIO> directly using | |
86 | BIO_new_CMS(). | |
87 | ||
88 | If a signer is specified it will use the default digest for the signing | |
89 | algorithm. This is B<SHA1> for both RSA and DSA keys. | |
90 | ||
91 | If B<signcert> and B<pkey> are NULL then a certificates only CMS structure is | |
92 | output. | |
93 | ||
94 | The function CMS_sign() is a basic CMS signing function whose output will be | |
95 | suitable for many purposes. For finer control of the output format the | |
96 | B<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> and the | |
97 | B<CMS_PARTIAL> flag set. Then one or more signers can be added using the | |
38d3a738 | 98 | function CMS_sign_add1_signer(), non default digests can be used and custom |
35cb565a | 99 | attributes added. CMS_final() must then be called to finalize the |
1bc74519 | 100 | structure if streaming is not enabled. |
e33ffaca DSH |
101 | |
102 | =head1 BUGS | |
103 | ||
38d3a738 | 104 | Some attributes such as counter signatures are not supported. |
e33ffaca DSH |
105 | |
106 | =head1 RETURN VALUES | |
107 | ||
108 | CMS_sign() returns either a valid CMS_ContentInfo structure or NULL if an error | |
38d3a738 | 109 | occurred. The error can be obtained from ERR_get_error(3). |
e33ffaca DSH |
110 | |
111 | =head1 SEE ALSO | |
112 | ||
9b86974e | 113 | L<ERR_get_error(3)>, L<CMS_verify(3)> |
e33ffaca DSH |
114 | |
115 | =head1 HISTORY | |
116 | ||
e33ffaca | 117 | The B<CMS_STREAM> flag is only supported for detached data in OpenSSL 0.9.8, |
fb552ac6 | 118 | it is supported for embedded data in OpenSSL 1.0.0 and later. |
e33ffaca | 119 | |
e2f92610 RS |
120 | =head1 COPYRIGHT |
121 | ||
122 | Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. | |
123 | ||
4746f25a | 124 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
125 | this file except in compliance with the License. You can obtain a copy |
126 | in the file LICENSE in the source distribution or at | |
127 | L<https://www.openssl.org/source/license.html>. | |
128 | ||
129 | =cut |