1CMS(1)                              OpenSSL                             CMS(1)
2
3
4

NAME

6       cms - CMS utility
7

SYNOPSIS

9       openssl cms [-encrypt] [-decrypt] [-sign] [-verify] [-cmsout] [-resign]
10       [-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] [-trusted_first]
16       [-no_alt_chains] [-md digest] [-[cipher]] [-nointern]
17       [-no_signer_cert_verify] [-nocerts] [-noattr] [-nosmimecap] [-binary]
18       [-nodetach] [-certfile file] [-certsout file] [-signer file] [-recip
19       file] [-keyid] [-receipt_request_all -receipt_request_first]
20       [-receipt_request_from emailaddress] [-receipt_request_to emailaddress]
21       [-receipt_request_print] [-secretkey key] [-secretkeyid id]
22       [-econtent_type type] [-inkey file] [-keyopt name:parameter] [-passin
23       arg] [-rand file(s)] [cert.pem...]  [-to addr] [-from addr] [-subject
24       subj] [cert.pem]...
25

DESCRIPTION

27       The cms command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign
28       and verify, compress and uncompress S/MIME messages.
29

COMMAND OPTIONS

31       There are fourteen operation options that set the type of operation to
32       be performed. The meaning of the other options varies according to the
33       operation type.
34
35       -encrypt
36           encrypt mail for the given recipient certificates. Input file is
37           the message to be encrypted. The output file is the encrypted mail
38           in MIME format. The actual CMS type is <B>EnvelopedData<B>.
39
40           Note that no revocation check is done for the recipient cert, so if
41           that key has been compromised, others may be able to decrypt the
42           text.
43
44       -decrypt
45           decrypt mail using the supplied certificate and private key.
46           Expects an encrypted mail message in MIME format for the input
47           file. The decrypted mail is written to the output file.
48
49       -debug_decrypt
50           this option sets the CMS_DEBUG_DECRYPT flag. This option should be
51           used with caution: see the notes section below.
52
53       -sign
54           sign mail using the supplied certificate and private key. Input
55           file is the message to be signed. The signed message in MIME format
56           is written to the output file.
57
58       -verify
59           verify signed mail. Expects a signed mail message on input and
60           outputs the signed data. Both clear text and opaque signing is
61           supported.
62
63       -cmsout
64           takes an input message and writes out a PEM encoded CMS structure.
65
66       -resign
67           resign a message: take an existing message and one or more new
68           signers.
69
70       -data_create
71           Create a CMS Data type.
72
73       -data_out
74           Data type and output the content.
75
76       -digest_create
77           Create a CMS DigestedData type.
78
79       -digest_verify
80           Verify a CMS DigestedData type and output the content.
81
82       -compress
83           Create a CMS CompressedData type. OpenSSL must be compiled with
84           zlib support for this option to work, otherwise it will output an
85           error.
86
87       -uncompress
88           Uncompress a CMS CompressedData type and output the content.
89           OpenSSL must be compiled with zlib support for this option to work,
90           otherwise it will output an error.
91
92       -EncryptedData_encrypt
93           Encrypt content using supplied symmetric key and algorithm using a
94           CMS EncrytedData type and output the content.
95
96       -sign_receipt
97           Generate and output a signed receipt for the supplied message. The
98           input message must contain a signed receipt request. Functionality
99           is otherwise similar to the -sign operation.
100
101       -verify_receipt receipt
102           Verify a signed receipt in filename receipt. The input message must
103           contain the original receipt request. Functionality is otherwise
104           similar to the -verify operation.
105
106       -in filename
107           the input message to be encrypted or signed or the message to be
108           decrypted or verified.
109
110       -inform SMIME|PEM|DER
111           this specifies the input format for the CMS structure. The default
112           is SMIME which reads an S/MIME format message. PEM and DER format
113           change this to expect PEM and DER format CMS structures instead.
114           This currently only affects the input format of the CMS structure,
115           if no CMS structure is being input (for example with -encrypt or
116           -sign) this option has no effect.
117
118       -rctform SMIME|PEM|DER
119           specify the format for a signed receipt for use with the
120           -receipt_verify operation.
121
122       -out filename
123           the message text that has been decrypted or verified or the output
124           MIME format message that has been signed or verified.
125
126       -outform SMIME|PEM|DER
127           this specifies the output format for the CMS structure. The default
128           is SMIME which writes an S/MIME format message. PEM and DER format
129           change this to write PEM and DER format CMS structures instead.
130           This currently only affects the output format of the CMS structure,
131           if no CMS structure is being output (for example with -verify or
132           -decrypt) this option has no effect.
133
134       -stream -indef -noindef
135           the -stream and -indef options are equivalent and enable streaming
136           I/O for encoding operations. This permits single pass processing of
137           data without the need to hold the entire contents in memory,
138           potentially supporting very large files. Streaming is automatically
139           set for S/MIME signing with detached data if the output format is
140           SMIME it is currently off by default for all other operations.
141
142       -noindef
143           disable streaming I/O where it would produce and indefinite length
144           constructed encoding. This option currently has no effect. In
145           future streaming will be enabled by default on all relevant
146           operations and this option will disable it.
147
148       -content filename
149           This specifies a file containing the detached content, this is only
150           useful with the -verify command. This is only usable if the CMS
151           structure is using the detached signature form where the content is
152           not included. This option will override any content if the input
153           format is S/MIME and it uses the multipart/signed MIME content
154           type.
155
156       -text
157           this option adds plain text (text/plain) MIME headers to the
158           supplied message if encrypting or signing. If decrypting or
159           verifying it strips off text headers: if the decrypted or verified
160           message is not of MIME type text/plain then an error occurs.
161
162       -noout
163           for the -cmsout operation do not output the parsed CMS structure.
164           This is useful when combined with the -print option or if the
165           syntax of the CMS structure is being checked.
166
167       -print
168           for the -cmsout operation print out all fields of the CMS
169           structure. This is mainly useful for testing purposes.
170
171       -CAfile file
172           a file containing trusted CA certificates, only used with -verify.
173
174       -CApath dir
175           a directory containing trusted CA certificates, only used with
176           -verify. This directory must be a standard certificate directory:
177           that is a hash of each subject name (using x509 -hash) should be
178           linked to each certificate.
179
180       -trusted_first
181           Use certificates in CA file or CA directory before untrusted
182           certificates from the message when building the trust chain to
183           verify certificates.  This is mainly useful in environments with
184           Bridge CA or Cross-Certified CAs.
185
186       -md digest
187           digest algorithm to use when signing or resigning. If not present
188           then the default digest algorithm for the signing key will be used
189           (usually SHA1).
190
191       -[cipher]
192           the encryption algorithm to use. For example triple DES (168 bits)
193           - -des3 or 256 bit AES - -aes256. Any standard algorithm name (as
194           used by the EVP_get_cipherbyname() function) can also be used
195           preceded by a dash, for example -aes_128_cbc. See enc for a list of
196           ciphers supported by your version of OpenSSL.
197
198           If not specified triple DES is used. Only used with -encrypt and
199           -EncryptedData_create commands.
200
201       -nointern
202           when verifying a message normally certificates (if any) included in
203           the message are searched for the signing certificate. With this
204           option only the certificates specified in the -certfile option are
205           used.  The supplied certificates can still be used as untrusted CAs
206           however.
207
208       -no_signer_cert_verify
209           do not verify the signers certificate of a signed message.
210
211       -nocerts
212           when signing a message the signer's certificate is normally
213           included with this option it is excluded. This will reduce the size
214           of the signed message but the verifier must have a copy of the
215           signers certificate available locally (passed using the -certfile
216           option for example).
217
218       -noattr
219           normally when a message is signed a set of attributes are included
220           which include the signing time and supported symmetric algorithms.
221           With this option they are not included.
222
223       -nosmimecap
224           exclude the list of supported algorithms from signed attributes,
225           other options such as signing time and content type are still
226           included.
227
228       -binary
229           normally the input message is converted to "canonical" format which
230           is effectively using CR and LF as end of line: as required by the
231           S/MIME specification. When this option is present no translation
232           occurs. This is useful when handling binary data which may not be
233           in MIME format.
234
235       -nodetach
236           when signing a message use opaque signing: this form is more
237           resistant to translation by mail relays but it cannot be read by
238           mail agents that do not support S/MIME.  Without this option
239           cleartext signing with the MIME type multipart/signed is used.
240
241       -certfile file
242           allows additional certificates to be specified. When signing these
243           will be included with the message. When verifying these will be
244           searched for the signers certificates. The certificates should be
245           in PEM format.
246
247       -certsout file
248           any certificates contained in the message are written to file.
249
250       -signer file
251           a signing certificate when signing or resigning a message, this
252           option can be used multiple times if more than one signer is
253           required. If a message is being verified then the signers
254           certificates will be written to this file if the verification was
255           successful.
256
257       -recip file
258           when decrypting a message this specifies the recipients
259           certificate. The certificate must match one of the recipients of
260           the message or an error occurs.
261
262           When encrypting a message this option may be used multiple times to
263           specify each recipient. This form must be used if customised
264           parameters are required (for example to specify RSA-OAEP).
265
266       -keyid
267           use subject key identifier to identify certificates instead of
268           issuer name and serial number. The supplied certificate must
269           include a subject key identifier extension. Supported by -sign and
270           -encrypt options.
271
272       -receipt_request_all -receipt_request_first
273           for -sign option include a signed receipt request. Indicate
274           requests should be provided by all receipient or first tier
275           recipients (those mailed directly and not from a mailing list).
276           Ignored it -receipt_request_from is included.
277
278       -receipt_request_from emailaddress
279           for -sign option include a signed receipt request. Add an explicit
280           email address where receipts should be supplied.
281
282       -receipt_request_to emailaddress
283           Add an explicit email address where signed receipts should be sent
284           to. This option must but supplied if a signed receipt it requested.
285
286       -receipt_request_print
287           For the -verify operation print out the contents of any signed
288           receipt requests.
289
290       -secretkey key
291           specify symmetric key to use. The key must be supplied in hex
292           format and be consistent with the algorithm used. Supported by the
293           -EncryptedData_encrypt -EncrryptedData_decrypt, -encrypt and
294           -decrypt options. When used with -encrypt or -decrypt the supplied
295           key is used to wrap or unwrap the content encryption key using an
296           AES key in the KEKRecipientInfo type.
297
298       -secretkeyid id
299           the key identifier for the supplied symmetric key for
300           KEKRecipientInfo type.  This option must be present if the
301           -secretkey option is used with -encrypt. With -decrypt operations
302           the id is used to locate the relevant key if it is not supplied
303           then an attempt is used to decrypt any KEKRecipientInfo structures.
304
305       -econtent_type type
306           set the encapsulated content type to type if not supplied the Data
307           type is used. The type argument can be any valid OID name in either
308           text or numerical format.
309
310       -inkey file
311           the private key to use when signing or decrypting. This must match
312           the corresponding certificate. If this option is not specified then
313           the private key must be included in the certificate file specified
314           with the -recip or -signer file. When signing this option can be
315           used multiple times to specify successive keys.
316
317       -keyopt name:opt
318           for signing and encryption this option can be used multiple times
319           to set customised parameters for the preceding key or certificate.
320           It can currently be used to set RSA-PSS for signing, RSA-OAEP for
321           encryption or to modify default parameters for ECDH.
322
323       -passin arg
324           the private key password source. For more information about the
325           format of arg see the PASS PHRASE ARGUMENTS section in openssl(1).
326
327       -rand file(s)
328           a file or files containing random data used to seed the random
329           number generator, or an EGD socket (see RAND_egd(3)).  Multiple
330           files can be specified separated by a OS-dependent character.  The
331           separator is ; for MS-Windows, , for OpenVMS, and : for all others.
332
333       cert.pem...
334           one or more certificates of message recipients: used when
335           encrypting a message.
336
337       -to, -from, -subject
338           the relevant mail headers. These are included outside the signed
339           portion of a message so they may be included manually. If signing
340           then many S/MIME mail clients check the signers certificate's email
341           address matches that specified in the From: address.
342
343       -purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all,
344       -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig
345       -no_alt_chains
346           Set various certificate chain valiadition option. See the verify
347           manual page for details.
348

NOTES

350       The MIME message must be sent without any blank lines between the
351       headers and the output. Some mail programs will automatically add a
352       blank line. Piping the mail directly to sendmail is one way to achieve
353       the correct format.
354
355       The supplied message to be signed or encrypted must include the
356       necessary MIME headers or many S/MIME clients wont display it properly
357       (if at all). You can use the -text option to automatically add plain
358       text headers.
359
360       A "signed and encrypted" message is one where a signed message is then
361       encrypted. This can be produced by encrypting an already signed
362       message: see the examples section.
363
364       This version of the program only allows one signer per message but it
365       will verify multiple signers on received messages. Some S/MIME clients
366       choke if a message contains multiple signers. It is possible to sign
367       messages "in parallel" by signing an already signed message.
368
369       The options -encrypt and -decrypt reflect common usage in S/MIME
370       clients. Strictly speaking these process CMS enveloped data: CMS
371       encrypted data is used for other purposes.
372
373       The -resign option uses an existing message digest when adding a new
374       signer. This means that attributes must be present in at least one
375       existing signer using the same message digest or this operation will
376       fail.
377
378       The -stream and -indef options enable experimental streaming I/O
379       support.  As a result the encoding is BER using indefinite length
380       constructed encoding and no longer DER. Streaming is supported for the
381       -encrypt operation and the -sign operation if the content is not
382       detached.
383
384       Streaming is always used for the -sign operation with detached data but
385       since the content is no longer part of the CMS structure the encoding
386       remains DER.
387
388       If the -decrypt option is used without a recipient certificate then an
389       attempt is made to locate the recipient by trying each potential
390       recipient in turn using the supplied private key. To thwart the MMA
391       attack (Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all
392       recipients are tried whether they succeed or not and if no recipients
393       match the message is "decrypted" using a random key which will
394       typically output garbage.  The -debug_decrypt option can be used to
395       disable the MMA attack protection and return an error if no recipient
396       can be found: this option should be used with caution. For a fuller
397       description see CMS_decrypt(3)).
398

EXIT CODES

400       0   the operation was completely successfully.
401
402       1   an error occurred parsing the command options.
403
404       2   one of the input files could not be read.
405
406       3   an error occurred creating the CMS file or when reading the MIME
407           message.
408
409       4   an error occurred decrypting or verifying the message.
410
411       5   the message was verified correctly but an error occurred writing
412           out the signers certificates.
413

COMPATIBILITY WITH PKCS#7 format.

415       The smime utility can only process the older PKCS#7 format. The cms
416       utility supports Cryptographic Message Syntax format. Use of some
417       features will result in messages which cannot be processed by
418       applications which only support the older format. These are detailed
419       below.
420
421       The use of the -keyid option with -sign or -encrypt.
422
423       The -outform PEM option uses different headers.
424
425       The -compress option.
426
427       The -secretkey option when used with -encrypt.
428
429       The use of PSS with -sign.
430
431       The use of OAEP or non-RSA keys with -encrypt.
432
433       Additionally the -EncryptedData_create and -data_create type cannot be
434       processed by the older smime command.
435

EXAMPLES

437       Create a cleartext signed message:
438
439        openssl cms -sign -in message.txt -text -out mail.msg \
440               -signer mycert.pem
441
442       Create an opaque signed message
443
444        openssl cms -sign -in message.txt -text -out mail.msg -nodetach \
445               -signer mycert.pem
446
447       Create a signed message, include some additional certificates and read
448       the private key from another file:
449
450        openssl cms -sign -in in.txt -text -out mail.msg \
451               -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
452
453       Create a signed message with two signers, use key identifier:
454
455        openssl cms -sign -in message.txt -text -out mail.msg \
456               -signer mycert.pem -signer othercert.pem -keyid
457
458       Send a signed message under Unix directly to sendmail, including
459       headers:
460
461        openssl cms -sign -in in.txt -text -signer mycert.pem \
462               -from steve@openssl.org -to someone@somewhere \
463               -subject "Signed message" | sendmail someone@somewhere
464
465       Verify a message and extract the signer's certificate if successful:
466
467        openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt
468
469       Send encrypted mail using triple DES:
470
471        openssl cms -encrypt -in in.txt -from steve@openssl.org \
472               -to someone@somewhere -subject "Encrypted message" \
473               -des3 user.pem -out mail.msg
474
475       Sign and encrypt mail:
476
477        openssl cms -sign -in ml.txt -signer my.pem -text \
478               | openssl cms -encrypt -out mail.msg \
479               -from steve@openssl.org -to someone@somewhere \
480               -subject "Signed and Encrypted message" -des3 user.pem
481
482       Note: the encryption command does not include the -text option because
483       the message being encrypted already has MIME headers.
484
485       Decrypt mail:
486
487        openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
488
489       The output from Netscape form signing is a PKCS#7 structure with the
490       detached signature format. You can use this program to verify the
491       signature by line wrapping the base64 encoded structure and surrounding
492       it with:
493
494        -----BEGIN PKCS7-----
495        -----END PKCS7-----
496
497       and using the command,
498
499        openssl cms -verify -inform PEM -in signature.pem -content content.txt
500
501       alternatively you can base64 decode the signature and use
502
503        openssl cms -verify -inform DER -in signature.der -content content.txt
504
505       Create an encrypted message using 128 bit Camellia:
506
507        openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
508
509       Add a signer to an existing message:
510
511        openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg
512
513       Sign mail using RSA-PSS:
514
515        openssl cms -sign -in message.txt -text -out mail.msg \
516               -signer mycert.pem -keyopt rsa_padding_mode:pss
517
518       Create encrypted mail using RSA-OAEP:
519
520        openssl cms -encrypt -in plain.txt -out mail.msg \
521               -recip cert.pem -keyopt rsa_padding_mode:oaep
522
523       Use SHA256 KDF with an ECDH certificate:
524
525        openssl cms -encrypt -in plain.txt -out mail.msg \
526               -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
527

BUGS

529       The MIME parser isn't very clever: it seems to handle most messages
530       that I've thrown at it but it may choke on others.
531
532       The code currently will only write out the signer's certificate to a
533       file: if the signer has a separate encryption certificate this must be
534       manually extracted. There should be some heuristic that determines the
535       correct encryption certificate.
536
537       Ideally a database should be maintained of a certificates for each
538       email address.
539
540       The code doesn't currently take note of the permitted symmetric
541       encryption algorithms as supplied in the SMIMECapabilities signed
542       attribute. this means the user has to manually include the correct
543       encryption algorithm. It should store the list of permitted ciphers in
544       a database and only use those.
545
546       No revocation checking is done on the signer's certificate.
547

HISTORY

549       The use of multiple -signer options and the -resign command were first
550       added in OpenSSL 1.0.0
551
552       The keyopt option was first added in OpenSSL 1.1.0
553
554       The use of -recip to specify the recipient when encrypting mail was
555       first added to OpenSSL 1.1.0
556
557       Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0.
558
559       The use of non-RSA keys with -encrypt and -decrypt was first added to
560       OpenSSL 1.1.0.
561
562       The -no_alt_chains options was first added to OpenSSL 1.0.2b.
563
564
565
5661.0.2k                            2019-03-12                            CMS(1)
Impressum