23 [B<-EncryptedData_encrypt>]
25 [B<-verify_receipt receipt>]
27 [B<-inform SMIME|PEM|DER>]
28 [B<-rctform SMIME|PEM|DER>]
30 [B<-outform SMIME|PEM|DER>]
31 [B<-stream -indef -noindef>]
33 [B<-content filename>]
41 [B<-attime timestamp>]
63 [B<-verify_depth num>]
64 [B<-verify_email email>]
65 [B<-verify_hostname hostname>]
67 [B<-verify_name name>]
72 [B<-no_signer_cert_verify>]
85 [B<-receipt_request_all -receipt_request_first>]
86 [B<-receipt_request_from emailaddress>]
87 [B<-receipt_request_to emailaddress>]
88 [B<-receipt_request_print>]
91 [B<-econtent_type type>]
93 [B<-keyopt name:parameter>]
104 The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and
105 verify, compress and uncompress S/MIME messages.
107 =head1 COMMAND OPTIONS
109 There are fourteen operation options that set the type of operation to be
110 performed. The meaning of the other options varies according to the operation
117 Print out a usage message.
121 encrypt mail for the given recipient certificates. Input file is the message
122 to be encrypted. The output file is the encrypted mail in MIME format. The
123 actual CMS type is <B>EnvelopedData<B>.
127 decrypt mail using the supplied certificate and private key. Expects an
128 encrypted mail message in MIME format for the input file. The decrypted mail
129 is written to the output file.
131 =item B<-debug_decrypt>
133 this option sets the B<CMS_DEBUG_DECRYPT> flag. This option should be used
134 with caution: see the notes section below.
138 sign mail using the supplied certificate and private key. Input file is
139 the message to be signed. The signed message in MIME format is written
144 verify signed mail. Expects a signed mail message on input and outputs
145 the signed data. Both clear text and opaque signing is supported.
149 takes an input message and writes out a PEM encoded CMS structure.
153 resign a message: take an existing message and one or more new signers.
155 =item B<-data_create>
157 Create a CMS B<Data> type.
161 B<Data> type and output the content.
163 =item B<-digest_create>
165 Create a CMS B<DigestedData> type.
167 =item B<-digest_verify>
169 Verify a CMS B<DigestedData> type and output the content.
173 Create a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib>
174 support for this option to work, otherwise it will output an error.
178 Uncompress a CMS B<CompressedData> type and output the content. OpenSSL must be
179 compiled with B<zlib> support for this option to work, otherwise it will
182 =item B<-EncryptedData_encrypt>
184 Encrypt content using supplied symmetric key and algorithm using a CMS
185 B<EncrytedData> type and output the content.
187 =item B<-sign_receipt>
189 Generate and output a signed receipt for the supplied message. The input
190 message B<must> contain a signed receipt request. Functionality is otherwise
191 similar to the B<-sign> operation.
193 =item B<-verify_receipt receipt>
195 Verify a signed receipt in filename B<receipt>. The input message B<must>
196 contain the original receipt request. Functionality is otherwise similar
197 to the B<-verify> operation.
199 =item B<-in filename>
201 the input message to be encrypted or signed or the message to be decrypted
204 =item B<-inform SMIME|PEM|DER>
206 this specifies the input format for the CMS structure. The default
207 is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER>
208 format change this to expect PEM and DER format CMS structures
209 instead. This currently only affects the input format of the CMS
210 structure, if no CMS structure is being input (for example with
211 B<-encrypt> or B<-sign>) this option has no effect.
213 =item B<-rctform SMIME|PEM|DER>
215 specify the format for a signed receipt for use with the B<-receipt_verify>
218 =item B<-out filename>
220 the message text that has been decrypted or verified or the output MIME
221 format message that has been signed or verified.
223 =item B<-outform SMIME|PEM|DER>
225 this specifies the output format for the CMS structure. The default
226 is B<SMIME> which writes an S/MIME format message. B<PEM> and B<DER>
227 format change this to write PEM and DER format CMS structures
228 instead. This currently only affects the output format of the CMS
229 structure, if no CMS structure is being output (for example with
230 B<-verify> or B<-decrypt>) this option has no effect.
232 =item B<-stream -indef -noindef>
234 the B<-stream> and B<-indef> options are equivalent and enable streaming I/O
235 for encoding operations. This permits single pass processing of data without
236 the need to hold the entire contents in memory, potentially supporting very
237 large files. Streaming is automatically set for S/MIME signing with detached
238 data if the output format is B<SMIME> it is currently off by default for all
243 disable streaming I/O where it would produce and indefinite length constructed
244 encoding. This option currently has no effect. In future streaming will be
245 enabled by default on all relevant operations and this option will disable it.
247 =item B<-content filename>
249 This specifies a file containing the detached content, this is only
250 useful with the B<-verify> command. This is only usable if the CMS
251 structure is using the detached signature form where the content is
252 not included. This option will override any content if the input format
253 is S/MIME and it uses the multipart/signed MIME content type.
257 this option adds plain text (text/plain) MIME headers to the supplied
258 message if encrypting or signing. If decrypting or verifying it strips
259 off text headers: if the decrypted or verified message is not of MIME
260 type text/plain then an error occurs.
264 for the B<-cmsout> operation do not output the parsed CMS structure. This
265 is useful when combined with the B<-print> option or if the syntax of the CMS
266 structure is being checked.
270 for the B<-cmsout> operation print out all fields of the CMS structure. This
271 is mainly useful for testing purposes.
273 =item B<-CAfile file>
275 a file containing trusted CA certificates, only used with B<-verify>.
279 a directory containing trusted CA certificates, only used with
280 B<-verify>. This directory must be a standard certificate directory: that
281 is a hash of each subject name (using B<x509 -hash>) should be linked
286 Do not load the trusted CA certificates from the default file location
290 Do not load the trusted CA certificates from the default directory location
294 digest algorithm to use when signing or resigning. If not present then the
295 default digest algorithm for the signing key will be used (usually SHA1).
299 the encryption algorithm to use. For example triple DES (168 bits) - B<-des3>
300 or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the
301 EVP_get_cipherbyname() function) can also be used preceded by a dash, for
302 example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for a list of ciphers
303 supported by your version of OpenSSL.
305 If not specified triple DES is used. Only used with B<-encrypt> and
306 B<-EncryptedData_create> commands.
310 when verifying a message normally certificates (if any) included in
311 the message are searched for the signing certificate. With this option
312 only the certificates specified in the B<-certfile> option are used.
313 The supplied certificates can still be used as untrusted CAs however.
315 =item B<-no_signer_cert_verify>
317 do not verify the signers certificate of a signed message.
321 when signing a message the signer's certificate is normally included
322 with this option it is excluded. This will reduce the size of the
323 signed message but the verifier must have a copy of the signers certificate
324 available locally (passed using the B<-certfile> option for example).
328 normally when a message is signed a set of attributes are included which
329 include the signing time and supported symmetric algorithms. With this
330 option they are not included.
334 exclude the list of supported algorithms from signed attributes, other options
335 such as signing time and content type are still included.
339 normally the input message is converted to "canonical" format which is
340 effectively using CR and LF as end of line: as required by the S/MIME
341 specification. When this option is present no translation occurs. This
342 is useful when handling binary data which may not be in MIME format.
346 normally the output file uses a single B<LF> as end of line. When this
347 option is present B<CRLF> is used instead.
351 when signing use ASCII CRLF format canonicalisation. This strips trailing
352 whitespace from all lines, deletes trailing blank lines at EOF and sets
353 the encapsulated content type. This option is normally used with detached
354 content and an output signature format of DER. This option is not normally
355 needed when verifying as it is enabled automatically if the encapsulated
356 content format is detected.
360 when signing a message use opaque signing: this form is more resistant
361 to translation by mail relays but it cannot be read by mail agents that
362 do not support S/MIME. Without this option cleartext signing with
363 the MIME type multipart/signed is used.
365 =item B<-certfile file>
367 allows additional certificates to be specified. When signing these will
368 be included with the message. When verifying these will be searched for
369 the signers certificates. The certificates should be in PEM format.
371 =item B<-certsout file>
373 any certificates contained in the message are written to B<file>.
375 =item B<-signer file>
377 a signing certificate when signing or resigning a message, this option can be
378 used multiple times if more than one signer is required. If a message is being
379 verified then the signers certificates will be written to this file if the
380 verification was successful.
384 when decrypting a message this specifies the recipients certificate. The
385 certificate must match one of the recipients of the message or an error
388 When encrypting a message this option may be used multiple times to specify
389 each recipient. This form B<must> be used if customised parameters are
390 required (for example to specify RSA-OAEP).
394 use subject key identifier to identify certificates instead of issuer name and
395 serial number. The supplied certificate B<must> include a subject key
396 identifier extension. Supported by B<-sign> and B<-encrypt> options.
398 =item B<-receipt_request_all -receipt_request_first>
400 for B<-sign> option include a signed receipt request. Indicate requests should
401 be provided by all recipient or first tier recipients (those mailed directly
402 and not from a mailing list). Ignored it B<-receipt_request_from> is included.
404 =item B<-receipt_request_from emailaddress>
406 for B<-sign> option include a signed receipt request. Add an explicit email
407 address where receipts should be supplied.
409 =item B<-receipt_request_to emailaddress>
411 Add an explicit email address where signed receipts should be sent to. This
412 option B<must> but supplied if a signed receipt it requested.
414 =item B<-receipt_request_print>
416 For the B<-verify> operation print out the contents of any signed receipt
419 =item B<-secretkey key>
421 specify symmetric key to use. The key must be supplied in hex format and be
422 consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt>
423 B<-EncryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used
424 with B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the
425 content encryption key using an AES key in the B<KEKRecipientInfo> type.
427 =item B<-secretkeyid id>
429 the key identifier for the supplied symmetric key for B<KEKRecipientInfo> type.
430 This option B<must> be present if the B<-secretkey> option is used with
431 B<-encrypt>. With B<-decrypt> operations the B<id> is used to locate the
432 relevant key if it is not supplied then an attempt is used to decrypt any
433 B<KEKRecipientInfo> structures.
435 =item B<-econtent_type type>
437 set the encapsulated content type to B<type> if not supplied the B<Data> type
438 is used. The B<type> argument can be any valid OID name in either text or
443 the private key to use when signing or decrypting. This must match the
444 corresponding certificate. If this option is not specified then the
445 private key must be included in the certificate file specified with
446 the B<-recip> or B<-signer> file. When signing this option can be used
447 multiple times to specify successive keys.
449 =item B<-keyopt name:opt>
451 for signing and encryption this option can be used multiple times to
452 set customised parameters for the preceding key or certificate. It can
453 currently be used to set RSA-PSS for signing, RSA-OAEP for encryption
454 or to modify default parameters for ECDH.
458 the private key password source. For more information about the format of B<arg>
459 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
461 =item B<-rand file(s)>
463 a file or files containing random data used to seed the random number
464 generator, or an EGD socket (see L<RAND_egd(3)>).
465 Multiple files can be specified separated by an OS-dependent character.
466 The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
471 one or more certificates of message recipients: used when encrypting
474 =item B<-to, -from, -subject>
476 the relevant mail headers. These are included outside the signed
477 portion of a message so they may be included manually. If signing
478 then many S/MIME mail clients check the signers certificate's email
479 address matches that specified in the From: address.
481 =item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
482 B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
483 B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
484 B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
485 B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
486 B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
487 B<-verify_ip>, B<-verify_name>, B<-x509_strict>
489 Set various certificate chain validation options. See the
490 L<verify(1)> manual page for details.
496 The MIME message must be sent without any blank lines between the
497 headers and the output. Some mail programs will automatically add
498 a blank line. Piping the mail directly to sendmail is one way to
499 achieve the correct format.
501 The supplied message to be signed or encrypted must include the
502 necessary MIME headers or many S/MIME clients won't display it
503 properly (if at all). You can use the B<-text> option to automatically
504 add plain text headers.
506 A "signed and encrypted" message is one where a signed message is
507 then encrypted. This can be produced by encrypting an already signed
508 message: see the examples section.
510 This version of the program only allows one signer per message but it
511 will verify multiple signers on received messages. Some S/MIME clients
512 choke if a message contains multiple signers. It is possible to sign
513 messages "in parallel" by signing an already signed message.
515 The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
516 clients. Strictly speaking these process CMS enveloped data: CMS
517 encrypted data is used for other purposes.
519 The B<-resign> option uses an existing message digest when adding a new
520 signer. This means that attributes must be present in at least one existing
521 signer using the same message digest or this operation will fail.
523 The B<-stream> and B<-indef> options enable streaming I/O support.
524 As a result the encoding is BER using indefinite length constructed encoding
525 and no longer DER. Streaming is supported for the B<-encrypt> operation and the
526 B<-sign> operation if the content is not detached.
528 Streaming is always used for the B<-sign> operation with detached data but
529 since the content is no longer part of the CMS structure the encoding
532 If the B<-decrypt> option is used without a recipient certificate then an
533 attempt is made to locate the recipient by trying each potential recipient
534 in turn using the supplied private key. To thwart the MMA attack
535 (Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are
536 tried whether they succeed or not and if no recipients match the message
537 is "decrypted" using a random key which will typically output garbage.
538 The B<-debug_decrypt> option can be used to disable the MMA attack protection
539 and return an error if no recipient can be found: this option should be used
540 with caution. For a fuller description see L<CMS_decrypt(3)>).
548 the operation was completely successfully.
552 an error occurred parsing the command options.
556 one of the input files could not be read.
560 an error occurred creating the CMS file or when reading the MIME
565 an error occurred decrypting or verifying the message.
569 the message was verified correctly but an error occurred writing out
570 the signers certificates.
574 =head1 COMPATIBILITY WITH PKCS#7 format.
576 The B<smime> utility can only process the older B<PKCS#7> format. The B<cms>
577 utility supports Cryptographic Message Syntax format. Use of some features
578 will result in messages which cannot be processed by applications which only
579 support the older format. These are detailed below.
581 The use of the B<-keyid> option with B<-sign> or B<-encrypt>.
583 The B<-outform PEM> option uses different headers.
585 The B<-compress> option.
587 The B<-secretkey> option when used with B<-encrypt>.
589 The use of PSS with B<-sign>.
591 The use of OAEP or non-RSA keys with B<-encrypt>.
593 Additionally the B<-EncryptedData_create> and B<-data_create> type cannot
594 be processed by the older B<smime> command.
598 Create a cleartext signed message:
600 openssl cms -sign -in message.txt -text -out mail.msg \
603 Create an opaque signed message
605 openssl cms -sign -in message.txt -text -out mail.msg -nodetach \
608 Create a signed message, include some additional certificates and
609 read the private key from another file:
611 openssl cms -sign -in in.txt -text -out mail.msg \
612 -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
614 Create a signed message with two signers, use key identifier:
616 openssl cms -sign -in message.txt -text -out mail.msg \
617 -signer mycert.pem -signer othercert.pem -keyid
619 Send a signed message under Unix directly to sendmail, including headers:
621 openssl cms -sign -in in.txt -text -signer mycert.pem \
622 -from steve@openssl.org -to someone@somewhere \
623 -subject "Signed message" | sendmail someone@somewhere
625 Verify a message and extract the signer's certificate if successful:
627 openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt
629 Send encrypted mail using triple DES:
631 openssl cms -encrypt -in in.txt -from steve@openssl.org \
632 -to someone@somewhere -subject "Encrypted message" \
633 -des3 user.pem -out mail.msg
635 Sign and encrypt mail:
637 openssl cms -sign -in ml.txt -signer my.pem -text \
638 | openssl cms -encrypt -out mail.msg \
639 -from steve@openssl.org -to someone@somewhere \
640 -subject "Signed and Encrypted message" -des3 user.pem
642 Note: the encryption command does not include the B<-text> option because the
643 message being encrypted already has MIME headers.
647 openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
649 The output from Netscape form signing is a PKCS#7 structure with the
650 detached signature format. You can use this program to verify the
651 signature by line wrapping the base64 encoded structure and surrounding
654 -----BEGIN PKCS7-----
657 and using the command,
659 openssl cms -verify -inform PEM -in signature.pem -content content.txt
661 alternatively you can base64 decode the signature and use
663 openssl cms -verify -inform DER -in signature.der -content content.txt
665 Create an encrypted message using 128 bit Camellia:
667 openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
669 Add a signer to an existing message:
671 openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg
673 Sign mail using RSA-PSS:
675 openssl cms -sign -in message.txt -text -out mail.msg \
676 -signer mycert.pem -keyopt rsa_padding_mode:pss
678 Create encrypted mail using RSA-OAEP:
680 openssl cms -encrypt -in plain.txt -out mail.msg \
681 -recip cert.pem -keyopt rsa_padding_mode:oaep
683 Use SHA256 KDF with an ECDH certificate:
685 openssl cms -encrypt -in plain.txt -out mail.msg \
686 -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
690 The MIME parser isn't very clever: it seems to handle most messages that I've
691 thrown at it but it may choke on others.
693 The code currently will only write out the signer's certificate to a file: if
694 the signer has a separate encryption certificate this must be manually
695 extracted. There should be some heuristic that determines the correct
696 encryption certificate.
698 Ideally a database should be maintained of a certificates for each email
701 The code doesn't currently take note of the permitted symmetric encryption
702 algorithms as supplied in the SMIMECapabilities signed attribute. this means the
703 user has to manually include the correct encryption algorithm. It should store
704 the list of permitted ciphers in a database and only use those.
706 No revocation checking is done on the signer's certificate.
710 The use of multiple B<-signer> options and the B<-resign> command were first
711 added in OpenSSL 1.0.0
713 The B<keyopt> option was first added in OpenSSL 1.1.0
715 The use of B<-recip> to specify the recipient when encrypting mail was first
716 added to OpenSSL 1.1.0
718 Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0.
720 The use of non-RSA keys with B<-encrypt> and B<-decrypt> was first added
723 The -no_alt_chains options was first added to OpenSSL 1.1.0.
727 Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
729 Licensed under the OpenSSL license (the "License"). You may not use
730 this file except in compliance with the License. You can obtain a copy
731 in the file LICENSE in the source distribution or at
732 L<https://www.openssl.org/source/license.html>.