cms.pod revision 306195
1=pod 2 3=head1 NAME 4 5cms - CMS utility 6 7=head1 SYNOPSIS 8 9B<openssl> B<cms> 10[B<-encrypt>] 11[B<-decrypt>] 12[B<-sign>] 13[B<-verify>] 14[B<-cmsout>] 15[B<-resign>] 16[B<-data_create>] 17[B<-data_out>] 18[B<-digest_create>] 19[B<-digest_verify>] 20[B<-compress>] 21[B<-uncompress>] 22[B<-EncryptedData_encrypt>] 23[B<-sign_receipt>] 24[B<-verify_receipt receipt>] 25[B<-in filename>] 26[B<-inform SMIME|PEM|DER>] 27[B<-rctform SMIME|PEM|DER>] 28[B<-out filename>] 29[B<-outform SMIME|PEM|DER>] 30[B<-stream -indef -noindef>] 31[B<-noindef>] 32[B<-content filename>] 33[B<-text>] 34[B<-noout>] 35[B<-print>] 36[B<-CAfile file>] 37[B<-CApath dir>] 38[B<-no_alt_chains>] 39[B<-md digest>] 40[B<-[cipher]>] 41[B<-nointern>] 42[B<-no_signer_cert_verify>] 43[B<-nocerts>] 44[B<-noattr>] 45[B<-nosmimecap>] 46[B<-binary>] 47[B<-nodetach>] 48[B<-certfile file>] 49[B<-certsout file>] 50[B<-signer file>] 51[B<-recip file>] 52[B<-keyid>] 53[B<-receipt_request_all -receipt_request_first>] 54[B<-receipt_request_from emailaddress>] 55[B<-receipt_request_to emailaddress>] 56[B<-receipt_request_print>] 57[B<-secretkey key>] 58[B<-secretkeyid id>] 59[B<-econtent_type type>] 60[B<-inkey file>] 61[B<-keyopt name:parameter>] 62[B<-passin arg>] 63[B<-rand file(s)>] 64[B<cert.pem...>] 65[B<-to addr>] 66[B<-from addr>] 67[B<-subject subj>] 68[cert.pem]... 69 70=head1 DESCRIPTION 71 72The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and 73verify, compress and uncompress S/MIME messages. 74 75=head1 COMMAND OPTIONS 76 77There are fourteen operation options that set the type of operation to be 78performed. The meaning of the other options varies according to the operation 79type. 80 81=over 4 82 83=item B<-encrypt> 84 85encrypt mail for the given recipient certificates. Input file is the message 86to be encrypted. The output file is the encrypted mail in MIME format. The 87actual CMS type is <B>EnvelopedData<B>. 88 89Note that no revocation check is done for the recipient cert, so if that 90key has been compromised, others may be able to decrypt the text. 91 92=item B<-decrypt> 93 94decrypt mail using the supplied certificate and private key. Expects an 95encrypted mail message in MIME format for the input file. The decrypted mail 96is written to the output file. 97 98=item B<-debug_decrypt> 99 100this option sets the B<CMS_DEBUG_DECRYPT> flag. This option should be used 101with caution: see the notes section below. 102 103=item B<-sign> 104 105sign mail using the supplied certificate and private key. Input file is 106the message to be signed. The signed message in MIME format is written 107to the output file. 108 109=item B<-verify> 110 111verify signed mail. Expects a signed mail message on input and outputs 112the signed data. Both clear text and opaque signing is supported. 113 114=item B<-cmsout> 115 116takes an input message and writes out a PEM encoded CMS structure. 117 118=item B<-resign> 119 120resign a message: take an existing message and one or more new signers. 121 122=item B<-data_create> 123 124Create a CMS B<Data> type. 125 126=item B<-data_out> 127 128B<Data> type and output the content. 129 130=item B<-digest_create> 131 132Create a CMS B<DigestedData> type. 133 134=item B<-digest_verify> 135 136Verify a CMS B<DigestedData> type and output the content. 137 138=item B<-compress> 139 140Create a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib> 141support for this option to work, otherwise it will output an error. 142 143=item B<-uncompress> 144 145Uncompress a CMS B<CompressedData> type and output the content. OpenSSL must be 146compiled with B<zlib> support for this option to work, otherwise it will 147output an error. 148 149=item B<-EncryptedData_encrypt> 150 151Encrypt content using supplied symmetric key and algorithm using a CMS 152B<EncrytedData> type and output the content. 153 154=item B<-sign_receipt> 155 156Generate and output a signed receipt for the supplied message. The input 157message B<must> contain a signed receipt request. Functionality is otherwise 158similar to the B<-sign> operation. 159 160=item B<-verify_receipt receipt> 161 162Verify a signed receipt in filename B<receipt>. The input message B<must> 163contain the original receipt request. Functionality is otherwise similar 164to the B<-verify> operation. 165 166=item B<-in filename> 167 168the input message to be encrypted or signed or the message to be decrypted 169or verified. 170 171=item B<-inform SMIME|PEM|DER> 172 173this specifies the input format for the CMS structure. The default 174is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> 175format change this to expect PEM and DER format CMS structures 176instead. This currently only affects the input format of the CMS 177structure, if no CMS structure is being input (for example with 178B<-encrypt> or B<-sign>) this option has no effect. 179 180=item B<-rctform SMIME|PEM|DER> 181 182specify the format for a signed receipt for use with the B<-receipt_verify> 183operation. 184 185=item B<-out filename> 186 187the message text that has been decrypted or verified or the output MIME 188format message that has been signed or verified. 189 190=item B<-outform SMIME|PEM|DER> 191 192this specifies the output format for the CMS structure. The default 193is B<SMIME> which writes an S/MIME format message. B<PEM> and B<DER> 194format change this to write PEM and DER format CMS structures 195instead. This currently only affects the output format of the CMS 196structure, if no CMS structure is being output (for example with 197B<-verify> or B<-decrypt>) this option has no effect. 198 199=item B<-stream -indef -noindef> 200 201the B<-stream> and B<-indef> options are equivalent and enable streaming I/O 202for encoding operations. This permits single pass processing of data without 203the need to hold the entire contents in memory, potentially supporting very 204large files. Streaming is automatically set for S/MIME signing with detached 205data if the output format is B<SMIME> it is currently off by default for all 206other operations. 207 208=item B<-noindef> 209 210disable streaming I/O where it would produce and indefinite length constructed 211encoding. This option currently has no effect. In future streaming will be 212enabled by default on all relevant operations and this option will disable it. 213 214=item B<-content filename> 215 216This specifies a file containing the detached content, this is only 217useful with the B<-verify> command. This is only usable if the CMS 218structure is using the detached signature form where the content is 219not included. This option will override any content if the input format 220is S/MIME and it uses the multipart/signed MIME content type. 221 222=item B<-text> 223 224this option adds plain text (text/plain) MIME headers to the supplied 225message if encrypting or signing. If decrypting or verifying it strips 226off text headers: if the decrypted or verified message is not of MIME 227type text/plain then an error occurs. 228 229=item B<-noout> 230 231for the B<-cmsout> operation do not output the parsed CMS structure. This 232is useful when combined with the B<-print> option or if the syntax of the CMS 233structure is being checked. 234 235=item B<-print> 236 237for the B<-cmsout> operation print out all fields of the CMS structure. This 238is mainly useful for testing purposes. 239 240=item B<-CAfile file> 241 242a file containing trusted CA certificates, only used with B<-verify>. 243 244=item B<-CApath dir> 245 246a directory containing trusted CA certificates, only used with 247B<-verify>. This directory must be a standard certificate directory: that 248is a hash of each subject name (using B<x509 -hash>) should be linked 249to each certificate. 250 251=item B<-md digest> 252 253digest algorithm to use when signing or resigning. If not present then the 254default digest algorithm for the signing key will be used (usually SHA1). 255 256=item B<-[cipher]> 257 258the encryption algorithm to use. For example triple DES (168 bits) - B<-des3> 259or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the 260EVP_get_cipherbyname() function) can also be used preceded by a dash, for 261example B<-aes_128_cbc>. See L<B<enc>|enc(1)> for a list of ciphers 262supported by your version of OpenSSL. 263 264If not specified triple DES is used. Only used with B<-encrypt> and 265B<-EncryptedData_create> commands. 266 267=item B<-nointern> 268 269when verifying a message normally certificates (if any) included in 270the message are searched for the signing certificate. With this option 271only the certificates specified in the B<-certfile> option are used. 272The supplied certificates can still be used as untrusted CAs however. 273 274=item B<-no_signer_cert_verify> 275 276do not verify the signers certificate of a signed message. 277 278=item B<-nocerts> 279 280when signing a message the signer's certificate is normally included 281with this option it is excluded. This will reduce the size of the 282signed message but the verifier must have a copy of the signers certificate 283available locally (passed using the B<-certfile> option for example). 284 285=item B<-noattr> 286 287normally when a message is signed a set of attributes are included which 288include the signing time and supported symmetric algorithms. With this 289option they are not included. 290 291=item B<-nosmimecap> 292 293exclude the list of supported algorithms from signed attributes, other options 294such as signing time and content type are still included. 295 296=item B<-binary> 297 298normally the input message is converted to "canonical" format which is 299effectively using CR and LF as end of line: as required by the S/MIME 300specification. When this option is present no translation occurs. This 301is useful when handling binary data which may not be in MIME format. 302 303=item B<-nodetach> 304 305when signing a message use opaque signing: this form is more resistant 306to translation by mail relays but it cannot be read by mail agents that 307do not support S/MIME. Without this option cleartext signing with 308the MIME type multipart/signed is used. 309 310=item B<-certfile file> 311 312allows additional certificates to be specified. When signing these will 313be included with the message. When verifying these will be searched for 314the signers certificates. The certificates should be in PEM format. 315 316=item B<-certsout file> 317 318any certificates contained in the message are written to B<file>. 319 320=item B<-signer file> 321 322a signing certificate when signing or resigning a message, this option can be 323used multiple times if more than one signer is required. If a message is being 324verified then the signers certificates will be written to this file if the 325verification was successful. 326 327=item B<-recip file> 328 329when decrypting a message this specifies the recipients certificate. The 330certificate must match one of the recipients of the message or an error 331occurs. 332 333When encrypting a message this option may be used multiple times to specify 334each recipient. This form B<must> be used if customised parameters are 335required (for example to specify RSA-OAEP). 336 337=item B<-keyid> 338 339use subject key identifier to identify certificates instead of issuer name and 340serial number. The supplied certificate B<must> include a subject key 341identifier extension. Supported by B<-sign> and B<-encrypt> options. 342 343=item B<-receipt_request_all -receipt_request_first> 344 345for B<-sign> option include a signed receipt request. Indicate requests should 346be provided by all receipient or first tier recipients (those mailed directly 347and not from a mailing list). Ignored it B<-receipt_request_from> is included. 348 349=item B<-receipt_request_from emailaddress> 350 351for B<-sign> option include a signed receipt request. Add an explicit email 352address where receipts should be supplied. 353 354=item B<-receipt_request_to emailaddress> 355 356Add an explicit email address where signed receipts should be sent to. This 357option B<must> but supplied if a signed receipt it requested. 358 359=item B<-receipt_request_print> 360 361For the B<-verify> operation print out the contents of any signed receipt 362requests. 363 364=item B<-secretkey key> 365 366specify symmetric key to use. The key must be supplied in hex format and be 367consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt> 368B<-EncrryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used 369with B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the 370content encryption key using an AES key in the B<KEKRecipientInfo> type. 371 372=item B<-secretkeyid id> 373 374the key identifier for the supplied symmetric key for B<KEKRecipientInfo> type. 375This option B<must> be present if the B<-secretkey> option is used with 376B<-encrypt>. With B<-decrypt> operations the B<id> is used to locate the 377relevant key if it is not supplied then an attempt is used to decrypt any 378B<KEKRecipientInfo> structures. 379 380=item B<-econtent_type type> 381 382set the encapsulated content type to B<type> if not supplied the B<Data> type 383is used. The B<type> argument can be any valid OID name in either text or 384numerical format. 385 386=item B<-inkey file> 387 388the private key to use when signing or decrypting. This must match the 389corresponding certificate. If this option is not specified then the 390private key must be included in the certificate file specified with 391the B<-recip> or B<-signer> file. When signing this option can be used 392multiple times to specify successive keys. 393 394=item B<-keyopt name:opt> 395 396for signing and encryption this option can be used multiple times to 397set customised parameters for the preceding key or certificate. It can 398currently be used to set RSA-PSS for signing, RSA-OAEP for encryption 399or to modify default parameters for ECDH. 400 401=item B<-passin arg> 402 403the private key password source. For more information about the format of B<arg> 404see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 405 406=item B<-rand file(s)> 407 408a file or files containing random data used to seed the random number 409generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 410Multiple files can be specified separated by a OS-dependent character. 411The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for 412all others. 413 414=item B<cert.pem...> 415 416one or more certificates of message recipients: used when encrypting 417a message. 418 419=item B<-to, -from, -subject> 420 421the relevant mail headers. These are included outside the signed 422portion of a message so they may be included manually. If signing 423then many S/MIME mail clients check the signers certificate's email 424address matches that specified in the From: address. 425 426=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains> 427 428Set various certificate chain valiadition option. See the 429L<B<verify>|verify(1)> manual page for details. 430 431=back 432 433=head1 NOTES 434 435The MIME message must be sent without any blank lines between the 436headers and the output. Some mail programs will automatically add 437a blank line. Piping the mail directly to sendmail is one way to 438achieve the correct format. 439 440The supplied message to be signed or encrypted must include the 441necessary MIME headers or many S/MIME clients wont display it 442properly (if at all). You can use the B<-text> option to automatically 443add plain text headers. 444 445A "signed and encrypted" message is one where a signed message is 446then encrypted. This can be produced by encrypting an already signed 447message: see the examples section. 448 449This version of the program only allows one signer per message but it 450will verify multiple signers on received messages. Some S/MIME clients 451choke if a message contains multiple signers. It is possible to sign 452messages "in parallel" by signing an already signed message. 453 454The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME 455clients. Strictly speaking these process CMS enveloped data: CMS 456encrypted data is used for other purposes. 457 458The B<-resign> option uses an existing message digest when adding a new 459signer. This means that attributes must be present in at least one existing 460signer using the same message digest or this operation will fail. 461 462The B<-stream> and B<-indef> options enable experimental streaming I/O support. 463As a result the encoding is BER using indefinite length constructed encoding 464and no longer DER. Streaming is supported for the B<-encrypt> operation and the 465B<-sign> operation if the content is not detached. 466 467Streaming is always used for the B<-sign> operation with detached data but 468since the content is no longer part of the CMS structure the encoding 469remains DER. 470 471If the B<-decrypt> option is used without a recipient certificate then an 472attempt is made to locate the recipient by trying each potential recipient 473in turn using the supplied private key. To thwart the MMA attack 474(Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are 475tried whether they succeed or not and if no recipients match the message 476is "decrypted" using a random key which will typically output garbage. 477The B<-debug_decrypt> option can be used to disable the MMA attack protection 478and return an error if no recipient can be found: this option should be used 479with caution. For a fuller description see L<CMS_decrypt(3)|CMS_decrypt(3)>). 480 481=head1 EXIT CODES 482 483=over 4 484 485=item Z<>0 486 487the operation was completely successfully. 488 489=item Z<>1 490 491an error occurred parsing the command options. 492 493=item Z<>2 494 495one of the input files could not be read. 496 497=item Z<>3 498 499an error occurred creating the CMS file or when reading the MIME 500message. 501 502=item Z<>4 503 504an error occurred decrypting or verifying the message. 505 506=item Z<>5 507 508the message was verified correctly but an error occurred writing out 509the signers certificates. 510 511=back 512 513=head1 COMPATIBILITY WITH PKCS#7 format. 514 515The B<smime> utility can only process the older B<PKCS#7> format. The B<cms> 516utility supports Cryptographic Message Syntax format. Use of some features 517will result in messages which cannot be processed by applications which only 518support the older format. These are detailed below. 519 520The use of the B<-keyid> option with B<-sign> or B<-encrypt>. 521 522The B<-outform PEM> option uses different headers. 523 524The B<-compress> option. 525 526The B<-secretkey> option when used with B<-encrypt>. 527 528The use of PSS with B<-sign>. 529 530The use of OAEP or non-RSA keys with B<-encrypt>. 531 532Additionally the B<-EncryptedData_create> and B<-data_create> type cannot 533be processed by the older B<smime> command. 534 535=head1 EXAMPLES 536 537Create a cleartext signed message: 538 539 openssl cms -sign -in message.txt -text -out mail.msg \ 540 -signer mycert.pem 541 542Create an opaque signed message 543 544 openssl cms -sign -in message.txt -text -out mail.msg -nodetach \ 545 -signer mycert.pem 546 547Create a signed message, include some additional certificates and 548read the private key from another file: 549 550 openssl cms -sign -in in.txt -text -out mail.msg \ 551 -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem 552 553Create a signed message with two signers, use key identifier: 554 555 openssl cms -sign -in message.txt -text -out mail.msg \ 556 -signer mycert.pem -signer othercert.pem -keyid 557 558Send a signed message under Unix directly to sendmail, including headers: 559 560 openssl cms -sign -in in.txt -text -signer mycert.pem \ 561 -from steve@openssl.org -to someone@somewhere \ 562 -subject "Signed message" | sendmail someone@somewhere 563 564Verify a message and extract the signer's certificate if successful: 565 566 openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt 567 568Send encrypted mail using triple DES: 569 570 openssl cms -encrypt -in in.txt -from steve@openssl.org \ 571 -to someone@somewhere -subject "Encrypted message" \ 572 -des3 user.pem -out mail.msg 573 574Sign and encrypt mail: 575 576 openssl cms -sign -in ml.txt -signer my.pem -text \ 577 | openssl cms -encrypt -out mail.msg \ 578 -from steve@openssl.org -to someone@somewhere \ 579 -subject "Signed and Encrypted message" -des3 user.pem 580 581Note: the encryption command does not include the B<-text> option because the 582message being encrypted already has MIME headers. 583 584Decrypt mail: 585 586 openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem 587 588The output from Netscape form signing is a PKCS#7 structure with the 589detached signature format. You can use this program to verify the 590signature by line wrapping the base64 encoded structure and surrounding 591it with: 592 593 -----BEGIN PKCS7----- 594 -----END PKCS7----- 595 596and using the command, 597 598 openssl cms -verify -inform PEM -in signature.pem -content content.txt 599 600alternatively you can base64 decode the signature and use 601 602 openssl cms -verify -inform DER -in signature.der -content content.txt 603 604Create an encrypted message using 128 bit Camellia: 605 606 openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem 607 608Add a signer to an existing message: 609 610 openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg 611 612Sign mail using RSA-PSS: 613 614 openssl cms -sign -in message.txt -text -out mail.msg \ 615 -signer mycert.pem -keyopt rsa_padding_mode:pss 616 617Create encrypted mail using RSA-OAEP: 618 619 openssl cms -encrypt -in plain.txt -out mail.msg \ 620 -recip cert.pem -keyopt rsa_padding_mode:oaep 621 622Use SHA256 KDF with an ECDH certificate: 623 624 openssl cms -encrypt -in plain.txt -out mail.msg \ 625 -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256 626 627=head1 BUGS 628 629The MIME parser isn't very clever: it seems to handle most messages that I've 630thrown at it but it may choke on others. 631 632The code currently will only write out the signer's certificate to a file: if 633the signer has a separate encryption certificate this must be manually 634extracted. There should be some heuristic that determines the correct 635encryption certificate. 636 637Ideally a database should be maintained of a certificates for each email 638address. 639 640The code doesn't currently take note of the permitted symmetric encryption 641algorithms as supplied in the SMIMECapabilities signed attribute. this means the 642user has to manually include the correct encryption algorithm. It should store 643the list of permitted ciphers in a database and only use those. 644 645No revocation checking is done on the signer's certificate. 646 647=head1 HISTORY 648 649The use of multiple B<-signer> options and the B<-resign> command were first 650added in OpenSSL 1.0.0 651 652The B<keyopt> option was first added in OpenSSL 1.1.0 653 654The use of B<-recip> to specify the recipient when encrypting mail was first 655added to OpenSSL 1.1.0 656 657Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0. 658 659The use of non-RSA keys with B<-encrypt> and B<-decrypt> was first added 660to OpenSSL 1.1.0. 661 662The -no_alt_chains options was first added to OpenSSL 1.0.2b. 663 664=cut 665