smime.pod revision 238405
159191Skris=pod 259191Skris 359191Skris=head1 NAME 459191Skris 559191Skrissmime - S/MIME utility 659191Skris 759191Skris=head1 SYNOPSIS 859191Skris 959191SkrisB<openssl> B<smime> 1059191Skris[B<-encrypt>] 1159191Skris[B<-decrypt>] 1259191Skris[B<-sign>] 13238405Sjkim[B<-resign>] 1459191Skris[B<-verify>] 1559191Skris[B<-pk7out>] 16238405Sjkim[B<-[cipher]>] 1759191Skris[B<-in file>] 1859191Skris[B<-certfile file>] 1959191Skris[B<-signer file>] 2059191Skris[B<-recip file>] 2168651Skris[B<-inform SMIME|PEM|DER>] 2268651Skris[B<-passin arg>] 2359191Skris[B<-inkey file>] 2459191Skris[B<-out file>] 2568651Skris[B<-outform SMIME|PEM|DER>] 2668651Skris[B<-content file>] 2759191Skris[B<-to addr>] 2859191Skris[B<-from ad>] 2959191Skris[B<-subject s>] 3059191Skris[B<-text>] 31238405Sjkim[B<-indef>] 32238405Sjkim[B<-noindef>] 33238405Sjkim[B<-stream>] 3459191Skris[B<-rand file(s)>] 35238405Sjkim[B<-md digest>] 3659191Skris[cert.pem]... 3759191Skris 3859191Skris=head1 DESCRIPTION 3959191Skris 4059191SkrisThe B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and 4159191Skrisverify S/MIME messages. 4259191Skris 4359191Skris=head1 COMMAND OPTIONS 4459191Skris 45238405SjkimThere are six operation options that set the type of operation to be performed. 4659191SkrisThe meaning of the other options varies according to the operation type. 4759191Skris 4859191Skris=over 4 4959191Skris 5059191Skris=item B<-encrypt> 5159191Skris 5259191Skrisencrypt mail for the given recipient certificates. Input file is the message 5359191Skristo be encrypted. The output file is the encrypted mail in MIME format. 5459191Skris 5559191Skris=item B<-decrypt> 5659191Skris 5759191Skrisdecrypt mail using the supplied certificate and private key. Expects an 5859191Skrisencrypted mail message in MIME format for the input file. The decrypted mail 5959191Skrisis written to the output file. 6059191Skris 6159191Skris=item B<-sign> 6259191Skris 6359191Skrissign mail using the supplied certificate and private key. Input file is 6459191Skristhe message to be signed. The signed message in MIME format is written 6559191Skristo the output file. 6659191Skris 6759191Skris=item B<-verify> 6859191Skris 6959191Skrisverify signed mail. Expects a signed mail message on input and outputs 7059191Skristhe signed data. Both clear text and opaque signing is supported. 7159191Skris 7259191Skris=item B<-pk7out> 7359191Skris 7459191Skristakes an input message and writes out a PEM encoded PKCS#7 structure. 7559191Skris 76238405Sjkim=item B<-resign> 77238405Sjkim 78238405Sjkimresign a message: take an existing message and one or more new signers. 79238405Sjkim 8059191Skris=item B<-in filename> 8159191Skris 8259191Skristhe input message to be encrypted or signed or the MIME message to 8359191Skrisbe decrypted or verified. 8459191Skris 8568651Skris=item B<-inform SMIME|PEM|DER> 8668651Skris 8768651Skristhis specifies the input format for the PKCS#7 structure. The default 8868651Skrisis B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> 8968651Skrisformat change this to expect PEM and DER format PKCS#7 structures 9068651Skrisinstead. This currently only affects the input format of the PKCS#7 9168651Skrisstructure, if no PKCS#7 structure is being input (for example with 9268651SkrisB<-encrypt> or B<-sign>) this option has no effect. 9368651Skris 9459191Skris=item B<-out filename> 9559191Skris 9659191Skristhe message text that has been decrypted or verified or the output MIME 9759191Skrisformat message that has been signed or verified. 9859191Skris 9968651Skris=item B<-outform SMIME|PEM|DER> 10068651Skris 10168651Skristhis specifies the output format for the PKCS#7 structure. The default 10268651Skrisis B<SMIME> which write an S/MIME format message. B<PEM> and B<DER> 10368651Skrisformat change this to write PEM and DER format PKCS#7 structures 10468651Skrisinstead. This currently only affects the output format of the PKCS#7 10568651Skrisstructure, if no PKCS#7 structure is being output (for example with 10668651SkrisB<-verify> or B<-decrypt>) this option has no effect. 10768651Skris 108238405Sjkim=item B<-stream -indef -noindef> 109238405Sjkim 110238405Sjkimthe B<-stream> and B<-indef> options are equivalent and enable streaming I/O 111238405Sjkimfor encoding operations. This permits single pass processing of data without 112238405Sjkimthe need to hold the entire contents in memory, potentially supporting very 113238405Sjkimlarge files. Streaming is automatically set for S/MIME signing with detached 114238405Sjkimdata if the output format is B<SMIME> it is currently off by default for all 115238405Sjkimother operations. 116238405Sjkim 117238405Sjkim=item B<-noindef> 118238405Sjkim 119238405Sjkimdisable streaming I/O where it would produce and indefinite length constructed 120238405Sjkimencoding. This option currently has no effect. In future streaming will be 121238405Sjkimenabled by default on all relevant operations and this option will disable it. 122238405Sjkim 12368651Skris=item B<-content filename> 12468651Skris 12568651SkrisThis specifies a file containing the detached content, this is only 12668651Skrisuseful with the B<-verify> command. This is only usable if the PKCS#7 12768651Skrisstructure is using the detached signature form where the content is 12868651Skrisnot included. This option will override any content if the input format 12968651Skrisis S/MIME and it uses the multipart/signed MIME content type. 13068651Skris 13159191Skris=item B<-text> 13259191Skris 13359191Skristhis option adds plain text (text/plain) MIME headers to the supplied 13459191Skrismessage if encrypting or signing. If decrypting or verifying it strips 13559191Skrisoff text headers: if the decrypted or verified message is not of MIME 13659191Skristype text/plain then an error occurs. 13759191Skris 13859191Skris=item B<-CAfile file> 13959191Skris 14059191Skrisa file containing trusted CA certificates, only used with B<-verify>. 14159191Skris 14259191Skris=item B<-CApath dir> 14359191Skris 14459191Skrisa directory containing trusted CA certificates, only used with 14559191SkrisB<-verify>. This directory must be a standard certificate directory: that 14659191Skrisis a hash of each subject name (using B<x509 -hash>) should be linked 14759191Skristo each certificate. 14859191Skris 149238405Sjkim=item B<-md digest> 15059191Skris 151238405Sjkimdigest algorithm to use when signing or resigning. If not present then the 152238405Sjkimdefault digest algorithm for the signing key will be used (usually SHA1). 15359191Skris 154238405Sjkim=item B<-[cipher]> 155238405Sjkim 156238405Sjkimthe encryption algorithm to use. For example DES (56 bits) - B<-des>, 157238405Sjkimtriple DES (168 bits) - B<-des3>, 158238405SjkimEVP_get_cipherbyname() function) can also be used preceded by a dash, for 159238405Sjkimexample B<-aes_128_cbc>. See L<B<enc>|enc(1)> for list of ciphers 160238405Sjkimsupported by your version of OpenSSL. 161238405Sjkim 162238405SjkimIf not specified 40 bit RC2 is used. Only used with B<-encrypt>. 163238405Sjkim 16459191Skris=item B<-nointern> 16559191Skris 16659191Skriswhen verifying a message normally certificates (if any) included in 16759191Skristhe message are searched for the signing certificate. With this option 16859191Skrisonly the certificates specified in the B<-certfile> option are used. 16959191SkrisThe supplied certificates can still be used as untrusted CAs however. 17059191Skris 17159191Skris=item B<-noverify> 17259191Skris 17359191Skrisdo not verify the signers certificate of a signed message. 17459191Skris 17559191Skris=item B<-nochain> 17659191Skris 17759191Skrisdo not do chain verification of signers certificates: that is don't 17859191Skrisuse the certificates in the signed message as untrusted CAs. 17959191Skris 18059191Skris=item B<-nosigs> 18159191Skris 18259191Skrisdon't try to verify the signatures on the message. 18359191Skris 18459191Skris=item B<-nocerts> 18559191Skris 18659191Skriswhen signing a message the signer's certificate is normally included 18759191Skriswith this option it is excluded. This will reduce the size of the 18859191Skrissigned message but the verifier must have a copy of the signers certificate 18959191Skrisavailable locally (passed using the B<-certfile> option for example). 19059191Skris 19159191Skris=item B<-noattr> 19259191Skris 19359191Skrisnormally when a message is signed a set of attributes are included which 19459191Skrisinclude the signing time and supported symmetric algorithms. With this 19559191Skrisoption they are not included. 19659191Skris 19759191Skris=item B<-binary> 19859191Skris 19959191Skrisnormally the input message is converted to "canonical" format which is 20059191Skriseffectively using CR and LF as end of line: as required by the S/MIME 20159191Skrisspecification. When this option is present no translation occurs. This 20259191Skrisis useful when handling binary data which may not be in MIME format. 20359191Skris 20459191Skris=item B<-nodetach> 20559191Skris 20659191Skriswhen signing a message use opaque signing: this form is more resistant 20759191Skristo translation by mail relays but it cannot be read by mail agents that 20859191Skrisdo not support S/MIME. Without this option cleartext signing with 20959191Skristhe MIME type multipart/signed is used. 21059191Skris 21159191Skris=item B<-certfile file> 21259191Skris 21359191Skrisallows additional certificates to be specified. When signing these will 21459191Skrisbe included with the message. When verifying these will be searched for 21559191Skristhe signers certificates. The certificates should be in PEM format. 21659191Skris 21759191Skris=item B<-signer file> 21859191Skris 219238405Sjkima signing certificate when signing or resigning a message, this option can be 220238405Sjkimused multiple times if more than one signer is required. If a message is being 221238405Sjkimverified then the signers certificates will be written to this file if the 222238405Sjkimverification was successful. 22359191Skris 22459191Skris=item B<-recip file> 22559191Skris 22659191Skristhe recipients certificate when decrypting a message. This certificate 22759191Skrismust match one of the recipients of the message or an error occurs. 22859191Skris 22959191Skris=item B<-inkey file> 23059191Skris 23159191Skristhe private key to use when signing or decrypting. This must match the 23259191Skriscorresponding certificate. If this option is not specified then the 23359191Skrisprivate key must be included in the certificate file specified with 234238405Sjkimthe B<-recip> or B<-signer> file. When signing this option can be used 235238405Sjkimmultiple times to specify successive keys. 23659191Skris 23768651Skris=item B<-passin arg> 23868651Skris 23968651Skristhe private key password source. For more information about the format of B<arg> 24068651Skrissee the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 24168651Skris 24259191Skris=item B<-rand file(s)> 24359191Skris 24459191Skrisa file or files containing random data used to seed the random number 24559191Skrisgenerator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 24659191SkrisMultiple files can be specified separated by a OS-dependent character. 24768651SkrisThe separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for 24859191Skrisall others. 24959191Skris 25059191Skris=item B<cert.pem...> 25159191Skris 25259191Skrisone or more certificates of message recipients: used when encrypting 25359191Skrisa message. 25459191Skris 25559191Skris=item B<-to, -from, -subject> 25659191Skris 25759191Skristhe relevant mail headers. These are included outside the signed 25859191Skrisportion of a message so they may be included manually. If signing 25959191Skristhen many S/MIME mail clients check the signers certificate's email 26059191Skrisaddress matches that specified in the From: address. 26159191Skris 262238405Sjkim=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig> 263238405Sjkim 264238405SjkimSet various options of certificate chain verification. See 265238405SjkimL<B<verify>|verify(1)> manual page for details. 266238405Sjkim 26759191Skris=back 26859191Skris 26959191Skris=head1 NOTES 27059191Skris 27159191SkrisThe MIME message must be sent without any blank lines between the 27259191Skrisheaders and the output. Some mail programs will automatically add 27359191Skrisa blank line. Piping the mail directly to sendmail is one way to 27459191Skrisachieve the correct format. 27559191Skris 27659191SkrisThe supplied message to be signed or encrypted must include the 27768651Skrisnecessary MIME headers or many S/MIME clients wont display it 27859191Skrisproperly (if at all). You can use the B<-text> option to automatically 27959191Skrisadd plain text headers. 28059191Skris 28159191SkrisA "signed and encrypted" message is one where a signed message is 28259191Skristhen encrypted. This can be produced by encrypting an already signed 28359191Skrismessage: see the examples section. 28459191Skris 28559191SkrisThis version of the program only allows one signer per message but it 28659191Skriswill verify multiple signers on received messages. Some S/MIME clients 28759191Skrischoke if a message contains multiple signers. It is possible to sign 28859191Skrismessages "in parallel" by signing an already signed message. 28959191Skris 29059191SkrisThe options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME 29159191Skrisclients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 29259191Skrisencrypted data is used for other purposes. 29359191Skris 294238405SjkimThe B<-resign> option uses an existing message digest when adding a new 295238405Sjkimsigner. This means that attributes must be present in at least one existing 296238405Sjkimsigner using the same message digest or this operation will fail. 297238405Sjkim 298238405SjkimThe B<-stream> and B<-indef> options enable experimental streaming I/O support. 299238405SjkimAs a result the encoding is BER using indefinite length constructed encoding 300238405Sjkimand no longer DER. Streaming is supported for the B<-encrypt> operation and the 301238405SjkimB<-sign> operation if the content is not detached. 302238405Sjkim 303238405SjkimStreaming is always used for the B<-sign> operation with detached data but 304238405Sjkimsince the content is no longer part of the PKCS#7 structure the encoding 305238405Sjkimremains DER. 306238405Sjkim 30759191Skris=head1 EXIT CODES 30859191Skris 30959191Skris=over 4 31059191Skris 31159191Skris=item 0 31259191Skris 31359191Skristhe operation was completely successfully. 31459191Skris 31559191Skris=item 1 31659191Skris 31759191Skrisan error occurred parsing the command options. 31859191Skris 31959191Skris=item 2 32059191Skris 32159191Skrisone of the input files could not be read. 32259191Skris 32359191Skris=item 3 32459191Skris 32559191Skrisan error occurred creating the PKCS#7 file or when reading the MIME 32659191Skrismessage. 32759191Skris 32859191Skris=item 4 32959191Skris 33059191Skrisan error occurred decrypting or verifying the message. 33159191Skris 33259191Skris=item 5 33359191Skris 33459191Skristhe message was verified correctly but an error occurred writing out 33559191Skristhe signers certificates. 33659191Skris 33759191Skris=back 33859191Skris 33959191Skris=head1 EXAMPLES 34059191Skris 34159191SkrisCreate a cleartext signed message: 34259191Skris 34359191Skris openssl smime -sign -in message.txt -text -out mail.msg \ 34459191Skris -signer mycert.pem 34559191Skris 346238405SjkimCreate an opaque signed message: 34759191Skris 34859191Skris openssl smime -sign -in message.txt -text -out mail.msg -nodetach \ 34959191Skris -signer mycert.pem 35059191Skris 35159191SkrisCreate a signed message, include some additional certificates and 35259191Skrisread the private key from another file: 35359191Skris 35459191Skris openssl smime -sign -in in.txt -text -out mail.msg \ 35559191Skris -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem 35659191Skris 357238405SjkimCreate a signed message with two signers: 358238405Sjkim 359238405Sjkim openssl smime -sign -in message.txt -text -out mail.msg \ 360238405Sjkim -signer mycert.pem -signer othercert.pem 361238405Sjkim 36259191SkrisSend a signed message under Unix directly to sendmail, including headers: 36359191Skris 36459191Skris openssl smime -sign -in in.txt -text -signer mycert.pem \ 36559191Skris -from steve@openssl.org -to someone@somewhere \ 36659191Skris -subject "Signed message" | sendmail someone@somewhere 36759191Skris 36859191SkrisVerify a message and extract the signer's certificate if successful: 36959191Skris 37059191Skris openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt 37159191Skris 37259191SkrisSend encrypted mail using triple DES: 37359191Skris 37459191Skris openssl smime -encrypt -in in.txt -from steve@openssl.org \ 37559191Skris -to someone@somewhere -subject "Encrypted message" \ 37659191Skris -des3 user.pem -out mail.msg 37759191Skris 37859191SkrisSign and encrypt mail: 37959191Skris 38059191Skris openssl smime -sign -in ml.txt -signer my.pem -text \ 38168651Skris | openssl smime -encrypt -out mail.msg \ 38259191Skris -from steve@openssl.org -to someone@somewhere \ 38359191Skris -subject "Signed and Encrypted message" -des3 user.pem 38459191Skris 385238405SjkimNote: the encryption command does not include the B<-text> option because the 386238405Sjkimmessage being encrypted already has MIME headers. 38759191Skris 38859191SkrisDecrypt mail: 38959191Skris 39059191Skris openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem 39159191Skris 39268651SkrisThe output from Netscape form signing is a PKCS#7 structure with the 39368651Skrisdetached signature format. You can use this program to verify the 39468651Skrissignature by line wrapping the base64 encoded structure and surrounding 39568651Skrisit with: 39668651Skris 397109998Smarkm -----BEGIN PKCS7----- 398109998Smarkm -----END PKCS7----- 39968651Skris 400215697Ssimonand using the command: 40168651Skris 40268651Skris openssl smime -verify -inform PEM -in signature.pem -content content.txt 40368651Skris 404215697SsimonAlternatively you can base64 decode the signature and use: 40568651Skris 40668651Skris openssl smime -verify -inform DER -in signature.der -content content.txt 40768651Skris 408162911SsimonCreate an encrypted message using 128 bit Camellia: 409162911Ssimon 410162911Ssimon openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem 411162911Ssimon 412238405SjkimAdd a signer to an existing message: 413238405Sjkim 414238405Sjkim openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg 415238405Sjkim 41659191Skris=head1 BUGS 41759191Skris 418238405SjkimThe MIME parser isn't very clever: it seems to handle most messages that I've 419238405Sjkimthrown at it but it may choke on others. 42059191Skris 421238405SjkimThe code currently will only write out the signer's certificate to a file: if 422238405Sjkimthe signer has a separate encryption certificate this must be manually 423238405Sjkimextracted. There should be some heuristic that determines the correct 424238405Sjkimencryption certificate. 42559191Skris 426238405SjkimIdeally a database should be maintained of a certificates for each email 427238405Sjkimaddress. 42859191Skris 42959191SkrisThe code doesn't currently take note of the permitted symmetric encryption 430215697Ssimonalgorithms as supplied in the SMIMECapabilities signed attribute. This means the 43159191Skrisuser has to manually include the correct encryption algorithm. It should store 43259191Skristhe list of permitted ciphers in a database and only use those. 43359191Skris 43459191SkrisNo revocation checking is done on the signer's certificate. 43559191Skris 43659191SkrisThe current code can only handle S/MIME v2 messages, the more complex S/MIME v3 43759191Skrisstructures may cause parsing errors. 43859191Skris 439238405Sjkim=head1 HISTORY 440238405Sjkim 441238405SjkimThe use of multiple B<-signer> options and the B<-resign> command were first 442238405Sjkimadded in OpenSSL 1.0.0 443238405Sjkim 444238405Sjkim 44559191Skris=cut 446