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