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