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