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 56306198SjkimNote that no revocation check is done for the recipient cert, so if that 57306198Sjkimkey has been compromised, others may be able to decrypt the text. 58306198Sjkim 5959191Skris=item B<-decrypt> 6059191Skris 6159191Skrisdecrypt mail using the supplied certificate and private key. Expects an 6259191Skrisencrypted mail message in MIME format for the input file. The decrypted mail 6359191Skrisis written to the output file. 6459191Skris 6559191Skris=item B<-sign> 6659191Skris 6759191Skrissign mail using the supplied certificate and private key. Input file is 6859191Skristhe message to be signed. The signed message in MIME format is written 6959191Skristo the output file. 7059191Skris 7159191Skris=item B<-verify> 7259191Skris 7359191Skrisverify signed mail. Expects a signed mail message on input and outputs 7459191Skristhe signed data. Both clear text and opaque signing is supported. 7559191Skris 7659191Skris=item B<-pk7out> 7759191Skris 7859191Skristakes an input message and writes out a PEM encoded PKCS#7 structure. 7959191Skris 80238405Sjkim=item B<-resign> 81238405Sjkim 82238405Sjkimresign a message: take an existing message and one or more new signers. 83238405Sjkim 8459191Skris=item B<-in filename> 8559191Skris 8659191Skristhe input message to be encrypted or signed or the MIME message to 8759191Skrisbe decrypted or verified. 8859191Skris 8968651Skris=item B<-inform SMIME|PEM|DER> 9068651Skris 9168651Skristhis specifies the input format for the PKCS#7 structure. The default 9268651Skrisis B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> 9368651Skrisformat change this to expect PEM and DER format PKCS#7 structures 9468651Skrisinstead. This currently only affects the input format of the PKCS#7 9568651Skrisstructure, if no PKCS#7 structure is being input (for example with 9668651SkrisB<-encrypt> or B<-sign>) this option has no effect. 9768651Skris 9859191Skris=item B<-out filename> 9959191Skris 10059191Skristhe message text that has been decrypted or verified or the output MIME 10159191Skrisformat message that has been signed or verified. 10259191Skris 10368651Skris=item B<-outform SMIME|PEM|DER> 10468651Skris 10568651Skristhis specifies the output format for the PKCS#7 structure. The default 10668651Skrisis B<SMIME> which write an S/MIME format message. B<PEM> and B<DER> 10768651Skrisformat change this to write PEM and DER format PKCS#7 structures 10868651Skrisinstead. This currently only affects the output format of the PKCS#7 10968651Skrisstructure, if no PKCS#7 structure is being output (for example with 11068651SkrisB<-verify> or B<-decrypt>) this option has no effect. 11168651Skris 112238405Sjkim=item B<-stream -indef -noindef> 113238405Sjkim 114238405Sjkimthe B<-stream> and B<-indef> options are equivalent and enable streaming I/O 115238405Sjkimfor encoding operations. This permits single pass processing of data without 116238405Sjkimthe need to hold the entire contents in memory, potentially supporting very 117238405Sjkimlarge files. Streaming is automatically set for S/MIME signing with detached 118238405Sjkimdata if the output format is B<SMIME> it is currently off by default for all 119238405Sjkimother operations. 120238405Sjkim 121238405Sjkim=item B<-noindef> 122238405Sjkim 123238405Sjkimdisable streaming I/O where it would produce and indefinite length constructed 124238405Sjkimencoding. This option currently has no effect. In future streaming will be 125238405Sjkimenabled by default on all relevant operations and this option will disable it. 126238405Sjkim 12768651Skris=item B<-content filename> 12868651Skris 12968651SkrisThis specifies a file containing the detached content, this is only 13068651Skrisuseful with the B<-verify> command. This is only usable if the PKCS#7 13168651Skrisstructure is using the detached signature form where the content is 13268651Skrisnot included. This option will override any content if the input format 13368651Skrisis S/MIME and it uses the multipart/signed MIME content type. 13468651Skris 13559191Skris=item B<-text> 13659191Skris 13759191Skristhis option adds plain text (text/plain) MIME headers to the supplied 13859191Skrismessage if encrypting or signing. If decrypting or verifying it strips 13959191Skrisoff text headers: if the decrypted or verified message is not of MIME 14059191Skristype text/plain then an error occurs. 14159191Skris 14259191Skris=item B<-CAfile file> 14359191Skris 14459191Skrisa file containing trusted CA certificates, only used with B<-verify>. 14559191Skris 14659191Skris=item B<-CApath dir> 14759191Skris 14859191Skrisa directory containing trusted CA certificates, only used with 14959191SkrisB<-verify>. This directory must be a standard certificate directory: that 15059191Skrisis a hash of each subject name (using B<x509 -hash>) should be linked 15159191Skristo each certificate. 15259191Skris 153238405Sjkim=item B<-md digest> 15459191Skris 155238405Sjkimdigest algorithm to use when signing or resigning. If not present then the 156238405Sjkimdefault digest algorithm for the signing key will be used (usually SHA1). 15759191Skris 158238405Sjkim=item B<-[cipher]> 159238405Sjkim 160238405Sjkimthe encryption algorithm to use. For example DES (56 bits) - B<-des>, 161238405Sjkimtriple DES (168 bits) - B<-des3>, 162238405SjkimEVP_get_cipherbyname() function) can also be used preceded by a dash, for 163238405Sjkimexample B<-aes_128_cbc>. See L<B<enc>|enc(1)> for list of ciphers 164238405Sjkimsupported by your version of OpenSSL. 165238405Sjkim 166267256SjkimIf not specified triple DES is used. Only used with B<-encrypt>. 167238405Sjkim 16859191Skris=item B<-nointern> 16959191Skris 17059191Skriswhen verifying a message normally certificates (if any) included in 17159191Skristhe message are searched for the signing certificate. With this option 17259191Skrisonly the certificates specified in the B<-certfile> option are used. 17359191SkrisThe supplied certificates can still be used as untrusted CAs however. 17459191Skris 17559191Skris=item B<-noverify> 17659191Skris 17759191Skrisdo not verify the signers certificate of a signed message. 17859191Skris 17959191Skris=item B<-nochain> 18059191Skris 18159191Skrisdo not do chain verification of signers certificates: that is don't 18259191Skrisuse the certificates in the signed message as untrusted CAs. 18359191Skris 18459191Skris=item B<-nosigs> 18559191Skris 18659191Skrisdon't try to verify the signatures on the message. 18759191Skris 18859191Skris=item B<-nocerts> 18959191Skris 19059191Skriswhen signing a message the signer's certificate is normally included 19159191Skriswith this option it is excluded. This will reduce the size of the 19259191Skrissigned message but the verifier must have a copy of the signers certificate 19359191Skrisavailable locally (passed using the B<-certfile> option for example). 19459191Skris 19559191Skris=item B<-noattr> 19659191Skris 19759191Skrisnormally when a message is signed a set of attributes are included which 19859191Skrisinclude the signing time and supported symmetric algorithms. With this 19959191Skrisoption they are not included. 20059191Skris 20159191Skris=item B<-binary> 20259191Skris 20359191Skrisnormally the input message is converted to "canonical" format which is 20459191Skriseffectively using CR and LF as end of line: as required by the S/MIME 20559191Skrisspecification. When this option is present no translation occurs. This 20659191Skrisis useful when handling binary data which may not be in MIME format. 20759191Skris 20859191Skris=item B<-nodetach> 20959191Skris 21059191Skriswhen signing a message use opaque signing: this form is more resistant 21159191Skristo translation by mail relays but it cannot be read by mail agents that 21259191Skrisdo not support S/MIME. Without this option cleartext signing with 21359191Skristhe MIME type multipart/signed is used. 21459191Skris 21559191Skris=item B<-certfile file> 21659191Skris 21759191Skrisallows additional certificates to be specified. When signing these will 21859191Skrisbe included with the message. When verifying these will be searched for 21959191Skristhe signers certificates. The certificates should be in PEM format. 22059191Skris 22159191Skris=item B<-signer file> 22259191Skris 223238405Sjkima signing certificate when signing or resigning a message, this option can be 224238405Sjkimused multiple times if more than one signer is required. If a message is being 225238405Sjkimverified then the signers certificates will be written to this file if the 226238405Sjkimverification was successful. 22759191Skris 22859191Skris=item B<-recip file> 22959191Skris 23059191Skristhe recipients certificate when decrypting a message. This certificate 23159191Skrismust match one of the recipients of the message or an error occurs. 23259191Skris 23359191Skris=item B<-inkey file> 23459191Skris 23559191Skristhe private key to use when signing or decrypting. This must match the 23659191Skriscorresponding certificate. If this option is not specified then the 23759191Skrisprivate key must be included in the certificate file specified with 238238405Sjkimthe B<-recip> or B<-signer> file. When signing this option can be used 239238405Sjkimmultiple times to specify successive keys. 24059191Skris 24168651Skris=item B<-passin arg> 24268651Skris 24368651Skristhe private key password source. For more information about the format of B<arg> 24468651Skrissee the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 24568651Skris 24659191Skris=item B<-rand file(s)> 24759191Skris 24859191Skrisa file or files containing random data used to seed the random number 24959191Skrisgenerator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 25059191SkrisMultiple files can be specified separated by a OS-dependent character. 25168651SkrisThe separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for 25259191Skrisall others. 25359191Skris 25459191Skris=item B<cert.pem...> 25559191Skris 25659191Skrisone or more certificates of message recipients: used when encrypting 25759191Skrisa message. 25859191Skris 25959191Skris=item B<-to, -from, -subject> 26059191Skris 26159191Skristhe relevant mail headers. These are included outside the signed 26259191Skrisportion of a message so they may be included manually. If signing 26359191Skristhen many S/MIME mail clients check the signers certificate's email 26459191Skrisaddress matches that specified in the From: address. 26559191Skris 266284283Sjkim=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> 267238405Sjkim 268238405SjkimSet various options of certificate chain verification. See 269238405SjkimL<B<verify>|verify(1)> manual page for details. 270238405Sjkim 27159191Skris=back 27259191Skris 27359191Skris=head1 NOTES 27459191Skris 27559191SkrisThe MIME message must be sent without any blank lines between the 27659191Skrisheaders and the output. Some mail programs will automatically add 27759191Skrisa blank line. Piping the mail directly to sendmail is one way to 27859191Skrisachieve the correct format. 27959191Skris 28059191SkrisThe supplied message to be signed or encrypted must include the 28168651Skrisnecessary MIME headers or many S/MIME clients wont display it 28259191Skrisproperly (if at all). You can use the B<-text> option to automatically 28359191Skrisadd plain text headers. 28459191Skris 28559191SkrisA "signed and encrypted" message is one where a signed message is 28659191Skristhen encrypted. This can be produced by encrypting an already signed 28759191Skrismessage: see the examples section. 28859191Skris 28959191SkrisThis version of the program only allows one signer per message but it 29059191Skriswill verify multiple signers on received messages. Some S/MIME clients 29159191Skrischoke if a message contains multiple signers. It is possible to sign 29259191Skrismessages "in parallel" by signing an already signed message. 29359191Skris 29459191SkrisThe options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME 29559191Skrisclients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 29659191Skrisencrypted data is used for other purposes. 29759191Skris 298238405SjkimThe B<-resign> option uses an existing message digest when adding a new 299238405Sjkimsigner. This means that attributes must be present in at least one existing 300238405Sjkimsigner using the same message digest or this operation will fail. 301238405Sjkim 302238405SjkimThe B<-stream> and B<-indef> options enable experimental streaming I/O support. 303238405SjkimAs a result the encoding is BER using indefinite length constructed encoding 304238405Sjkimand no longer DER. Streaming is supported for the B<-encrypt> operation and the 305238405SjkimB<-sign> operation if the content is not detached. 306238405Sjkim 307238405SjkimStreaming is always used for the B<-sign> operation with detached data but 308238405Sjkimsince the content is no longer part of the PKCS#7 structure the encoding 309238405Sjkimremains DER. 310238405Sjkim 31159191Skris=head1 EXIT CODES 31259191Skris 31359191Skris=over 4 31459191Skris 315261037Sjkim=item Z<>0 31659191Skris 31759191Skristhe operation was completely successfully. 31859191Skris 319261037Sjkim=item Z<>1 32059191Skris 32159191Skrisan error occurred parsing the command options. 32259191Skris 323261037Sjkim=item Z<>2 32459191Skris 32559191Skrisone of the input files could not be read. 32659191Skris 327261037Sjkim=item Z<>3 32859191Skris 32959191Skrisan error occurred creating the PKCS#7 file or when reading the MIME 33059191Skrismessage. 33159191Skris 332261037Sjkim=item Z<>4 33359191Skris 33459191Skrisan error occurred decrypting or verifying the message. 33559191Skris 336261037Sjkim=item Z<>5 33759191Skris 33859191Skristhe message was verified correctly but an error occurred writing out 33959191Skristhe signers certificates. 34059191Skris 34159191Skris=back 34259191Skris 34359191Skris=head1 EXAMPLES 34459191Skris 34559191SkrisCreate a cleartext signed message: 34659191Skris 34759191Skris openssl smime -sign -in message.txt -text -out mail.msg \ 34859191Skris -signer mycert.pem 34959191Skris 350238405SjkimCreate an opaque signed message: 35159191Skris 35259191Skris openssl smime -sign -in message.txt -text -out mail.msg -nodetach \ 35359191Skris -signer mycert.pem 35459191Skris 35559191SkrisCreate a signed message, include some additional certificates and 35659191Skrisread the private key from another file: 35759191Skris 35859191Skris openssl smime -sign -in in.txt -text -out mail.msg \ 35959191Skris -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem 36059191Skris 361238405SjkimCreate a signed message with two signers: 362238405Sjkim 363238405Sjkim openssl smime -sign -in message.txt -text -out mail.msg \ 364238405Sjkim -signer mycert.pem -signer othercert.pem 365238405Sjkim 36659191SkrisSend a signed message under Unix directly to sendmail, including headers: 36759191Skris 36859191Skris openssl smime -sign -in in.txt -text -signer mycert.pem \ 36959191Skris -from steve@openssl.org -to someone@somewhere \ 37059191Skris -subject "Signed message" | sendmail someone@somewhere 37159191Skris 37259191SkrisVerify a message and extract the signer's certificate if successful: 37359191Skris 37459191Skris openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt 37559191Skris 37659191SkrisSend encrypted mail using triple DES: 37759191Skris 37859191Skris openssl smime -encrypt -in in.txt -from steve@openssl.org \ 37959191Skris -to someone@somewhere -subject "Encrypted message" \ 38059191Skris -des3 user.pem -out mail.msg 38159191Skris 38259191SkrisSign and encrypt mail: 38359191Skris 38459191Skris openssl smime -sign -in ml.txt -signer my.pem -text \ 38568651Skris | openssl smime -encrypt -out mail.msg \ 38659191Skris -from steve@openssl.org -to someone@somewhere \ 38759191Skris -subject "Signed and Encrypted message" -des3 user.pem 38859191Skris 389238405SjkimNote: the encryption command does not include the B<-text> option because the 390238405Sjkimmessage being encrypted already has MIME headers. 39159191Skris 39259191SkrisDecrypt mail: 39359191Skris 39459191Skris openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem 39559191Skris 39668651SkrisThe output from Netscape form signing is a PKCS#7 structure with the 39768651Skrisdetached signature format. You can use this program to verify the 39868651Skrissignature by line wrapping the base64 encoded structure and surrounding 39968651Skrisit with: 40068651Skris 401109998Smarkm -----BEGIN PKCS7----- 402109998Smarkm -----END PKCS7----- 40368651Skris 404215697Ssimonand using the command: 40568651Skris 40668651Skris openssl smime -verify -inform PEM -in signature.pem -content content.txt 40768651Skris 408215697SsimonAlternatively you can base64 decode the signature and use: 40968651Skris 41068651Skris openssl smime -verify -inform DER -in signature.der -content content.txt 41168651Skris 412162911SsimonCreate an encrypted message using 128 bit Camellia: 413162911Ssimon 414162911Ssimon openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem 415162911Ssimon 416238405SjkimAdd a signer to an existing message: 417238405Sjkim 418238405Sjkim openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg 419238405Sjkim 42059191Skris=head1 BUGS 42159191Skris 422238405SjkimThe MIME parser isn't very clever: it seems to handle most messages that I've 423238405Sjkimthrown at it but it may choke on others. 42459191Skris 425238405SjkimThe code currently will only write out the signer's certificate to a file: if 426238405Sjkimthe signer has a separate encryption certificate this must be manually 427238405Sjkimextracted. There should be some heuristic that determines the correct 428238405Sjkimencryption certificate. 42959191Skris 430238405SjkimIdeally a database should be maintained of a certificates for each email 431238405Sjkimaddress. 43259191Skris 43359191SkrisThe code doesn't currently take note of the permitted symmetric encryption 434215697Ssimonalgorithms as supplied in the SMIMECapabilities signed attribute. This means the 43559191Skrisuser has to manually include the correct encryption algorithm. It should store 43659191Skristhe list of permitted ciphers in a database and only use those. 43759191Skris 43859191SkrisNo revocation checking is done on the signer's certificate. 43959191Skris 44059191SkrisThe current code can only handle S/MIME v2 messages, the more complex S/MIME v3 44159191Skrisstructures may cause parsing errors. 44259191Skris 443238405Sjkim=head1 HISTORY 444238405Sjkim 445238405SjkimThe use of multiple B<-signer> options and the B<-resign> command were first 446238405Sjkimadded in OpenSSL 1.0.0 447238405Sjkim 448290207SjkimThe -no_alt_chains options was first added to OpenSSL 1.0.2b. 449238405Sjkim 45059191Skris=cut 451