cms.pod revision 284285
1238384Sjkim=pod 2238384Sjkim 3238384Sjkim=head1 NAME 4238384Sjkim 5238384Sjkimcms - CMS utility 6238384Sjkim 7238384Sjkim=head1 SYNOPSIS 8238384Sjkim 9238384SjkimB<openssl> B<cms> 10238384Sjkim[B<-encrypt>] 11238384Sjkim[B<-decrypt>] 12238384Sjkim[B<-sign>] 13238384Sjkim[B<-verify>] 14238384Sjkim[B<-cmsout>] 15238384Sjkim[B<-resign>] 16238384Sjkim[B<-data_create>] 17238384Sjkim[B<-data_out>] 18238384Sjkim[B<-digest_create>] 19238384Sjkim[B<-digest_verify>] 20238384Sjkim[B<-compress>] 21238384Sjkim[B<-uncompress>] 22238384Sjkim[B<-EncryptedData_encrypt>] 23238384Sjkim[B<-sign_receipt>] 24238384Sjkim[B<-verify_receipt receipt>] 25238384Sjkim[B<-in filename>] 26238384Sjkim[B<-inform SMIME|PEM|DER>] 27238384Sjkim[B<-rctform SMIME|PEM|DER>] 28238384Sjkim[B<-out filename>] 29238384Sjkim[B<-outform SMIME|PEM|DER>] 30238384Sjkim[B<-stream -indef -noindef>] 31238384Sjkim[B<-noindef>] 32238384Sjkim[B<-content filename>] 33238384Sjkim[B<-text>] 34238384Sjkim[B<-noout>] 35238384Sjkim[B<-print>] 36238384Sjkim[B<-CAfile file>] 37238384Sjkim[B<-CApath dir>] 38284285Sjkim[B<-no_alt_chains>] 39238384Sjkim[B<-md digest>] 40238384Sjkim[B<-[cipher]>] 41238384Sjkim[B<-nointern>] 42238384Sjkim[B<-no_signer_cert_verify>] 43238384Sjkim[B<-nocerts>] 44238384Sjkim[B<-noattr>] 45238384Sjkim[B<-nosmimecap>] 46238384Sjkim[B<-binary>] 47238384Sjkim[B<-nodetach>] 48238384Sjkim[B<-certfile file>] 49238384Sjkim[B<-certsout file>] 50238384Sjkim[B<-signer file>] 51238384Sjkim[B<-recip file>] 52238384Sjkim[B<-keyid>] 53238384Sjkim[B<-receipt_request_all -receipt_request_first>] 54238384Sjkim[B<-receipt_request_from emailaddress>] 55238384Sjkim[B<-receipt_request_to emailaddress>] 56238384Sjkim[B<-receipt_request_print>] 57238384Sjkim[B<-secretkey key>] 58238384Sjkim[B<-secretkeyid id>] 59238384Sjkim[B<-econtent_type type>] 60238384Sjkim[B<-inkey file>] 61238384Sjkim[B<-passin arg>] 62238384Sjkim[B<-rand file(s)>] 63238384Sjkim[B<cert.pem...>] 64238384Sjkim[B<-to addr>] 65238384Sjkim[B<-from addr>] 66238384Sjkim[B<-subject subj>] 67238384Sjkim[cert.pem]... 68238384Sjkim 69238384Sjkim=head1 DESCRIPTION 70238384Sjkim 71238384SjkimThe B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and 72238384Sjkimverify, compress and uncompress S/MIME messages. 73238384Sjkim 74238384Sjkim=head1 COMMAND OPTIONS 75238384Sjkim 76238384SjkimThere are fourteen operation options that set the type of operation to be 77238384Sjkimperformed. The meaning of the other options varies according to the operation 78238384Sjkimtype. 79238384Sjkim 80238384Sjkim=over 4 81238384Sjkim 82238384Sjkim=item B<-encrypt> 83238384Sjkim 84238384Sjkimencrypt mail for the given recipient certificates. Input file is the message 85238384Sjkimto be encrypted. The output file is the encrypted mail in MIME format. The 86238384Sjkimactual CMS type is <B>EnvelopedData<B>. 87238384Sjkim 88238384Sjkim=item B<-decrypt> 89238384Sjkim 90238384Sjkimdecrypt mail using the supplied certificate and private key. Expects an 91238384Sjkimencrypted mail message in MIME format for the input file. The decrypted mail 92238384Sjkimis written to the output file. 93238384Sjkim 94267258Sjkim=item B<-debug_decrypt> 95267258Sjkim 96267258Sjkimthis option sets the B<CMS_DEBUG_DECRYPT> flag. This option should be used 97267258Sjkimwith caution: see the notes section below. 98267258Sjkim 99238384Sjkim=item B<-sign> 100238384Sjkim 101238384Sjkimsign mail using the supplied certificate and private key. Input file is 102238384Sjkimthe message to be signed. The signed message in MIME format is written 103238384Sjkimto the output file. 104238384Sjkim 105238384Sjkim=item B<-verify> 106238384Sjkim 107238384Sjkimverify signed mail. Expects a signed mail message on input and outputs 108238384Sjkimthe signed data. Both clear text and opaque signing is supported. 109238384Sjkim 110238384Sjkim=item B<-cmsout> 111238384Sjkim 112238384Sjkimtakes an input message and writes out a PEM encoded CMS structure. 113238384Sjkim 114238384Sjkim=item B<-resign> 115238384Sjkim 116238384Sjkimresign a message: take an existing message and one or more new signers. 117238384Sjkim 118238384Sjkim=item B<-data_create> 119238384Sjkim 120238384SjkimCreate a CMS B<Data> type. 121238384Sjkim 122238384Sjkim=item B<-data_out> 123238384Sjkim 124238384SjkimB<Data> type and output the content. 125238384Sjkim 126238384Sjkim=item B<-digest_create> 127238384Sjkim 128238384SjkimCreate a CMS B<DigestedData> type. 129238384Sjkim 130238384Sjkim=item B<-digest_verify> 131238384Sjkim 132238384SjkimVerify a CMS B<DigestedData> type and output the content. 133238384Sjkim 134238384Sjkim=item B<-compress> 135238384Sjkim 136238384SjkimCreate a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib> 137238384Sjkimsupport for this option to work, otherwise it will output an error. 138238384Sjkim 139238384Sjkim=item B<-uncompress> 140238384Sjkim 141238384SjkimUncompress a CMS B<CompressedData> type and output the content. OpenSSL must be 142238384Sjkimcompiled with B<zlib> support for this option to work, otherwise it will 143238384Sjkimoutput an error. 144238384Sjkim 145238384Sjkim=item B<-EncryptedData_encrypt> 146238384Sjkim 147269686SjkimEncrypt content using supplied symmetric key and algorithm using a CMS 148238384SjkimB<EncrytedData> type and output the content. 149238384Sjkim 150238384Sjkim=item B<-sign_receipt> 151238384Sjkim 152238384SjkimGenerate and output a signed receipt for the supplied message. The input 153238384Sjkimmessage B<must> contain a signed receipt request. Functionality is otherwise 154238384Sjkimsimilar to the B<-sign> operation. 155238384Sjkim 156238384Sjkim=item B<-verify_receipt receipt> 157238384Sjkim 158238384SjkimVerify a signed receipt in filename B<receipt>. The input message B<must> 159238384Sjkimcontain the original receipt request. Functionality is otherwise similar 160238384Sjkimto the B<-verify> operation. 161238384Sjkim 162238384Sjkim=item B<-in filename> 163238384Sjkim 164238384Sjkimthe input message to be encrypted or signed or the message to be decrypted 165238384Sjkimor verified. 166238384Sjkim 167238384Sjkim=item B<-inform SMIME|PEM|DER> 168238384Sjkim 169238384Sjkimthis specifies the input format for the CMS structure. The default 170238384Sjkimis B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> 171238384Sjkimformat change this to expect PEM and DER format CMS structures 172238384Sjkiminstead. This currently only affects the input format of the CMS 173238384Sjkimstructure, if no CMS structure is being input (for example with 174238384SjkimB<-encrypt> or B<-sign>) this option has no effect. 175238384Sjkim 176238384Sjkim=item B<-rctform SMIME|PEM|DER> 177238384Sjkim 178238384Sjkimspecify the format for a signed receipt for use with the B<-receipt_verify> 179238384Sjkimoperation. 180238384Sjkim 181238384Sjkim=item B<-out filename> 182238384Sjkim 183238384Sjkimthe message text that has been decrypted or verified or the output MIME 184238384Sjkimformat message that has been signed or verified. 185238384Sjkim 186238384Sjkim=item B<-outform SMIME|PEM|DER> 187238384Sjkim 188238384Sjkimthis specifies the output format for the CMS structure. The default 189238384Sjkimis B<SMIME> which writes an S/MIME format message. B<PEM> and B<DER> 190238384Sjkimformat change this to write PEM and DER format CMS structures 191238384Sjkiminstead. This currently only affects the output format of the CMS 192238384Sjkimstructure, if no CMS structure is being output (for example with 193238384SjkimB<-verify> or B<-decrypt>) this option has no effect. 194238384Sjkim 195238384Sjkim=item B<-stream -indef -noindef> 196238384Sjkim 197238384Sjkimthe B<-stream> and B<-indef> options are equivalent and enable streaming I/O 198238384Sjkimfor encoding operations. This permits single pass processing of data without 199238384Sjkimthe need to hold the entire contents in memory, potentially supporting very 200238384Sjkimlarge files. Streaming is automatically set for S/MIME signing with detached 201238384Sjkimdata if the output format is B<SMIME> it is currently off by default for all 202238384Sjkimother operations. 203238384Sjkim 204238384Sjkim=item B<-noindef> 205238384Sjkim 206238384Sjkimdisable streaming I/O where it would produce and indefinite length constructed 207238384Sjkimencoding. This option currently has no effect. In future streaming will be 208238384Sjkimenabled by default on all relevant operations and this option will disable it. 209238384Sjkim 210238384Sjkim=item B<-content filename> 211238384Sjkim 212238384SjkimThis specifies a file containing the detached content, this is only 213238384Sjkimuseful with the B<-verify> command. This is only usable if the CMS 214238384Sjkimstructure is using the detached signature form where the content is 215238384Sjkimnot included. This option will override any content if the input format 216238384Sjkimis S/MIME and it uses the multipart/signed MIME content type. 217238384Sjkim 218238384Sjkim=item B<-text> 219238384Sjkim 220238384Sjkimthis option adds plain text (text/plain) MIME headers to the supplied 221238384Sjkimmessage if encrypting or signing. If decrypting or verifying it strips 222238384Sjkimoff text headers: if the decrypted or verified message is not of MIME 223238384Sjkimtype text/plain then an error occurs. 224238384Sjkim 225238384Sjkim=item B<-noout> 226238384Sjkim 227238384Sjkimfor the B<-cmsout> operation do not output the parsed CMS structure. This 228238384Sjkimis useful when combined with the B<-print> option or if the syntax of the CMS 229238384Sjkimstructure is being checked. 230238384Sjkim 231238384Sjkim=item B<-print> 232238384Sjkim 233238384Sjkimfor the B<-cmsout> operation print out all fields of the CMS structure. This 234238384Sjkimis mainly useful for testing purposes. 235238384Sjkim 236238384Sjkim=item B<-CAfile file> 237238384Sjkim 238238384Sjkima file containing trusted CA certificates, only used with B<-verify>. 239238384Sjkim 240238384Sjkim=item B<-CApath dir> 241238384Sjkim 242238384Sjkima directory containing trusted CA certificates, only used with 243238384SjkimB<-verify>. This directory must be a standard certificate directory: that 244238384Sjkimis a hash of each subject name (using B<x509 -hash>) should be linked 245238384Sjkimto each certificate. 246238384Sjkim 247238384Sjkim=item B<-md digest> 248238384Sjkim 249238384Sjkimdigest algorithm to use when signing or resigning. If not present then the 250238384Sjkimdefault digest algorithm for the signing key will be used (usually SHA1). 251238384Sjkim 252238384Sjkim=item B<-[cipher]> 253238384Sjkim 254238384Sjkimthe encryption algorithm to use. For example triple DES (168 bits) - B<-des3> 255238384Sjkimor 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the 256238384SjkimEVP_get_cipherbyname() function) can also be used preceded by a dash, for 257238384Sjkimexample B<-aes_128_cbc>. See L<B<enc>|enc(1)> for a list of ciphers 258238384Sjkimsupported by your version of OpenSSL. 259238384Sjkim 260238384SjkimIf not specified triple DES is used. Only used with B<-encrypt> and 261238384SjkimB<-EncryptedData_create> commands. 262238384Sjkim 263238384Sjkim=item B<-nointern> 264238384Sjkim 265238384Sjkimwhen verifying a message normally certificates (if any) included in 266238384Sjkimthe message are searched for the signing certificate. With this option 267238384Sjkimonly the certificates specified in the B<-certfile> option are used. 268238384SjkimThe supplied certificates can still be used as untrusted CAs however. 269238384Sjkim 270238384Sjkim=item B<-no_signer_cert_verify> 271238384Sjkim 272238384Sjkimdo not verify the signers certificate of a signed message. 273238384Sjkim 274238384Sjkim=item B<-nocerts> 275238384Sjkim 276238384Sjkimwhen signing a message the signer's certificate is normally included 277238384Sjkimwith this option it is excluded. This will reduce the size of the 278238384Sjkimsigned message but the verifier must have a copy of the signers certificate 279238384Sjkimavailable locally (passed using the B<-certfile> option for example). 280238384Sjkim 281238384Sjkim=item B<-noattr> 282238384Sjkim 283238384Sjkimnormally when a message is signed a set of attributes are included which 284238384Sjkiminclude the signing time and supported symmetric algorithms. With this 285238384Sjkimoption they are not included. 286238384Sjkim 287238384Sjkim=item B<-nosmimecap> 288238384Sjkim 289238384Sjkimexclude the list of supported algorithms from signed attributes, other options 290238384Sjkimsuch as signing time and content type are still included. 291238384Sjkim 292238384Sjkim=item B<-binary> 293238384Sjkim 294238384Sjkimnormally the input message is converted to "canonical" format which is 295238384Sjkimeffectively using CR and LF as end of line: as required by the S/MIME 296238384Sjkimspecification. When this option is present no translation occurs. This 297238384Sjkimis useful when handling binary data which may not be in MIME format. 298238384Sjkim 299238384Sjkim=item B<-nodetach> 300238384Sjkim 301238384Sjkimwhen signing a message use opaque signing: this form is more resistant 302238384Sjkimto translation by mail relays but it cannot be read by mail agents that 303238384Sjkimdo not support S/MIME. Without this option cleartext signing with 304238384Sjkimthe MIME type multipart/signed is used. 305238384Sjkim 306238384Sjkim=item B<-certfile file> 307238384Sjkim 308238384Sjkimallows additional certificates to be specified. When signing these will 309238384Sjkimbe included with the message. When verifying these will be searched for 310238384Sjkimthe signers certificates. The certificates should be in PEM format. 311238384Sjkim 312238384Sjkim=item B<-certsout file> 313238384Sjkim 314238384Sjkimany certificates contained in the message are written to B<file>. 315238384Sjkim 316238384Sjkim=item B<-signer file> 317238384Sjkim 318238384Sjkima signing certificate when signing or resigning a message, this option can be 319238384Sjkimused multiple times if more than one signer is required. If a message is being 320238384Sjkimverified then the signers certificates will be written to this file if the 321238384Sjkimverification was successful. 322238384Sjkim 323238384Sjkim=item B<-recip file> 324238384Sjkim 325238384Sjkimthe recipients certificate when decrypting a message. This certificate 326238384Sjkimmust match one of the recipients of the message or an error occurs. 327238384Sjkim 328238384Sjkim=item B<-keyid> 329238384Sjkim 330238384Sjkimuse subject key identifier to identify certificates instead of issuer name and 331238384Sjkimserial number. The supplied certificate B<must> include a subject key 332238384Sjkimidentifier extension. Supported by B<-sign> and B<-encrypt> options. 333238384Sjkim 334238384Sjkim=item B<-receipt_request_all -receipt_request_first> 335238384Sjkim 336238384Sjkimfor B<-sign> option include a signed receipt request. Indicate requests should 337238384Sjkimbe provided by all receipient or first tier recipients (those mailed directly 338238384Sjkimand not from a mailing list). Ignored it B<-receipt_request_from> is included. 339238384Sjkim 340238384Sjkim=item B<-receipt_request_from emailaddress> 341238384Sjkim 342238384Sjkimfor B<-sign> option include a signed receipt request. Add an explicit email 343238384Sjkimaddress where receipts should be supplied. 344238384Sjkim 345238384Sjkim=item B<-receipt_request_to emailaddress> 346238384Sjkim 347238384SjkimAdd an explicit email address where signed receipts should be sent to. This 348238384Sjkimoption B<must> but supplied if a signed receipt it requested. 349238384Sjkim 350238384Sjkim=item B<-receipt_request_print> 351238384Sjkim 352238384SjkimFor the B<-verify> operation print out the contents of any signed receipt 353238384Sjkimrequests. 354238384Sjkim 355238384Sjkim=item B<-secretkey key> 356238384Sjkim 357238384Sjkimspecify symmetric key to use. The key must be supplied in hex format and be 358238384Sjkimconsistent with the algorithm used. Supported by the B<-EncryptedData_encrypt> 359238384SjkimB<-EncrryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used 360238384Sjkimwith B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the 361238384Sjkimcontent encryption key using an AES key in the B<KEKRecipientInfo> type. 362238384Sjkim 363238384Sjkim=item B<-secretkeyid id> 364238384Sjkim 365238384Sjkimthe key identifier for the supplied symmetric key for B<KEKRecipientInfo> type. 366238384SjkimThis option B<must> be present if the B<-secretkey> option is used with 367238384SjkimB<-encrypt>. With B<-decrypt> operations the B<id> is used to locate the 368238384Sjkimrelevant key if it is not supplied then an attempt is used to decrypt any 369238384SjkimB<KEKRecipientInfo> structures. 370238384Sjkim 371238384Sjkim=item B<-econtent_type type> 372238384Sjkim 373238384Sjkimset the encapsulated content type to B<type> if not supplied the B<Data> type 374238384Sjkimis used. The B<type> argument can be any valid OID name in either text or 375238384Sjkimnumerical format. 376238384Sjkim 377238384Sjkim=item B<-inkey file> 378238384Sjkim 379238384Sjkimthe private key to use when signing or decrypting. This must match the 380238384Sjkimcorresponding certificate. If this option is not specified then the 381238384Sjkimprivate key must be included in the certificate file specified with 382238384Sjkimthe B<-recip> or B<-signer> file. When signing this option can be used 383238384Sjkimmultiple times to specify successive keys. 384238384Sjkim 385238384Sjkim=item B<-passin arg> 386238384Sjkim 387238384Sjkimthe private key password source. For more information about the format of B<arg> 388238384Sjkimsee the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 389238384Sjkim 390238384Sjkim=item B<-rand file(s)> 391238384Sjkim 392238384Sjkima file or files containing random data used to seed the random number 393238384Sjkimgenerator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 394238384SjkimMultiple files can be specified separated by a OS-dependent character. 395238384SjkimThe separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for 396238384Sjkimall others. 397238384Sjkim 398238384Sjkim=item B<cert.pem...> 399238384Sjkim 400238384Sjkimone or more certificates of message recipients: used when encrypting 401238384Sjkima message. 402238384Sjkim 403238384Sjkim=item B<-to, -from, -subject> 404238384Sjkim 405238384Sjkimthe relevant mail headers. These are included outside the signed 406238384Sjkimportion of a message so they may be included manually. If signing 407238384Sjkimthen many S/MIME mail clients check the signers certificate's email 408238384Sjkimaddress matches that specified in the From: address. 409238384Sjkim 410284285Sjkim=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> 411238384Sjkim 412238384SjkimSet various certificate chain valiadition option. See the 413238384SjkimL<B<verify>|verify(1)> manual page for details. 414238384Sjkim 415238384Sjkim=back 416238384Sjkim 417238384Sjkim=head1 NOTES 418238384Sjkim 419238384SjkimThe MIME message must be sent without any blank lines between the 420238384Sjkimheaders and the output. Some mail programs will automatically add 421238384Sjkima blank line. Piping the mail directly to sendmail is one way to 422238384Sjkimachieve the correct format. 423238384Sjkim 424238384SjkimThe supplied message to be signed or encrypted must include the 425238384Sjkimnecessary MIME headers or many S/MIME clients wont display it 426238384Sjkimproperly (if at all). You can use the B<-text> option to automatically 427238384Sjkimadd plain text headers. 428238384Sjkim 429238384SjkimA "signed and encrypted" message is one where a signed message is 430238384Sjkimthen encrypted. This can be produced by encrypting an already signed 431238384Sjkimmessage: see the examples section. 432238384Sjkim 433238384SjkimThis version of the program only allows one signer per message but it 434238384Sjkimwill verify multiple signers on received messages. Some S/MIME clients 435238384Sjkimchoke if a message contains multiple signers. It is possible to sign 436238384Sjkimmessages "in parallel" by signing an already signed message. 437238384Sjkim 438238384SjkimThe options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME 439238384Sjkimclients. Strictly speaking these process CMS enveloped data: CMS 440238384Sjkimencrypted data is used for other purposes. 441238384Sjkim 442238384SjkimThe B<-resign> option uses an existing message digest when adding a new 443238384Sjkimsigner. This means that attributes must be present in at least one existing 444238384Sjkimsigner using the same message digest or this operation will fail. 445238384Sjkim 446238384SjkimThe B<-stream> and B<-indef> options enable experimental streaming I/O support. 447238384SjkimAs a result the encoding is BER using indefinite length constructed encoding 448238384Sjkimand no longer DER. Streaming is supported for the B<-encrypt> operation and the 449238384SjkimB<-sign> operation if the content is not detached. 450238384Sjkim 451238384SjkimStreaming is always used for the B<-sign> operation with detached data but 452238384Sjkimsince the content is no longer part of the CMS structure the encoding 453238384Sjkimremains DER. 454238384Sjkim 455267258SjkimIf the B<-decrypt> option is used without a recipient certificate then an 456267258Sjkimattempt is made to locate the recipient by trying each potential recipient 457267258Sjkimin turn using the supplied private key. To thwart the MMA attack 458267258Sjkim(Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are 459267258Sjkimtried whether they succeed or not and if no recipients match the message 460267258Sjkimis "decrypted" using a random key which will typically output garbage. 461267258SjkimThe B<-debug_decrypt> option can be used to disable the MMA attack protection 462267258Sjkimand return an error if no recipient can be found: this option should be used 463267258Sjkimwith caution. For a fuller description see L<CMS_decrypt(3)|CMS_decrypt(3)>). 464267258Sjkim 465238384Sjkim=head1 EXIT CODES 466238384Sjkim 467238384Sjkim=over 4 468238384Sjkim 469264331Sjkim=item Z<>0 470238384Sjkim 471238384Sjkimthe operation was completely successfully. 472238384Sjkim 473264331Sjkim=item Z<>1 474238384Sjkim 475238384Sjkiman error occurred parsing the command options. 476238384Sjkim 477264331Sjkim=item Z<>2 478238384Sjkim 479238384Sjkimone of the input files could not be read. 480238384Sjkim 481264331Sjkim=item Z<>3 482238384Sjkim 483238384Sjkiman error occurred creating the CMS file or when reading the MIME 484238384Sjkimmessage. 485238384Sjkim 486264331Sjkim=item Z<>4 487238384Sjkim 488238384Sjkiman error occurred decrypting or verifying the message. 489238384Sjkim 490264331Sjkim=item Z<>5 491238384Sjkim 492238384Sjkimthe message was verified correctly but an error occurred writing out 493238384Sjkimthe signers certificates. 494238384Sjkim 495238384Sjkim=back 496238384Sjkim 497238384Sjkim=head1 COMPATIBILITY WITH PKCS#7 format. 498238384Sjkim 499238384SjkimThe B<smime> utility can only process the older B<PKCS#7> format. The B<cms> 500238384Sjkimutility supports Cryptographic Message Syntax format. Use of some features 501238384Sjkimwill result in messages which cannot be processed by applications which only 502238384Sjkimsupport the older format. These are detailed below. 503238384Sjkim 504238384SjkimThe use of the B<-keyid> option with B<-sign> or B<-encrypt>. 505238384Sjkim 506238384SjkimThe B<-outform PEM> option uses different headers. 507238384Sjkim 508238384SjkimThe B<-compress> option. 509238384Sjkim 510238384SjkimThe B<-secretkey> option when used with B<-encrypt>. 511238384Sjkim 512238384SjkimAdditionally the B<-EncryptedData_create> and B<-data_create> type cannot 513238384Sjkimbe processed by the older B<smime> command. 514238384Sjkim 515238384Sjkim=head1 EXAMPLES 516238384Sjkim 517238384SjkimCreate a cleartext signed message: 518238384Sjkim 519238384Sjkim openssl cms -sign -in message.txt -text -out mail.msg \ 520238384Sjkim -signer mycert.pem 521238384Sjkim 522238384SjkimCreate an opaque signed message 523238384Sjkim 524238384Sjkim openssl cms -sign -in message.txt -text -out mail.msg -nodetach \ 525238384Sjkim -signer mycert.pem 526238384Sjkim 527238384SjkimCreate a signed message, include some additional certificates and 528238384Sjkimread the private key from another file: 529238384Sjkim 530238384Sjkim openssl cms -sign -in in.txt -text -out mail.msg \ 531238384Sjkim -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem 532238384Sjkim 533238384SjkimCreate a signed message with two signers, use key identifier: 534238384Sjkim 535238384Sjkim openssl cms -sign -in message.txt -text -out mail.msg \ 536238384Sjkim -signer mycert.pem -signer othercert.pem -keyid 537238384Sjkim 538238384SjkimSend a signed message under Unix directly to sendmail, including headers: 539238384Sjkim 540238384Sjkim openssl cms -sign -in in.txt -text -signer mycert.pem \ 541238384Sjkim -from steve@openssl.org -to someone@somewhere \ 542238384Sjkim -subject "Signed message" | sendmail someone@somewhere 543238384Sjkim 544238384SjkimVerify a message and extract the signer's certificate if successful: 545238384Sjkim 546238384Sjkim openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt 547238384Sjkim 548238384SjkimSend encrypted mail using triple DES: 549238384Sjkim 550238384Sjkim openssl cms -encrypt -in in.txt -from steve@openssl.org \ 551238384Sjkim -to someone@somewhere -subject "Encrypted message" \ 552238384Sjkim -des3 user.pem -out mail.msg 553238384Sjkim 554238384SjkimSign and encrypt mail: 555238384Sjkim 556238384Sjkim openssl cms -sign -in ml.txt -signer my.pem -text \ 557238384Sjkim | openssl cms -encrypt -out mail.msg \ 558238384Sjkim -from steve@openssl.org -to someone@somewhere \ 559238384Sjkim -subject "Signed and Encrypted message" -des3 user.pem 560238384Sjkim 561238384SjkimNote: the encryption command does not include the B<-text> option because the 562238384Sjkimmessage being encrypted already has MIME headers. 563238384Sjkim 564238384SjkimDecrypt mail: 565238384Sjkim 566238384Sjkim openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem 567238384Sjkim 568238384SjkimThe output from Netscape form signing is a PKCS#7 structure with the 569238384Sjkimdetached signature format. You can use this program to verify the 570238384Sjkimsignature by line wrapping the base64 encoded structure and surrounding 571238384Sjkimit with: 572238384Sjkim 573238384Sjkim -----BEGIN PKCS7----- 574238384Sjkim -----END PKCS7----- 575238384Sjkim 576238384Sjkimand using the command, 577238384Sjkim 578238384Sjkim openssl cms -verify -inform PEM -in signature.pem -content content.txt 579238384Sjkim 580238384Sjkimalternatively you can base64 decode the signature and use 581238384Sjkim 582238384Sjkim openssl cms -verify -inform DER -in signature.der -content content.txt 583238384Sjkim 584238384SjkimCreate an encrypted message using 128 bit Camellia: 585238384Sjkim 586238384Sjkim openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem 587238384Sjkim 588238384SjkimAdd a signer to an existing message: 589238384Sjkim 590238384Sjkim openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg 591238384Sjkim 592238384Sjkim=head1 BUGS 593238384Sjkim 594238384SjkimThe MIME parser isn't very clever: it seems to handle most messages that I've 595238384Sjkimthrown at it but it may choke on others. 596238384Sjkim 597238384SjkimThe code currently will only write out the signer's certificate to a file: if 598238384Sjkimthe signer has a separate encryption certificate this must be manually 599238384Sjkimextracted. There should be some heuristic that determines the correct 600238384Sjkimencryption certificate. 601238384Sjkim 602238384SjkimIdeally a database should be maintained of a certificates for each email 603238384Sjkimaddress. 604238384Sjkim 605238384SjkimThe code doesn't currently take note of the permitted symmetric encryption 606238384Sjkimalgorithms as supplied in the SMIMECapabilities signed attribute. this means the 607238384Sjkimuser has to manually include the correct encryption algorithm. It should store 608238384Sjkimthe list of permitted ciphers in a database and only use those. 609238384Sjkim 610238384SjkimNo revocation checking is done on the signer's certificate. 611238384Sjkim 612238384Sjkim=head1 HISTORY 613238384Sjkim 614238384SjkimThe use of multiple B<-signer> options and the B<-resign> command were first 615238384Sjkimadded in OpenSSL 1.0.0 616238384Sjkim 617238384Sjkim 618284285SjkimThe -no_alt_chains options was first added to OpenSSL 1.0.1n and 1.0.2b. 619284285Sjkim 620238384Sjkim=cut 621