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