doc/man1/openssl-cms.pod.in

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