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