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