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