1CMS(1) OpenSSL CMS(1)
2
6 openssl-cms, cms - CMS utility
7
9 openssl cms [-help] [-encrypt] [-decrypt] [-sign] [-verify] [-cmsout]
10 [-resign] [-data_create] [-data_out] [-digest_create] [-digest_verify]
11 [-compress] [-uncompress] [-EncryptedData_encrypt] [-sign_receipt]
12 [-verify_receipt receipt] [-in filename] [-inform SMIME|PEM|DER]
13 [-rctform SMIME|PEM|DER] [-out filename] [-outform SMIME|PEM|DER]
14 [-stream -indef -noindef] [-noindef] [-content filename] [-text]
15 [-noout] [-print] [-CAfile file] [-CApath dir] [-no-CAfile]
16 [-no-CApath] [-attime timestamp] [-check_ss_sig] [-crl_check]
17 [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical]
18 [-inhibit_any] [-inhibit_map] [-no_check_time] [-partial_chain]
19 [-policy arg] [-policy_check] [-policy_print] [-purpose purpose]
20 [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first]
21 [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num]
22 [-verify_email email] [-verify_hostname hostname] [-verify_ip ip]
23 [-verify_name name] [-x509_strict] [-md digest] [-cipher] [-nointern]
24 [-noverify] [-nocerts] [-noattr] [-nosmimecap] [-binary] [-crlfeol]
25 [-asciicrlf] [-nodetach] [-certfile file] [-certsout file] [-signer
26 file] [-recip file] [-keyid] [-receipt_request_all]
27 [-receipt_request_first] [-receipt_request_from emailaddress]
28 [-receipt_request_to emailaddress] [-receipt_request_print] [-secretkey
29 key] [-secretkeyid id] [-econtent_type type] [-inkey file] [-keyopt
30 name:parameter] [-passin arg] [-rand file...] [-writerand file]
31 [cert.pem...] [-to addr] [-from addr] [-subject subj] [cert.pem]...
32
34 The cms command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign
35 and verify, compress and uncompress S/MIME messages.
36
38 There are fourteen operation options that set the type of operation to
39 be performed. The meaning of the other options varies according to the
40 operation type.
41 -help
43 Print out a usage message.
44 -encrypt
46 Encrypt mail for the given recipient certificates. Input file is
47 the message to be encrypted. The output file is the encrypted mail
48 in MIME format. The actual CMS type is <B>EnvelopedData<B>.
49 Note that no revocation check is done for the recipient cert, so if
51 that key has been compromised, others may be able to decrypt the
52 text.
53 -decrypt
55 Decrypt mail using the supplied certificate and private key.
56 Expects an encrypted mail message in MIME format for the input
57 file. The decrypted mail is written to the output file.
58 -debug_decrypt
60 This option sets the CMS_DEBUG_DECRYPT flag. This option should be
61 used with caution: see the notes section below.
62 -sign
64 Sign mail using the supplied certificate and private key. Input
65 file is the message to be signed. The signed message in MIME format
66 is written to the output file.
67 -verify
69 Verify signed mail. Expects a signed mail message on input and
70 outputs the signed data. Both clear text and opaque signing is
71 supported.
72 -cmsout
74 Takes an input message and writes out a PEM encoded CMS structure.
75 -resign
77 Resign a message: take an existing message and one or more new
78 signers.
79 -data_create
81 Create a CMS Data type.
82 -data_out
84 Data type and output the content.
85 -digest_create
87 Create a CMS DigestedData type.
88 -digest_verify
90 Verify a CMS DigestedData type and output the content.
91 -compress
93 Create a CMS CompressedData type. OpenSSL must be compiled with
94 zlib support for this option to work, otherwise it will output an
95 error.
96 -uncompress
98 Uncompress a CMS CompressedData type and output the content.
99 OpenSSL must be compiled with zlib support for this option to work,
100 otherwise it will output an error.
101 -EncryptedData_encrypt
103 Encrypt content using supplied symmetric key and algorithm using a
104 CMS EncryptedData type and output the content.
105 -sign_receipt
107 Generate and output a signed receipt for the supplied message. The
108 input message must contain a signed receipt request. Functionality
109 is otherwise similar to the -sign operation.
110 -verify_receipt receipt
112 Verify a signed receipt in filename receipt. The input message must
113 contain the original receipt request. Functionality is otherwise
114 similar to the -verify operation.
115 -in filename
117 The input message to be encrypted or signed or the message to be
118 decrypted or verified.
119 -inform SMIME|PEM|DER
121 This specifies the input format for the CMS structure. The default
122 is SMIME which reads an S/MIME format message. PEM and DER format
123 change this to expect PEM and DER format CMS structures instead.
124 This currently only affects the input format of the CMS structure,
125 if no CMS structure is being input (for example with -encrypt or
126 -sign) this option has no effect.
127 -rctform SMIME|PEM|DER
129 Specify the format for a signed receipt for use with the
130 -receipt_verify operation.
131 -out filename
133 The message text that has been decrypted or verified or the output
134 MIME format message that has been signed or verified.
135 -outform SMIME|PEM|DER
137 This specifies the output format for the CMS structure. The default
138 is SMIME which writes an S/MIME format message. PEM and DER format
139 change this to write PEM and DER format CMS structures instead.
140 This currently only affects the output format of the CMS structure,
141 if no CMS structure is being output (for example with -verify or
142 -decrypt) this option has no effect.
143 -stream -indef -noindef
145 The -stream and -indef options are equivalent and enable streaming
146 I/O for encoding operations. This permits single pass processing of
147 data without the need to hold the entire contents in memory,
148 potentially supporting very large files. Streaming is automatically
149 set for S/MIME signing with detached data if the output format is
150 SMIME it is currently off by default for all other operations.
151 -noindef
153 Disable streaming I/O where it would produce and indefinite length
154 constructed encoding. This option currently has no effect. In
155 future streaming will be enabled by default on all relevant
156 operations and this option will disable it.
157 -content filename
159 This specifies a file containing the detached content, this is only
160 useful with the -verify command. This is only usable if the CMS
161 structure is using the detached signature form where the content is
162 not included. This option will override any content if the input
163 format is S/MIME and it uses the multipart/signed MIME content
164 type.
165 -text
167 This option adds plain text (text/plain) MIME headers to the
168 supplied message if encrypting or signing. If decrypting or
169 verifying it strips off text headers: if the decrypted or verified
170 message is not of MIME type text/plain then an error occurs.
171 -noout
173 For the -cmsout operation do not output the parsed CMS structure.
174 This is useful when combined with the -print option or if the
175 syntax of the CMS structure is being checked.
176 -print
178 For the -cmsout operation print out all fields of the CMS
179 structure. This is mainly useful for testing purposes.
180 -CAfile file
182 A file containing trusted CA certificates, only used with -verify.
183 -CApath dir
185 A directory containing trusted CA certificates, only used with
186 -verify. This directory must be a standard certificate directory:
187 that is a hash of each subject name (using x509 -hash) should be
188 linked to each certificate.
189 -no-CAfile
191 Do not load the trusted CA certificates from the default file
192 location
193 -no-CApath
195 Do not load the trusted CA certificates from the default directory
196 location
197 -md digest
199 Digest algorithm to use when signing or resigning. If not present
200 then the default digest algorithm for the signing key will be used
201 (usually SHA1).
202 -cipher
204 The encryption algorithm to use. For example triple DES (168 bits)
205 - -des3 or 256 bit AES - -aes256. Any standard algorithm name (as
206 used by the EVP_get_cipherbyname() function) can also be used
207 preceded by a dash, for example -aes-128-cbc. See enc(1) for a list
208 of ciphers supported by your version of OpenSSL.
209 If not specified triple DES is used. Only used with -encrypt and
211 -EncryptedData_create commands.
212 -nointern
214 When verifying a message normally certificates (if any) included in
215 the message are searched for the signing certificate. With this
216 option only the certificates specified in the -certfile option are
217 used. The supplied certificates can still be used as untrusted CAs
218 however.
219 -noverify
221 Do not verify the signers certificate of a signed message.
222 -nocerts
224 When signing a message the signer's certificate is normally
225 included with this option it is excluded. This will reduce the size
226 of the signed message but the verifier must have a copy of the
227 signers certificate available locally (passed using the -certfile
228 option for example).
229 -noattr
231 Normally when a message is signed a set of attributes are included
232 which include the signing time and supported symmetric algorithms.
233 With this option they are not included.
234 -nosmimecap
236 Exclude the list of supported algorithms from signed attributes,
237 other options such as signing time and content type are still
238 included.
239 -binary
241 Normally the input message is converted to "canonical" format which
242 is effectively using CR and LF as end of line: as required by the
243 S/MIME specification. When this option is present no translation
244 occurs. This is useful when handling binary data which may not be
245 in MIME format.
246 -crlfeol
248 Normally the output file uses a single LF as end of line. When this
249 option is present CRLF is used instead.
250 -asciicrlf
252 When signing use ASCII CRLF format canonicalisation. This strips
253 trailing whitespace from all lines, deletes trailing blank lines at
254 EOF and sets the encapsulated content type. This option is normally
255 used with detached content and an output signature format of DER.
256 This option is not normally needed when verifying as it is enabled
257 automatically if the encapsulated content format is detected.
258 -nodetach
260 When signing a message use opaque signing: this form is more
261 resistant to translation by mail relays but it cannot be read by
262 mail agents that do not support S/MIME. Without this option
263 cleartext signing with the MIME type multipart/signed is used.
264 -certfile file
266 Allows additional certificates to be specified. When signing these
267 will be included with the message. When verifying these will be
268 searched for the signers certificates. The certificates should be
269 in PEM format.
270 -certsout file
272 Any certificates contained in the message are written to file.
273 -signer file
275 A signing certificate when signing or resigning a message, this
276 option can be used multiple times if more than one signer is
277 required. If a message is being verified then the signers
278 certificates will be written to this file if the verification was
279 successful.
280 -recip file
282 When decrypting a message this specifies the recipients
283 certificate. The certificate must match one of the recipients of
284 the message or an error occurs.
285 When encrypting a message this option may be used multiple times to
287 specify each recipient. This form must be used if customised
288 parameters are required (for example to specify RSA-OAEP).
289 Only certificates carrying RSA, Diffie-Hellman or EC keys are
291 supported by this option.
292 -keyid
294 Use subject key identifier to identify certificates instead of
295 issuer name and serial number. The supplied certificate must
296 include a subject key identifier extension. Supported by -sign and
297 -encrypt options.
298 -receipt_request_all, -receipt_request_first
300 For -sign option include a signed receipt request. Indicate
301 requests should be provided by all recipient or first tier
302 recipients (those mailed directly and not from a mailing list).
303 Ignored it -receipt_request_from is included.
304 -receipt_request_from emailaddress
306 For -sign option include a signed receipt request. Add an explicit
307 email address where receipts should be supplied.
308 -receipt_request_to emailaddress
310 Add an explicit email address where signed receipts should be sent
311 to. This option must but supplied if a signed receipt it requested.
312 -receipt_request_print
314 For the -verify operation print out the contents of any signed
315 receipt requests.
316 -secretkey key
318 Specify symmetric key to use. The key must be supplied in hex
319 format and be consistent with the algorithm used. Supported by the
320 -EncryptedData_encrypt -EncryptedData_decrypt, -encrypt and
321 -decrypt options. When used with -encrypt or -decrypt the supplied
322 key is used to wrap or unwrap the content encryption key using an
323 AES key in the KEKRecipientInfo type.
324 -secretkeyid id
326 The key identifier for the supplied symmetric key for
327 KEKRecipientInfo type. This option must be present if the
328 -secretkey option is used with -encrypt. With -decrypt operations
329 the id is used to locate the relevant key if it is not supplied
330 then an attempt is used to decrypt any KEKRecipientInfo structures.
331 -econtent_type type
333 Set the encapsulated content type to type if not supplied the Data
334 type is used. The type argument can be any valid OID name in either
335 text or numerical format.
336 -inkey file
338 The private key to use when signing or decrypting. This must match
339 the corresponding certificate. If this option is not specified then
340 the private key must be included in the certificate file specified
341 with the -recip or -signer file. When signing this option can be
342 used multiple times to specify successive keys.
343 -keyopt name:opt
345 For signing and encryption this option can be used multiple times
346 to set customised parameters for the preceding key or certificate.
347 It can currently be used to set RSA-PSS for signing, RSA-OAEP for
348 encryption or to modify default parameters for ECDH.
349 -passin arg
351 The private key password source. For more information about the
352 format of arg see "Pass Phrase Options" in openssl(1).
353 -rand file...
355 A file or files containing random data used to seed the random
356 number generator. Multiple files can be specified separated by an
357 OS-dependent character. The separator is ; for MS-Windows, , for
358 OpenVMS, and : for all others.
359 [-writerand file]
361 Writes random data to the specified file upon exit. This can be
362 used with a subsequent -rand flag.
363 cert.pem...
365 One or more certificates of message recipients: used when
366 encrypting a message.
367 -to, -from, -subject
369 The relevant mail headers. These are included outside the signed
370 portion of a message so they may be included manually. If signing
371 then many S/MIME mail clients check the signers certificate's email
372 address matches that specified in the From: address.
373 -attime, -check_ss_sig, -crl_check, -crl_check_all, -explicit_policy,
375 -extended_crl, -ignore_critical, -inhibit_any, -inhibit_map,
376 -no_alt_chains, -no_check_time, -partial_chain, -policy, -policy_check,
377 -policy_print, -purpose, -suiteB_128, -suiteB_128_only, -suiteB_192,
378 -trusted_first, -use_deltas, -auth_level, -verify_depth, -verify_email,
379 -verify_hostname, -verify_ip, -verify_name, -x509_strict
380 Set various certificate chain validation options. See the verify(1)
381 manual page for details.
382
384 The MIME message must be sent without any blank lines between the
385 headers and the output. Some mail programs will automatically add a
386 blank line. Piping the mail directly to sendmail is one way to achieve
387 the correct format.
388 The supplied message to be signed or encrypted must include the
390 necessary MIME headers or many S/MIME clients won't display it properly
391 (if at all). You can use the -text option to automatically add plain
392 text headers.
393 A "signed and encrypted" message is one where a signed message is then
395 encrypted. This can be produced by encrypting an already signed
396 message: see the examples section.
397 This version of the program only allows one signer per message but it
399 will verify multiple signers on received messages. Some S/MIME clients
400 choke if a message contains multiple signers. It is possible to sign
401 messages "in parallel" by signing an already signed message.
402 The options -encrypt and -decrypt reflect common usage in S/MIME
404 clients. Strictly speaking these process CMS enveloped data: CMS
405 encrypted data is used for other purposes.
406 The -resign option uses an existing message digest when adding a new
408 signer. This means that attributes must be present in at least one
409 existing signer using the same message digest or this operation will
410 fail.
411 The -stream and -indef options enable streaming I/O support. As a
413 result the encoding is BER using indefinite length constructed encoding
414 and no longer DER. Streaming is supported for the -encrypt operation
415 and the -sign operation if the content is not detached.
416 Streaming is always used for the -sign operation with detached data but
418 since the content is no longer part of the CMS structure the encoding
419 remains DER.
420 If the -decrypt option is used without a recipient certificate then an
422 attempt is made to locate the recipient by trying each potential
423 recipient in turn using the supplied private key. To thwart the MMA
424 attack (Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all
425 recipients are tried whether they succeed or not and if no recipients
426 match the message is "decrypted" using a random key which will
427 typically output garbage. The -debug_decrypt option can be used to
428 disable the MMA attack protection and return an error if no recipient
429 can be found: this option should be used with caution. For a fuller
430 description see CMS_decrypt(3)).
431
433 0 The operation was completely successfully.
434 1 An error occurred parsing the command options.
436 2 One of the input files could not be read.
438 3 An error occurred creating the CMS file or when reading the MIME
440 message.
441 4 An error occurred decrypting or verifying the message.
443 5 The message was verified correctly but an error occurred writing
445 out the signers certificates.
446
448 The smime utility can only process the older PKCS#7 format. The cms
449 utility supports Cryptographic Message Syntax format. Use of some
450 features will result in messages which cannot be processed by
451 applications which only support the older format. These are detailed
452 below.
453 The use of the -keyid option with -sign or -encrypt.
455 The -outform PEM option uses different headers.
457 The -compress option.
459 The -secretkey option when used with -encrypt.
461 The use of PSS with -sign.
463 The use of OAEP or non-RSA keys with -encrypt.
465 Additionally the -EncryptedData_create and -data_create type cannot be
467 processed by the older smime command.
468
470 Create a cleartext signed message:
471 openssl cms -sign -in message.txt -text -out mail.msg \
473 -signer mycert.pem
474 Create an opaque signed message
476 openssl cms -sign -in message.txt -text -out mail.msg -nodetach \
478 -signer mycert.pem
479 Create a signed message, include some additional certificates and read
481 the private key from another file:
482 openssl cms -sign -in in.txt -text -out mail.msg \
484 -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
485 Create a signed message with two signers, use key identifier:
487 openssl cms -sign -in message.txt -text -out mail.msg \
489 -signer mycert.pem -signer othercert.pem -keyid
490 Send a signed message under Unix directly to sendmail, including
492 headers:
493 openssl cms -sign -in in.txt -text -signer mycert.pem \
495 -from steve@openssl.org -to someone@somewhere \
496 -subject "Signed message" | sendmail someone@somewhere
497 Verify a message and extract the signer's certificate if successful:
499 openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt
501 Send encrypted mail using triple DES:
503 openssl cms -encrypt -in in.txt -from steve@openssl.org \
505 -to someone@somewhere -subject "Encrypted message" \
506 -des3 user.pem -out mail.msg
507 Sign and encrypt mail:
509 openssl cms -sign -in ml.txt -signer my.pem -text \
511 | openssl cms -encrypt -out mail.msg \
512 -from steve@openssl.org -to someone@somewhere \
513 -subject "Signed and Encrypted message" -des3 user.pem
514 Note: the encryption command does not include the -text option because
516 the message being encrypted already has MIME headers.
517 Decrypt mail:
519 openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
521 The output from Netscape form signing is a PKCS#7 structure with the
523 detached signature format. You can use this program to verify the
524 signature by line wrapping the base64 encoded structure and surrounding
525 it with:
526 -----BEGIN PKCS7-----
528 -----END PKCS7-----
529 and using the command,
531 openssl cms -verify -inform PEM -in signature.pem -content content.txt
533 alternatively you can base64 decode the signature and use
535 openssl cms -verify -inform DER -in signature.der -content content.txt
537 Create an encrypted message using 128 bit Camellia:
539 openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
541 Add a signer to an existing message:
543 openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg
545 Sign mail using RSA-PSS:
547 openssl cms -sign -in message.txt -text -out mail.msg \
549 -signer mycert.pem -keyopt rsa_padding_mode:pss
550 Create encrypted mail using RSA-OAEP:
552 openssl cms -encrypt -in plain.txt -out mail.msg \
554 -recip cert.pem -keyopt rsa_padding_mode:oaep
555 Use SHA256 KDF with an ECDH certificate:
557 openssl cms -encrypt -in plain.txt -out mail.msg \
559 -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
560
562 The MIME parser isn't very clever: it seems to handle most messages
563 that I've thrown at it but it may choke on others.
564 The code currently will only write out the signer's certificate to a
566 file: if the signer has a separate encryption certificate this must be
567 manually extracted. There should be some heuristic that determines the
568 correct encryption certificate.
569 Ideally a database should be maintained of a certificates for each
571 email address.
572 The code doesn't currently take note of the permitted symmetric
574 encryption algorithms as supplied in the SMIMECapabilities signed
575 attribute. this means the user has to manually include the correct
576 encryption algorithm. It should store the list of permitted ciphers in
577 a database and only use those.
578 No revocation checking is done on the signer's certificate.
580
582 The use of multiple -signer options and the -resign command were first
583 added in OpenSSL 1.0.0.
584 The keyopt option was added in OpenSSL 1.0.2.
586 Support for RSA-OAEP and RSA-PSS was added in OpenSSL 1.0.2.
588 The use of non-RSA keys with -encrypt and -decrypt was added in OpenSSL
590 1.0.2.
591 The -no_alt_chains option was added in OpenSSL 1.0.2b.
593
595 Copyright 2008-2021 The OpenSSL Project Authors. All Rights Reserved.
596 Licensed under the OpenSSL license (the "License"). You may not use
598 this file except in compliance with the License. You can obtain a copy
599 in the file LICENSE in the source distribution or at
600 <https://www.openssl.org/source/license.html>.
6011.1.1k 2021-03-26 CMS(1)