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