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