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