smime.pod revision 267256
12061Sjkh=pod 250479Speter 32061Sjkh=head1 NAME 438666Sjb 532427Sjbsmime - S/MIME utility 6111131Sru 7111131Sru=head1 SYNOPSIS 838666Sjb 938666SjbB<openssl> B<smime> 1038666Sjb[B<-encrypt>] 11159363Strhodes[B<-decrypt>] 1264049Salex[B<-sign>] 1364049Salex[B<-resign>] 14116679Ssimokawa[B<-verify>] 1566071Smarkm[B<-pk7out>] 16116679Ssimokawa[B<-[cipher]>] 1773504Sobrien[B<-in file>] 18158962Snetchild[B<-certfile file>] 1938666Sjb[B<-signer file>] 20148330Snetchild[B<-recip file>] 21148330Snetchild[B<-inform SMIME|PEM|DER>] 22148330Snetchild[B<-passin arg>] 2332427Sjb[B<-inkey file>] 2438666Sjb[B<-out file>] 25108451Sschweikh[B<-outform SMIME|PEM|DER>] 2638666Sjb[B<-content file>] 2738666Sjb[B<-to addr>] 2838666Sjb[B<-from ad>] 2938666Sjb[B<-subject s>] 3017308Speter[B<-text>] 3191606Skeramida[B<-indef>] 3219175Sbde[B<-noindef>] 3396205Sjwd[B<-stream>] 3496205Sjwd[B<-rand file(s)>] 3538042Sbde[B<-md digest>] 3696205Sjwd[cert.pem]... 3796205Sjwd 3838042Sbde=head1 DESCRIPTION 3996205Sjwd 40159363StrhodesThe B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and 41159363Strhodesverify S/MIME messages. 4217308Speter 4396205Sjwd=head1 COMMAND OPTIONS 4496205Sjwd 4517308SpeterThere are six operation options that set the type of operation to be performed. 46148330SnetchildThe meaning of the other options varies according to the operation type. 47148330Snetchild 48148330Snetchild=over 4 49148330Snetchild 50159831Sobrien=item B<-encrypt> 51148330Snetchild 52148330Snetchildencrypt mail for the given recipient certificates. Input file is the message 53148330Snetchildto be encrypted. The output file is the encrypted mail in MIME format. 54148330Snetchild 55148330Snetchild=item B<-decrypt> 56148330Snetchild 57148330Snetchilddecrypt mail using the supplied certificate and private key. Expects an 5896205Sjwdencrypted mail message in MIME format for the input file. The decrypted mail 5996205Sjwdis written to the output file. 6096205Sjwd 61162147Sru=item B<-sign> 62162147Sru 6398723Sdillonsign mail using the supplied certificate and private key. Input file is 6498723Sdillonthe message to be signed. The signed message in MIME format is written 6598723Sdillonto the output file. 6638666Sjb 6738666Sjb=item B<-verify> 6817308Speter 69123311Speterverify signed mail. Expects a signed mail message on input and outputs 70123311Speterthe signed data. Both clear text and opaque signing is supported. 71123311Speter 72123311Speter=item B<-pk7out> 73159349Simp 74159349Simptakes an input message and writes out a PEM encoded PKCS#7 structure. 75159349Simp 76158962Snetchild=item B<-resign> 77158962Snetchild 78158962Snetchildresign a message: take an existing message and one or more new signers. 79156840Sru 80123311Speter=item B<-in filename> 81137288Speter 82147425Sruthe input message to be encrypted or signed or the MIME message to 83156740Srube decrypted or verified. 842061Sjkh 8597769Sru=item B<-inform SMIME|PEM|DER> 8697252Sru 87119579Sruthis specifies the input format for the PKCS#7 structure. The default 8897252Sruis B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> 8995730Sruformat change this to expect PEM and DER format PKCS#7 structures 9095793Sruinstead. This currently only affects the input format of the PKCS#7 91111617Srustructure, if no PKCS#7 structure is being input (for example with 9295730SruB<-encrypt> or B<-sign>) this option has no effect. 93116679Ssimokawa 9495730Sru=item B<-out filename> 95116679Ssimokawa 9695730Sruthe message text that has been decrypted or verified or the output MIME 97110035Sruformat message that has been signed or verified. 98107516Sru 99138921Sru=item B<-outform SMIME|PEM|DER> 100156145Syar 101138921Sruthis specifies the output format for the PKCS#7 structure. The default 102133942Sruis B<SMIME> which write an S/MIME format message. B<PEM> and B<DER> 103133942Sruformat change this to write PEM and DER format PKCS#7 structures 104156145Syarinstead. This currently only affects the output format of the PKCS#7 105133942Srustructure, if no PKCS#7 structure is being output (for example with 106110035SruB<-verify> or B<-decrypt>) this option has no effect. 107117234Sru 108110035Sru=item B<-stream -indef -noindef> 109117229Sru 110117234Sruthe B<-stream> and B<-indef> options are equivalent and enable streaming I/O 11154324Smarcelfor encoding operations. This permits single pass processing of data without 11217308Speterthe need to hold the entire contents in memory, potentially supporting very 113119519Smarcellarge files. Streaming is automatically set for S/MIME signing with detached 114119519Smarceldata if the output format is B<SMIME> it is currently off by default for all 115119519Smarcelother operations. 116119519Smarcel 117119519Smarcel=item B<-noindef> 118119519Smarcel 119119579Srudisable streaming I/O where it would produce and indefinite length constructed 120119519Smarcelencoding. This option currently has no effect. In future streaming will be 121119519Smarcelenabled by default on all relevant operations and this option will disable it. 122119519Smarcel 123119519Smarcel=item B<-content filename> 124119519Smarcel 125126031SgadThis specifies a file containing the detached content, this is only 126126024Sgaduseful with the B<-verify> command. This is only usable if the PKCS#7 127126024Sgadstructure is using the detached signature form where the content is 128126024Sgadnot included. This option will override any content if the input format 129126024Sgadis S/MIME and it uses the multipart/signed MIME content type. 130126024Sgad 131126024Sgad=item B<-text> 132126024Sgad 133126024Sgadthis option adds plain text (text/plain) MIME headers to the supplied 134126024Sgadmessage if encrypting or signing. If decrypting or verifying it strips 135126024Sgadoff text headers: if the decrypted or verified message is not of MIME 136126024Sgadtype text/plain then an error occurs. 137126024Sgad 138126024Sgad=item B<-CAfile file> 139126031Sgad 140126024Sgada file containing trusted CA certificates, only used with B<-verify>. 141126024Sgad 142126024Sgad=item B<-CApath dir> 143126024Sgad 144126024Sgada directory containing trusted CA certificates, only used with 145126024SgadB<-verify>. This directory must be a standard certificate directory: that 146126024Sgadis a hash of each subject name (using B<x509 -hash>) should be linked 147133376Shartito each certificate. 148126024Sgad 149126024Sgad=item B<-md digest> 150126024Sgad 151126024Sgaddigest algorithm to use when signing or resigning. If not present then the 152126024Sgaddefault digest algorithm for the signing key will be used (usually SHA1). 153125885Sgad 154125885Sgad=item B<-[cipher]> 15538666Sjb 15617308Speterthe encryption algorithm to use. For example DES (56 bits) - B<-des>, 157119519Smarceltriple DES (168 bits) - B<-des3>, 158119579SruEVP_get_cipherbyname() function) can also be used preceded by a dash, for 159133376Shartiexample B<-aes_128_cbc>. See L<B<enc>|enc(1)> for list of ciphers 160110035Srusupported by your version of OpenSSL. 1612302Spaul 16239206SjkhIf not specified triple DES is used. Only used with B<-encrypt>. 16339206Sjkh 16439206Sjkh=item B<-nointern> 165133945Sru 166133945Sruwhen verifying a message normally certificates (if any) included in 167132358Smarkmthe message are searched for the signing certificate. With this option 16817308Speteronly the certificates specified in the B<-certfile> option are used. 16954324SmarcelThe supplied certificates can still be used as untrusted CAs however. 17054324Smarcel 171132234Smarcel=item B<-noverify> 172132234Smarcel 173132234Smarceldo not verify the signers certificate of a signed message. 174132234Smarcel 17554324Smarcel=item B<-nochain> 17654324Smarcel 17754324Smarceldo not do chain verification of signers certificates: that is don't 178118531Sruuse the certificates in the signed message as untrusted CAs. 17954324Smarcel 18054324Smarcel=item B<-nosigs> 18154324Smarcel 18254324Smarceldon't try to verify the signatures on the message. 18354324Smarcel 18454324Smarcel=item B<-nocerts> 185133376Sharti 18654324Smarcelwhen signing a message the signer's certificate is normally included 187133376Shartiwith this option it is excluded. This will reduce the size of the 188133376Shartisigned message but the verifier must have a copy of the signers certificate 18954324Smarcelavailable locally (passed using the B<-certfile> option for example). 19054324Smarcel 19154324Smarcel=item B<-noattr> 19254324Smarcel 19354324Smarcelnormally when a message is signed a set of attributes are included which 194133376Shartiinclude the signing time and supported symmetric algorithms. With this 19554324Smarceloption they are not included. 19654324Smarcel 19754324Smarcel=item B<-binary> 198118531Sru 199118531Srunormally the input message is converted to "canonical" format which is 20054324Smarceleffectively using CR and LF as end of line: as required by the S/MIME 201132234Smarcelspecification. When this option is present no translation occurs. This 202132234Smarcelis useful when handling binary data which may not be in MIME format. 203132234Smarcel 204132234Smarcel=item B<-nodetach> 205132234Smarcel 206132588Skensmithwhen signing a message use opaque signing: this form is more resistant 207132358Smarkmto translation by mail relays but it cannot be read by mail agents that 208132234Smarceldo not support S/MIME. Without this option cleartext signing with 209132358Smarkmthe MIME type multipart/signed is used. 210132234Smarcel 211132234Smarcel=item B<-certfile file> 212132234Smarcel 21354324Smarcelallows additional certificates to be specified. When signing these will 21454324Smarcelbe included with the message. When verifying these will be searched for 21595730Sruthe signers certificates. The certificates should be in PEM format. 21695730Sru 21795730Sru=item B<-signer file> 21895730Sru 21995730Srua signing certificate when signing or resigning a message, this option can be 22095730Sruused multiple times if more than one signer is required. If a message is being 22195730Sruverified then the signers certificates will be written to this file if the 22238666Sjbverification was successful. 223107374Sru 22417308Speter=item B<-recip file> 22555678Smarcel 226143032Shartithe recipients certificate when decrypting a message. This certificate 227138515Shartimust match one of the recipients of the message or an error occurs. 228117793Sru 229110035Sru=item B<-inkey file> 230110035Sru 231110035Sruthe private key to use when signing or decrypting. This must match the 2322061Sjkhcorresponding certificate. If this option is not specified then the 23317308Speterprivate key must be included in the certificate file specified with 234107516Sruthe B<-recip> or B<-signer> file. When signing this option can be used 235107374Srumultiple times to specify successive keys. 23655678Smarcel 237107516Sru=item B<-passin arg> 238107516Sru 239107516Sruthe private key password source. For more information about the format of B<arg> 240107516Srusee the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 241107516Sru 242139112Sru=item B<-rand file(s)> 243164470Sjb 244107516Srua file or files containing random data used to seed the random number 245122204Skrisgenerator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 24655678SmarcelMultiple files can be specified separated by a OS-dependent character. 24755678SmarcelThe separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for 248116696Sruall others. 24955678Smarcel 250133376Sharti=item B<cert.pem...> 251107516Sru 252107516Sruone or more certificates of message recipients: used when encrypting 253107516Srua message. 254107516Sru 25555678Smarcel=item B<-to, -from, -subject> 25655678Smarcel 257111131Sruthe relevant mail headers. These are included outside the signed 258111131Sruportion of a message so they may be included manually. If signing 259111131Sruthen many S/MIME mail clients check the signers certificate's email 260133945Sruaddress matches that specified in the From: address. 261111131Sru 262111131Sru=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig> 263148154Sru 264168280SmarcelSet various options of certificate chain verification. See 265168280SmarcelL<B<verify>|verify(1)> manual page for details. 266133945Sru 267133945Sru=back 268103985Sphk 269103985Sphk=head1 NOTES 270103985Sphk 271168280SmarcelThe MIME message must be sent without any blank lines between the 272162147Sruheaders and the output. Some mail programs will automatically add 273152879Srua blank line. Piping the mail directly to sendmail is one way to 274152880Sruachieve the correct format. 275148154Sru 276162147SruThe supplied message to be signed or encrypted must include the 277162147Srunecessary MIME headers or many S/MIME clients wont display it 278162147Sruproperly (if at all). You can use the B<-text> option to automatically 279162147Sruadd plain text headers. 280131876Sphk 281162147SruA "signed and encrypted" message is one where a signed message is 282111131Sruthen encrypted. This can be produced by encrypting an already signed 283162147Srumessage: see the examples section. 284162147Sru 285162147SruThis version of the program only allows one signer per message but it 286162147Sruwill verify multiple signers on received messages. Some S/MIME clients 287162147Sruchoke if a message contains multiple signers. It is possible to sign 288103985Sphkmessages "in parallel" by signing an already signed message. 289148154Sru 290148154SruThe options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME 291162147Sruclients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 292148154Sruencrypted data is used for other purposes. 293148154Sru 294162147SruThe B<-resign> option uses an existing message digest when adding a new 295148154Srusigner. This means that attributes must be present in at least one existing 296162147Srusigner using the same message digest or this operation will fail. 297103985Sphk 298133945SruThe B<-stream> and B<-indef> options enable experimental streaming I/O support. 299133945SruAs a result the encoding is BER using indefinite length constructed encoding 300103985Sphkand no longer DER. Streaming is supported for the B<-encrypt> operation and the 301118531SruB<-sign> operation if the content is not detached. 302118531Sru 303103985SphkStreaming is always used for the B<-sign> operation with detached data but 304133945Srusince the content is no longer part of the PKCS#7 structure the encoding 305remains DER. 306 307=head1 EXIT CODES 308 309=over 4 310 311=item Z<>0 312 313the operation was completely successfully. 314 315=item Z<>1 316 317an error occurred parsing the command options. 318 319=item Z<>2 320 321one of the input files could not be read. 322 323=item Z<>3 324 325an error occurred creating the PKCS#7 file or when reading the MIME 326message. 327 328=item Z<>4 329 330an error occurred decrypting or verifying the message. 331 332=item Z<>5 333 334the message was verified correctly but an error occurred writing out 335the signers certificates. 336 337=back 338 339=head1 EXAMPLES 340 341Create a cleartext signed message: 342 343 openssl smime -sign -in message.txt -text -out mail.msg \ 344 -signer mycert.pem 345 346Create an opaque signed message: 347 348 openssl smime -sign -in message.txt -text -out mail.msg -nodetach \ 349 -signer mycert.pem 350 351Create a signed message, include some additional certificates and 352read the private key from another file: 353 354 openssl smime -sign -in in.txt -text -out mail.msg \ 355 -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem 356 357Create a signed message with two signers: 358 359 openssl smime -sign -in message.txt -text -out mail.msg \ 360 -signer mycert.pem -signer othercert.pem 361 362Send a signed message under Unix directly to sendmail, including headers: 363 364 openssl smime -sign -in in.txt -text -signer mycert.pem \ 365 -from steve@openssl.org -to someone@somewhere \ 366 -subject "Signed message" | sendmail someone@somewhere 367 368Verify a message and extract the signer's certificate if successful: 369 370 openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt 371 372Send encrypted mail using triple DES: 373 374 openssl smime -encrypt -in in.txt -from steve@openssl.org \ 375 -to someone@somewhere -subject "Encrypted message" \ 376 -des3 user.pem -out mail.msg 377 378Sign and encrypt mail: 379 380 openssl smime -sign -in ml.txt -signer my.pem -text \ 381 | openssl smime -encrypt -out mail.msg \ 382 -from steve@openssl.org -to someone@somewhere \ 383 -subject "Signed and Encrypted message" -des3 user.pem 384 385Note: the encryption command does not include the B<-text> option because the 386message being encrypted already has MIME headers. 387 388Decrypt mail: 389 390 openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem 391 392The output from Netscape form signing is a PKCS#7 structure with the 393detached signature format. You can use this program to verify the 394signature by line wrapping the base64 encoded structure and surrounding 395it with: 396 397 -----BEGIN PKCS7----- 398 -----END PKCS7----- 399 400and using the command: 401 402 openssl smime -verify -inform PEM -in signature.pem -content content.txt 403 404Alternatively you can base64 decode the signature and use: 405 406 openssl smime -verify -inform DER -in signature.der -content content.txt 407 408Create an encrypted message using 128 bit Camellia: 409 410 openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem 411 412Add a signer to an existing message: 413 414 openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg 415 416=head1 BUGS 417 418The MIME parser isn't very clever: it seems to handle most messages that I've 419thrown at it but it may choke on others. 420 421The code currently will only write out the signer's certificate to a file: if 422the signer has a separate encryption certificate this must be manually 423extracted. There should be some heuristic that determines the correct 424encryption certificate. 425 426Ideally a database should be maintained of a certificates for each email 427address. 428 429The code doesn't currently take note of the permitted symmetric encryption 430algorithms as supplied in the SMIMECapabilities signed attribute. This means the 431user has to manually include the correct encryption algorithm. It should store 432the list of permitted ciphers in a database and only use those. 433 434No revocation checking is done on the signer's certificate. 435 436The current code can only handle S/MIME v2 messages, the more complex S/MIME v3 437structures may cause parsing errors. 438 439=head1 HISTORY 440 441The use of multiple B<-signer> options and the B<-resign> command were first 442added in OpenSSL 1.0.0 443 444 445=cut 446