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