]>
Commit | Line | Data |
---|---|---|
7122aafc DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
b6b66573 | 5 | openssl-cms - CMS utility |
7122aafc DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | B<openssl> B<cms> | |
169394d4 | 10 | [B<-help>] |
7122aafc DSH |
11 | [B<-encrypt>] |
12 | [B<-decrypt>] | |
13 | [B<-sign>] | |
7122aafc DSH |
14 | [B<-verify>] |
15 | [B<-cmsout>] | |
41f81a01 | 16 | [B<-resign>] |
e85d19c6 | 17 | [B<-cades>] |
41f81a01 DSH |
18 | [B<-data_create>] |
19 | [B<-data_out>] | |
20 | [B<-digest_create>] | |
21 | [B<-digest_verify>] | |
22 | [B<-compress>] | |
23 | [B<-uncompress>] | |
24 | [B<-EncryptedData_encrypt>] | |
25 | [B<-sign_receipt>] | |
e8769719 RS |
26 | [B<-verify_receipt> I<receipt>] |
27 | [B<-in> I<filename>] | |
28 | [B<-inform> B<DER>|B<PEM>|B<SMIME>] | |
29 | [B<-rctform> B<DER>|B<PEM>|B<SMIME>] | |
30 | [B<-out> I<filename>] | |
31 | [B<-outform> B<DER>|B<PEM>|B<SMIME>] | |
32 | [B<-stream>] | |
33 | [B<-indef>] | |
41f81a01 | 34 | [B<-noindef>] |
e8769719 RS |
35 | [B<-noindef>] |
36 | [B<-content> I<filename>] | |
41f81a01 DSH |
37 | [B<-text>] |
38 | [B<-noout>] | |
39 | [B<-print>] | |
e8769719 RS |
40 | [B<-CAfile> I<file>] |
41 | [B<-CApath> I<dir>] | |
40e2d76b MC |
42 | [B<-no-CAfile>] |
43 | [B<-no-CApath>] | |
e8769719 | 44 | [B<-attime> I<timestamp>] |
e42d84be HK |
45 | [B<-check_ss_sig>] |
46 | [B<-crl_check>] | |
47 | [B<-crl_check_all>] | |
48 | [B<-explicit_policy>] | |
49 | [B<-extended_crl>] | |
50 | [B<-ignore_critical>] | |
51 | [B<-inhibit_any>] | |
52 | [B<-inhibit_map>] | |
5a1f853b | 53 | [B<-no_check_time>] |
e42d84be | 54 | [B<-partial_chain>] |
e8769719 | 55 | [B<-policy> I<arg>] |
e42d84be HK |
56 | [B<-policy_check>] |
57 | [B<-policy_print>] | |
e8769719 | 58 | [B<-purpose> I<purpose>] |
e42d84be HK |
59 | [B<-suiteB_128>] |
60 | [B<-suiteB_128_only>] | |
61 | [B<-suiteB_192>] | |
6d3d5793 | 62 | [B<-trusted_first>] |
fa7b0111 | 63 | [B<-no_alt_chains>] |
e42d84be | 64 | [B<-use_deltas>] |
e8769719 RS |
65 | [B<-auth_level> I<num>] |
66 | [B<-verify_depth> I<num>] | |
67 | [B<-verify_email> I<email>] | |
68 | [B<-verify_hostname> I<hostname>] | |
69 | [B<-verify_ip> I<ip>] | |
70 | [B<-verify_name> I<name>] | |
e42d84be | 71 | [B<-x509_strict>] |
e8769719 RS |
72 | [B<-md> I<digest>] |
73 | [B<->I<cipher>] | |
41f81a01 | 74 | [B<-nointern>] |
e75138ab | 75 | [B<-noverify>] |
41f81a01 DSH |
76 | [B<-nocerts>] |
77 | [B<-noattr>] | |
78 | [B<-nosmimecap>] | |
79 | [B<-binary>] | |
2197494d | 80 | [B<-crlfeol>] |
847865d0 | 81 | [B<-asciicrlf>] |
41f81a01 | 82 | [B<-nodetach>] |
e8769719 RS |
83 | [B<-certfile> I<file>] |
84 | [B<-certsout> I<file>] | |
85 | [B<-signer> I<file>] | |
86 | [B<-recip> I<file>] | |
41f81a01 | 87 | [B<-keyid>] |
dfee8626 RS |
88 | [B<-receipt_request_all>] |
89 | [B<-receipt_request_first>] | |
e8769719 RS |
90 | [B<-receipt_request_from> I<emailaddress>] |
91 | [B<-receipt_request_to> I<emailaddress>] | |
41f81a01 | 92 | [B<-receipt_request_print>] |
e8769719 RS |
93 | [B<-secretkey> I<key>] |
94 | [B<-secretkeyid> I<id>] | |
95 | [B<-econtent_type> I<type>] | |
96 | [B<-inkey> I<file>] | |
97 | [B<-keyopt> I<name>:I<parameter>] | |
98 | [B<-passin> I<arg>] | |
99 | [B<-rand> I<file...>] | |
100 | [B<-writerand> I<file>] | |
101 | [B<-to> I<addr>] | |
102 | [B<-from> I<addr>] | |
103 | [B<-subject> I<subj>] | |
104 | [I<cert.pem ...>] | |
7122aafc | 105 | |
1738c0ce RS |
106 | =for comment ifdef des-wrap engine |
107 | ||
7122aafc DSH |
108 | =head1 DESCRIPTION |
109 | ||
110 | The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and | |
111 | verify, compress and uncompress S/MIME messages. | |
112 | ||
3dfda1a6 | 113 | =head1 OPTIONS |
7122aafc | 114 | |
41f81a01 DSH |
115 | There are fourteen operation options that set the type of operation to be |
116 | performed. The meaning of the other options varies according to the operation | |
7122aafc DSH |
117 | type. |
118 | ||
119 | =over 4 | |
120 | ||
169394d4 MR |
121 | =item B<-help> |
122 | ||
123 | Print out a usage message. | |
124 | ||
7122aafc DSH |
125 | =item B<-encrypt> |
126 | ||
c4de074e | 127 | Encrypt mail for the given recipient certificates. Input file is the message |
7122aafc DSH |
128 | to be encrypted. The output file is the encrypted mail in MIME format. The |
129 | actual CMS type is <B>EnvelopedData<B>. | |
130 | ||
2a9afa40 RS |
131 | Note that no revocation check is done for the recipient cert, so if that |
132 | key has been compromised, others may be able to decrypt the text. | |
133 | ||
7122aafc DSH |
134 | =item B<-decrypt> |
135 | ||
c4de074e | 136 | Decrypt mail using the supplied certificate and private key. Expects an |
7122aafc DSH |
137 | encrypted mail message in MIME format for the input file. The decrypted mail |
138 | is written to the output file. | |
139 | ||
0dd5b94a DSH |
140 | =item B<-debug_decrypt> |
141 | ||
c4de074e | 142 | This option sets the B<CMS_DEBUG_DECRYPT> flag. This option should be used |
0dd5b94a DSH |
143 | with caution: see the notes section below. |
144 | ||
7122aafc DSH |
145 | =item B<-sign> |
146 | ||
c4de074e | 147 | Sign mail using the supplied certificate and private key. Input file is |
7122aafc DSH |
148 | the message to be signed. The signed message in MIME format is written |
149 | to the output file. | |
150 | ||
151 | =item B<-verify> | |
152 | ||
c4de074e | 153 | Verify signed mail. Expects a signed mail message on input and outputs |
7122aafc DSH |
154 | the signed data. Both clear text and opaque signing is supported. |
155 | ||
156 | =item B<-cmsout> | |
157 | ||
c4de074e | 158 | Takes an input message and writes out a PEM encoded CMS structure. |
7122aafc DSH |
159 | |
160 | =item B<-resign> | |
161 | ||
c4de074e | 162 | Resign a message: take an existing message and one or more new signers. |
7122aafc | 163 | |
e85d19c6 AI |
164 | =item B<-cades> |
165 | ||
166 | Add an ESS signing-certificate or ESS signing-certificate-v2 signed-attribute to the SignerInfo, in order to make | |
167 | the signature comply with the requirements for a CAdES Basic Electronic Signature (CAdES-BES). See the NOTES | |
168 | section for more details. | |
169 | ||
7122aafc DSH |
170 | =item B<-data_create> |
171 | ||
172 | Create a CMS B<Data> type. | |
173 | ||
174 | =item B<-data_out> | |
175 | ||
176 | B<Data> type and output the content. | |
177 | ||
178 | =item B<-digest_create> | |
179 | ||
180 | Create a CMS B<DigestedData> type. | |
181 | ||
182 | =item B<-digest_verify> | |
183 | ||
184 | Verify a CMS B<DigestedData> type and output the content. | |
185 | ||
186 | =item B<-compress> | |
187 | ||
188 | Create a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib> | |
189 | support for this option to work, otherwise it will output an error. | |
190 | ||
191 | =item B<-uncompress> | |
192 | ||
193 | Uncompress a CMS B<CompressedData> type and output the content. OpenSSL must be | |
194 | compiled with B<zlib> support for this option to work, otherwise it will | |
195 | output an error. | |
196 | ||
197 | =item B<-EncryptedData_encrypt> | |
198 | ||
a9661e45 | 199 | Encrypt content using supplied symmetric key and algorithm using a CMS |
27b138e9 | 200 | B<EncryptedData> type and output the content. |
7122aafc | 201 | |
41f81a01 DSH |
202 | =item B<-sign_receipt> |
203 | ||
1bc74519 | 204 | Generate and output a signed receipt for the supplied message. The input |
41f81a01 DSH |
205 | message B<must> contain a signed receipt request. Functionality is otherwise |
206 | similar to the B<-sign> operation. | |
207 | ||
e8769719 | 208 | =item B<-verify_receipt> I<receipt> |
41f81a01 | 209 | |
1bc74519 | 210 | Verify a signed receipt in filename B<receipt>. The input message B<must> |
41f81a01 DSH |
211 | contain the original receipt request. Functionality is otherwise similar |
212 | to the B<-verify> operation. | |
213 | ||
e8769719 | 214 | =item B<-in> I<filename> |
7122aafc | 215 | |
c4de074e | 216 | The input message to be encrypted or signed or the message to be decrypted |
41f81a01 | 217 | or verified. |
7122aafc | 218 | |
e8769719 | 219 | =item B<-inform> B<DER>|B<PEM>|B<SMIME> |
7122aafc | 220 | |
c4de074e | 221 | This specifies the input format for the CMS structure. The default |
7122aafc DSH |
222 | is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> |
223 | format change this to expect PEM and DER format CMS structures | |
224 | instead. This currently only affects the input format of the CMS | |
225 | structure, if no CMS structure is being input (for example with | |
226 | B<-encrypt> or B<-sign>) this option has no effect. | |
227 | ||
e8769719 | 228 | =item B<-rctform> B<DER>|B<PEM>|B<SMIME> |
41f81a01 | 229 | |
c4de074e | 230 | Specify the format for a signed receipt for use with the B<-receipt_verify> |
41f81a01 DSH |
231 | operation. |
232 | ||
e8769719 | 233 | =item B<-out> I<filename> |
7122aafc | 234 | |
c4de074e | 235 | The message text that has been decrypted or verified or the output MIME |
7122aafc DSH |
236 | format message that has been signed or verified. |
237 | ||
e8769719 | 238 | =item B<-outform> B<DER>|B<PEM>|B<SMIME> |
7122aafc | 239 | |
c4de074e | 240 | This specifies the output format for the CMS structure. The default |
41f81a01 | 241 | is B<SMIME> which writes an S/MIME format message. B<PEM> and B<DER> |
7122aafc DSH |
242 | format change this to write PEM and DER format CMS structures |
243 | instead. This currently only affects the output format of the CMS | |
244 | structure, if no CMS structure is being output (for example with | |
245 | B<-verify> or B<-decrypt>) this option has no effect. | |
246 | ||
e8769719 | 247 | =item B<-stream>, B<-indef>, B<-noindef> |
7122aafc | 248 | |
c4de074e | 249 | The B<-stream> and B<-indef> options are equivalent and enable streaming I/O |
7122aafc DSH |
250 | for encoding operations. This permits single pass processing of data without |
251 | the need to hold the entire contents in memory, potentially supporting very | |
252 | large files. Streaming is automatically set for S/MIME signing with detached | |
253 | data if the output format is B<SMIME> it is currently off by default for all | |
254 | other operations. | |
255 | ||
256 | =item B<-noindef> | |
257 | ||
c4de074e | 258 | Disable streaming I/O where it would produce and indefinite length constructed |
7122aafc DSH |
259 | encoding. This option currently has no effect. In future streaming will be |
260 | enabled by default on all relevant operations and this option will disable it. | |
261 | ||
e8769719 | 262 | =item B<-content> I<filename> |
7122aafc DSH |
263 | |
264 | This specifies a file containing the detached content, this is only | |
265 | useful with the B<-verify> command. This is only usable if the CMS | |
266 | structure is using the detached signature form where the content is | |
267 | not included. This option will override any content if the input format | |
268 | is S/MIME and it uses the multipart/signed MIME content type. | |
269 | ||
270 | =item B<-text> | |
271 | ||
c4de074e | 272 | This option adds plain text (text/plain) MIME headers to the supplied |
7122aafc | 273 | message if encrypting or signing. If decrypting or verifying it strips |
1bc74519 | 274 | off text headers: if the decrypted or verified message is not of MIME |
7122aafc DSH |
275 | type text/plain then an error occurs. |
276 | ||
41f81a01 DSH |
277 | =item B<-noout> |
278 | ||
c4de074e | 279 | For the B<-cmsout> operation do not output the parsed CMS structure. This |
41f81a01 DSH |
280 | is useful when combined with the B<-print> option or if the syntax of the CMS |
281 | structure is being checked. | |
282 | ||
283 | =item B<-print> | |
284 | ||
c4de074e | 285 | For the B<-cmsout> operation print out all fields of the CMS structure. This |
41f81a01 DSH |
286 | is mainly useful for testing purposes. |
287 | ||
e8769719 | 288 | =item B<-CAfile> I<file> |
7122aafc | 289 | |
c4de074e | 290 | A file containing trusted CA certificates, only used with B<-verify>. |
7122aafc | 291 | |
e8769719 | 292 | =item B<-CApath> I<dir> |
7122aafc | 293 | |
c4de074e | 294 | A directory containing trusted CA certificates, only used with |
7122aafc | 295 | B<-verify>. This directory must be a standard certificate directory: that |
e8769719 | 296 | is a hash of each subject name (using C<x509 -hash>) should be linked |
7122aafc DSH |
297 | to each certificate. |
298 | ||
40e2d76b MC |
299 | =item B<-no-CAfile> |
300 | ||
301 | Do not load the trusted CA certificates from the default file location | |
302 | ||
303 | =item B<-no-CApath> | |
304 | ||
305 | Do not load the trusted CA certificates from the default directory location | |
306 | ||
e8769719 | 307 | =item B<-md> I<digest> |
7122aafc | 308 | |
c4de074e | 309 | Digest algorithm to use when signing or resigning. If not present then the |
7122aafc DSH |
310 | default digest algorithm for the signing key will be used (usually SHA1). |
311 | ||
e8769719 | 312 | =item B<->I<cipher> |
7122aafc | 313 | |
c4de074e | 314 | The encryption algorithm to use. For example triple DES (168 bits) - B<-des3> |
e5fa864f | 315 | or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the |
1bc74519 | 316 | EVP_get_cipherbyname() function) can also be used preceded by a dash, for |
dfee8626 | 317 | example B<-aes-128-cbc>. See L<enc(1)> for a list of ciphers |
e5fa864f | 318 | supported by your version of OpenSSL. |
7122aafc | 319 | |
1bc74519 | 320 | If not specified triple DES is used. Only used with B<-encrypt> and |
7122aafc DSH |
321 | B<-EncryptedData_create> commands. |
322 | ||
323 | =item B<-nointern> | |
324 | ||
c4de074e | 325 | When verifying a message normally certificates (if any) included in |
7122aafc DSH |
326 | the message are searched for the signing certificate. With this option |
327 | only the certificates specified in the B<-certfile> option are used. | |
328 | The supplied certificates can still be used as untrusted CAs however. | |
329 | ||
e75138ab | 330 | =item B<-noverify> |
7122aafc | 331 | |
c4de074e | 332 | Do not verify the signers certificate of a signed message. |
7122aafc DSH |
333 | |
334 | =item B<-nocerts> | |
335 | ||
c4de074e | 336 | When signing a message the signer's certificate is normally included |
7122aafc DSH |
337 | with this option it is excluded. This will reduce the size of the |
338 | signed message but the verifier must have a copy of the signers certificate | |
339 | available locally (passed using the B<-certfile> option for example). | |
340 | ||
341 | =item B<-noattr> | |
342 | ||
c4de074e | 343 | Normally when a message is signed a set of attributes are included which |
7122aafc DSH |
344 | include the signing time and supported symmetric algorithms. With this |
345 | option they are not included. | |
346 | ||
347 | =item B<-nosmimecap> | |
348 | ||
c4de074e | 349 | Exclude the list of supported algorithms from signed attributes, other options |
7122aafc DSH |
350 | such as signing time and content type are still included. |
351 | ||
352 | =item B<-binary> | |
353 | ||
c4de074e | 354 | Normally the input message is converted to "canonical" format which is |
7122aafc DSH |
355 | effectively using CR and LF as end of line: as required by the S/MIME |
356 | specification. When this option is present no translation occurs. This | |
357 | is useful when handling binary data which may not be in MIME format. | |
358 | ||
2197494d DSH |
359 | =item B<-crlfeol> |
360 | ||
c4de074e | 361 | Normally the output file uses a single B<LF> as end of line. When this |
2197494d DSH |
362 | option is present B<CRLF> is used instead. |
363 | ||
847865d0 DSH |
364 | =item B<-asciicrlf> |
365 | ||
c4de074e | 366 | When signing use ASCII CRLF format canonicalisation. This strips trailing |
847865d0 DSH |
367 | whitespace from all lines, deletes trailing blank lines at EOF and sets |
368 | the encapsulated content type. This option is normally used with detached | |
369 | content and an output signature format of DER. This option is not normally | |
370 | needed when verifying as it is enabled automatically if the encapsulated | |
371 | content format is detected. | |
372 | ||
7122aafc DSH |
373 | =item B<-nodetach> |
374 | ||
c4de074e | 375 | When signing a message use opaque signing: this form is more resistant |
7122aafc DSH |
376 | to translation by mail relays but it cannot be read by mail agents that |
377 | do not support S/MIME. Without this option cleartext signing with | |
378 | the MIME type multipart/signed is used. | |
379 | ||
e8769719 | 380 | =item B<-certfile> I<file> |
7122aafc | 381 | |
c4de074e | 382 | Allows additional certificates to be specified. When signing these will |
7122aafc DSH |
383 | be included with the message. When verifying these will be searched for |
384 | the signers certificates. The certificates should be in PEM format. | |
385 | ||
e8769719 | 386 | =item B<-certsout> I<file> |
4a954b56 | 387 | |
c4de074e | 388 | Any certificates contained in the message are written to B<file>. |
4a954b56 | 389 | |
e8769719 | 390 | =item B<-signer> I<file> |
7122aafc | 391 | |
c4de074e | 392 | A signing certificate when signing or resigning a message, this option can be |
7122aafc DSH |
393 | used multiple times if more than one signer is required. If a message is being |
394 | verified then the signers certificates will be written to this file if the | |
395 | verification was successful. | |
396 | ||
e8769719 | 397 | =item B<-recip> I<file> |
7122aafc | 398 | |
c4de074e | 399 | When decrypting a message this specifies the recipients certificate. The |
4bf4a650 DSH |
400 | certificate must match one of the recipients of the message or an error |
401 | occurs. | |
402 | ||
403 | When encrypting a message this option may be used multiple times to specify | |
404 | each recipient. This form B<must> be used if customised parameters are | |
405 | required (for example to specify RSA-OAEP). | |
7122aafc | 406 | |
ecd4b8fe MC |
407 | Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this |
408 | option. | |
409 | ||
7122aafc DSH |
410 | =item B<-keyid> |
411 | ||
c4de074e | 412 | Use subject key identifier to identify certificates instead of issuer name and |
7122aafc DSH |
413 | serial number. The supplied certificate B<must> include a subject key |
414 | identifier extension. Supported by B<-sign> and B<-encrypt> options. | |
415 | ||
dfee8626 | 416 | =item B<-receipt_request_all>, B<-receipt_request_first> |
41f81a01 | 417 | |
c4de074e | 418 | For B<-sign> option include a signed receipt request. Indicate requests should |
4c583c36 | 419 | be provided by all recipient or first tier recipients (those mailed directly |
41f81a01 DSH |
420 | and not from a mailing list). Ignored it B<-receipt_request_from> is included. |
421 | ||
e8769719 | 422 | =item B<-receipt_request_from> I<emailaddress> |
41f81a01 | 423 | |
c4de074e | 424 | For B<-sign> option include a signed receipt request. Add an explicit email |
41f81a01 DSH |
425 | address where receipts should be supplied. |
426 | ||
e8769719 | 427 | =item B<-receipt_request_to> I<emailaddress> |
41f81a01 | 428 | |
1bc74519 | 429 | Add an explicit email address where signed receipts should be sent to. This |
41f81a01 DSH |
430 | option B<must> but supplied if a signed receipt it requested. |
431 | ||
432 | =item B<-receipt_request_print> | |
433 | ||
434 | For the B<-verify> operation print out the contents of any signed receipt | |
435 | requests. | |
436 | ||
e8769719 | 437 | =item B<-secretkey> I<key> |
7122aafc | 438 | |
c4de074e | 439 | Specify symmetric key to use. The key must be supplied in hex format and be |
7122aafc | 440 | consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt> |
4c583c36 | 441 | B<-EncryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used |
7122aafc DSH |
442 | with B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the |
443 | content encryption key using an AES key in the B<KEKRecipientInfo> type. | |
444 | ||
e8769719 | 445 | =item B<-secretkeyid> I<id> |
7122aafc | 446 | |
c4de074e | 447 | The key identifier for the supplied symmetric key for B<KEKRecipientInfo> type. |
7122aafc DSH |
448 | This option B<must> be present if the B<-secretkey> option is used with |
449 | B<-encrypt>. With B<-decrypt> operations the B<id> is used to locate the | |
450 | relevant key if it is not supplied then an attempt is used to decrypt any | |
451 | B<KEKRecipientInfo> structures. | |
452 | ||
e8769719 | 453 | =item B<-econtent_type> I<type> |
7122aafc | 454 | |
c4de074e | 455 | Set the encapsulated content type to B<type> if not supplied the B<Data> type |
7122aafc | 456 | is used. The B<type> argument can be any valid OID name in either text or |
1bc74519 | 457 | numerical format. |
7122aafc | 458 | |
e8769719 | 459 | =item B<-inkey> I<file> |
7122aafc | 460 | |
c4de074e | 461 | The private key to use when signing or decrypting. This must match the |
7122aafc DSH |
462 | corresponding certificate. If this option is not specified then the |
463 | private key must be included in the certificate file specified with | |
464 | the B<-recip> or B<-signer> file. When signing this option can be used | |
465 | multiple times to specify successive keys. | |
466 | ||
e8769719 | 467 | =item B<-keyopt> I<name>:I<parameter> |
4bf4a650 | 468 | |
c4de074e | 469 | For signing and encryption this option can be used multiple times to |
4bf4a650 | 470 | set customised parameters for the preceding key or certificate. It can |
dfcb42c6 DSH |
471 | currently be used to set RSA-PSS for signing, RSA-OAEP for encryption |
472 | or to modify default parameters for ECDH. | |
4bf4a650 | 473 | |
e8769719 | 474 | =item B<-passin> I<arg> |
7122aafc | 475 | |
c4de074e | 476 | The private key password source. For more information about the format of B<arg> |
e8769719 | 477 | see L<openssl(1)/Pass phrase options>. |
7122aafc | 478 | |
e8769719 | 479 | =item B<-rand> I<file...> |
7122aafc | 480 | |
c4de074e | 481 | A file or files containing random data used to seed the random number |
3ee1eac2 | 482 | generator. |
35ed393e | 483 | Multiple files can be specified separated by an OS-dependent character. |
7122aafc DSH |
484 | The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for |
485 | all others. | |
486 | ||
e8769719 | 487 | =item B<-writerand> I<file> |
3ee1eac2 RS |
488 | |
489 | Writes random data to the specified I<file> upon exit. | |
490 | This can be used with a subsequent B<-rand> flag. | |
491 | ||
e8769719 | 492 | =item I<cert.pem...> |
7122aafc | 493 | |
c4de074e | 494 | One or more certificates of message recipients: used when encrypting |
1bc74519 | 495 | a message. |
7122aafc | 496 | |
e8769719 | 497 | =item B<-to>, B<-from>, B<-subject> |
7122aafc | 498 | |
c4de074e | 499 | The relevant mail headers. These are included outside the signed |
7122aafc DSH |
500 | portion of a message so they may be included manually. If signing |
501 | then many S/MIME mail clients check the signers certificate's email | |
502 | address matches that specified in the From: address. | |
503 | ||
e42d84be | 504 | =item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, |
d33def66 | 505 | B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>, |
5a1f853b | 506 | B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>, |
e42d84be | 507 | B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>, |
d33def66 | 508 | B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, |
fbb82a60 VD |
509 | B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, |
510 | B<-verify_ip>, B<-verify_name>, B<-x509_strict> | |
e5fa864f | 511 | |
fa7b0111 | 512 | Set various certificate chain validation options. See the |
9b86974e | 513 | L<verify(1)> manual page for details. |
e5fa864f | 514 | |
7122aafc DSH |
515 | =back |
516 | ||
517 | =head1 NOTES | |
518 | ||
519 | The MIME message must be sent without any blank lines between the | |
520 | headers and the output. Some mail programs will automatically add | |
521 | a blank line. Piping the mail directly to sendmail is one way to | |
522 | achieve the correct format. | |
523 | ||
524 | The supplied message to be signed or encrypted must include the | |
60250017 | 525 | necessary MIME headers or many S/MIME clients won't display it |
7122aafc DSH |
526 | properly (if at all). You can use the B<-text> option to automatically |
527 | add plain text headers. | |
528 | ||
529 | A "signed and encrypted" message is one where a signed message is | |
530 | then encrypted. This can be produced by encrypting an already signed | |
531 | message: see the examples section. | |
532 | ||
533 | This version of the program only allows one signer per message but it | |
534 | will verify multiple signers on received messages. Some S/MIME clients | |
535 | choke if a message contains multiple signers. It is possible to sign | |
536 | messages "in parallel" by signing an already signed message. | |
537 | ||
538 | The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME | |
539 | clients. Strictly speaking these process CMS enveloped data: CMS | |
540 | encrypted data is used for other purposes. | |
541 | ||
542 | The B<-resign> option uses an existing message digest when adding a new | |
543 | signer. This means that attributes must be present in at least one existing | |
544 | signer using the same message digest or this operation will fail. | |
545 | ||
e4ef2e25 | 546 | The B<-stream> and B<-indef> options enable streaming I/O support. |
7122aafc DSH |
547 | As a result the encoding is BER using indefinite length constructed encoding |
548 | and no longer DER. Streaming is supported for the B<-encrypt> operation and the | |
549 | B<-sign> operation if the content is not detached. | |
550 | ||
551 | Streaming is always used for the B<-sign> operation with detached data but | |
552 | since the content is no longer part of the CMS structure the encoding | |
553 | remains DER. | |
554 | ||
0dd5b94a DSH |
555 | If the B<-decrypt> option is used without a recipient certificate then an |
556 | attempt is made to locate the recipient by trying each potential recipient | |
557 | in turn using the supplied private key. To thwart the MMA attack | |
558 | (Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are | |
559 | tried whether they succeed or not and if no recipients match the message | |
1bc74519 | 560 | is "decrypted" using a random key which will typically output garbage. |
0dd5b94a DSH |
561 | The B<-debug_decrypt> option can be used to disable the MMA attack protection |
562 | and return an error if no recipient can be found: this option should be used | |
9b86974e | 563 | with caution. For a fuller description see L<CMS_decrypt(3)>). |
0dd5b94a | 564 | |
485d3361 | 565 | =head1 CADES BASIC ELECTRONIC SIGNATURE (CADES-BES) |
e85d19c6 AI |
566 | |
567 | A CAdES Basic Electronic Signature (CAdES-BES), as defined in the European Standard ETSI EN 319 122-1 V1.1.1, contains: | |
568 | ||
569 | =over 4 | |
570 | ||
571 | =item * | |
572 | ||
573 | The signed user data as defined in CMS (RFC 3852); | |
574 | ||
575 | =item * | |
576 | ||
577 | Content-type of the EncapsulatedContentInfo value being signed; | |
578 | ||
579 | =item * | |
580 | ||
581 | Message-digest of the eContent OCTET STRING within encapContentInfo being signed; | |
582 | ||
583 | =item * | |
584 | ||
585 | An ESS signing-certificate or ESS signing-certificate-v2 attribute, as defined in Enhanced Security Services (ESS), RFC 2634 and RFC 5035. | |
586 | An ESS signing-certificate attribute only allows for the use of SHA-1 as a digest algorithm. | |
587 | An ESS signing-certificate-v2 attribute allows for the use of any digest algorithm. | |
588 | ||
589 | =item * | |
590 | ||
591 | The digital signature value computed on the user data and, when present, on the signed attributes. | |
592 | ||
593 | Note that currently the B<-cades> option applies only to the B<-sign> operation and is ignored during | |
594 | the B<-verify> operation, i.e. the signing certification is not checked during the verification process. | |
595 | This feature might be added in a future version. | |
596 | ||
597 | =back | |
598 | ||
7122aafc DSH |
599 | =head1 EXIT CODES |
600 | ||
601 | =over 4 | |
602 | ||
c8919dde | 603 | =item Z<>0 |
7122aafc | 604 | |
c4de074e | 605 | The operation was completely successfully. |
7122aafc | 606 | |
c8919dde | 607 | =item Z<>1 |
7122aafc | 608 | |
c4de074e | 609 | An error occurred parsing the command options. |
7122aafc | 610 | |
c8919dde | 611 | =item Z<>2 |
7122aafc | 612 | |
c4de074e | 613 | One of the input files could not be read. |
7122aafc | 614 | |
c8919dde | 615 | =item Z<>3 |
7122aafc | 616 | |
c4de074e | 617 | An error occurred creating the CMS file or when reading the MIME |
7122aafc DSH |
618 | message. |
619 | ||
c8919dde | 620 | =item Z<>4 |
7122aafc | 621 | |
c4de074e | 622 | An error occurred decrypting or verifying the message. |
7122aafc | 623 | |
c8919dde | 624 | =item Z<>5 |
7122aafc | 625 | |
c4de074e | 626 | The message was verified correctly but an error occurred writing out |
7122aafc DSH |
627 | the signers certificates. |
628 | ||
629 | =back | |
630 | ||
485d3361 | 631 | =head1 COMPATIBILITY WITH PKCS#7 FORMAT |
7122aafc DSH |
632 | |
633 | The B<smime> utility can only process the older B<PKCS#7> format. The B<cms> | |
634 | utility supports Cryptographic Message Syntax format. Use of some features | |
635 | will result in messages which cannot be processed by applications which only | |
636 | support the older format. These are detailed below. | |
637 | ||
638 | The use of the B<-keyid> option with B<-sign> or B<-encrypt>. | |
639 | ||
e8769719 | 640 | The B<-outform> I<PEM> option uses different headers. |
7122aafc DSH |
641 | |
642 | The B<-compress> option. | |
643 | ||
644 | The B<-secretkey> option when used with B<-encrypt>. | |
645 | ||
dfcb42c6 DSH |
646 | The use of PSS with B<-sign>. |
647 | ||
648 | The use of OAEP or non-RSA keys with B<-encrypt>. | |
649 | ||
7122aafc DSH |
650 | Additionally the B<-EncryptedData_create> and B<-data_create> type cannot |
651 | be processed by the older B<smime> command. | |
652 | ||
653 | =head1 EXAMPLES | |
654 | ||
655 | Create a cleartext signed message: | |
656 | ||
657 | openssl cms -sign -in message.txt -text -out mail.msg \ | |
1bc74519 | 658 | -signer mycert.pem |
7122aafc DSH |
659 | |
660 | Create an opaque signed message | |
661 | ||
662 | openssl cms -sign -in message.txt -text -out mail.msg -nodetach \ | |
1bc74519 | 663 | -signer mycert.pem |
7122aafc DSH |
664 | |
665 | Create a signed message, include some additional certificates and | |
666 | read the private key from another file: | |
667 | ||
668 | openssl cms -sign -in in.txt -text -out mail.msg \ | |
1bc74519 | 669 | -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem |
7122aafc DSH |
670 | |
671 | Create a signed message with two signers, use key identifier: | |
672 | ||
673 | openssl cms -sign -in message.txt -text -out mail.msg \ | |
1bc74519 | 674 | -signer mycert.pem -signer othercert.pem -keyid |
7122aafc DSH |
675 | |
676 | Send a signed message under Unix directly to sendmail, including headers: | |
677 | ||
678 | openssl cms -sign -in in.txt -text -signer mycert.pem \ | |
1bc74519 RS |
679 | -from steve@openssl.org -to someone@somewhere \ |
680 | -subject "Signed message" | sendmail someone@somewhere | |
7122aafc DSH |
681 | |
682 | Verify a message and extract the signer's certificate if successful: | |
683 | ||
684 | openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt | |
685 | ||
686 | Send encrypted mail using triple DES: | |
687 | ||
688 | openssl cms -encrypt -in in.txt -from steve@openssl.org \ | |
1bc74519 RS |
689 | -to someone@somewhere -subject "Encrypted message" \ |
690 | -des3 user.pem -out mail.msg | |
7122aafc DSH |
691 | |
692 | Sign and encrypt mail: | |
693 | ||
694 | openssl cms -sign -in ml.txt -signer my.pem -text \ | |
1bc74519 RS |
695 | | openssl cms -encrypt -out mail.msg \ |
696 | -from steve@openssl.org -to someone@somewhere \ | |
697 | -subject "Signed and Encrypted message" -des3 user.pem | |
7122aafc DSH |
698 | |
699 | Note: the encryption command does not include the B<-text> option because the | |
700 | message being encrypted already has MIME headers. | |
701 | ||
702 | Decrypt mail: | |
703 | ||
704 | openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem | |
705 | ||
706 | The output from Netscape form signing is a PKCS#7 structure with the | |
707 | detached signature format. You can use this program to verify the | |
708 | signature by line wrapping the base64 encoded structure and surrounding | |
709 | it with: | |
710 | ||
711 | -----BEGIN PKCS7----- | |
712 | -----END PKCS7----- | |
713 | ||
1bc74519 | 714 | and using the command, |
7122aafc DSH |
715 | |
716 | openssl cms -verify -inform PEM -in signature.pem -content content.txt | |
717 | ||
718 | alternatively you can base64 decode the signature and use | |
719 | ||
720 | openssl cms -verify -inform DER -in signature.der -content content.txt | |
721 | ||
722 | Create an encrypted message using 128 bit Camellia: | |
723 | ||
724 | openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem | |
725 | ||
726 | Add a signer to an existing message: | |
727 | ||
728 | openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg | |
729 | ||
4bf4a650 DSH |
730 | Sign mail using RSA-PSS: |
731 | ||
732 | openssl cms -sign -in message.txt -text -out mail.msg \ | |
1bc74519 | 733 | -signer mycert.pem -keyopt rsa_padding_mode:pss |
4bf4a650 DSH |
734 | |
735 | Create encrypted mail using RSA-OAEP: | |
736 | ||
dfcb42c6 | 737 | openssl cms -encrypt -in plain.txt -out mail.msg \ |
1bc74519 | 738 | -recip cert.pem -keyopt rsa_padding_mode:oaep |
4bf4a650 | 739 | |
dfcb42c6 DSH |
740 | Use SHA256 KDF with an ECDH certificate: |
741 | ||
742 | openssl cms -encrypt -in plain.txt -out mail.msg \ | |
1bc74519 | 743 | -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256 |
dfcb42c6 | 744 | |
7122aafc DSH |
745 | =head1 BUGS |
746 | ||
747 | The MIME parser isn't very clever: it seems to handle most messages that I've | |
748 | thrown at it but it may choke on others. | |
749 | ||
750 | The code currently will only write out the signer's certificate to a file: if | |
751 | the signer has a separate encryption certificate this must be manually | |
752 | extracted. There should be some heuristic that determines the correct | |
753 | encryption certificate. | |
754 | ||
755 | Ideally a database should be maintained of a certificates for each email | |
756 | address. | |
757 | ||
758 | The code doesn't currently take note of the permitted symmetric encryption | |
759 | algorithms as supplied in the SMIMECapabilities signed attribute. this means the | |
760 | user has to manually include the correct encryption algorithm. It should store | |
761 | the list of permitted ciphers in a database and only use those. | |
762 | ||
763 | No revocation checking is done on the signer's certificate. | |
764 | ||
765 | =head1 HISTORY | |
766 | ||
767 | The use of multiple B<-signer> options and the B<-resign> command were first | |
ecd4b8fe | 768 | added in OpenSSL 1.0.0. |
4bf4a650 | 769 | |
fc5ecadd | 770 | The B<keyopt> option was added in OpenSSL 1.0.2. |
4bf4a650 | 771 | |
fc5ecadd | 772 | Support for RSA-OAEP and RSA-PSS was added in OpenSSL 1.0.2. |
7122aafc | 773 | |
fc5ecadd DMSP |
774 | The use of non-RSA keys with B<-encrypt> and B<-decrypt> |
775 | was added in OpenSSL 1.0.2. | |
dfcb42c6 | 776 | |
fc5ecadd | 777 | The -no_alt_chains option was added in OpenSSL 1.0.2b. |
fa7b0111 | 778 | |
e2f92610 RS |
779 | =head1 COPYRIGHT |
780 | ||
b6b66573 | 781 | Copyright 2008-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 782 | |
449040b4 | 783 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
784 | this file except in compliance with the License. You can obtain a copy |
785 | in the file LICENSE in the source distribution or at | |
786 | L<https://www.openssl.org/source/license.html>. | |
787 | ||
788 | =cut |