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