smime.pod revision 59191
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>] 1359191Skris[B<-verify>] 1459191Skris[B<-pk7out>] 1559191Skris[B<-des>] 1659191Skris[B<-des3>] 1759191Skris[B<-rc2-40>] 1859191Skris[B<-rc2-64>] 1959191Skris[B<-rc2-128>] 2059191Skris[B<-in file>] 2159191Skris[B<-certfile file>] 2259191Skris[B<-signer file>] 2359191Skris[B<-recip file>] 2459191Skris[B<-in file>] 2559191Skris[B<-inkey file>] 2659191Skris[B<-out file>] 2759191Skris[B<-to addr>] 2859191Skris[B<-from ad>] 2959191Skris[B<-subject s>] 3059191Skris[B<-text>] 3159191Skris[B<-rand file(s)>] 3259191Skris[cert.pem]... 3359191Skris 3459191Skris=head1 DESCRIPTION 3559191Skris 3659191SkrisThe B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and 3759191Skrisverify S/MIME messages. 3859191Skris 3959191Skris=head1 COMMAND OPTIONS 4059191Skris 4159191SkrisThere are five operation options that set the type of operation to be performed. 4259191SkrisThe meaning of the other options varies according to the operation type. 4359191Skris 4459191Skris=over 4 4559191Skris 4659191Skris=item B<-encrypt> 4759191Skris 4859191Skrisencrypt mail for the given recipient certificates. Input file is the message 4959191Skristo be encrypted. The output file is the encrypted mail in MIME format. 5059191Skris 5159191Skris=item B<-decrypt> 5259191Skris 5359191Skrisdecrypt mail using the supplied certificate and private key. Expects an 5459191Skrisencrypted mail message in MIME format for the input file. The decrypted mail 5559191Skrisis written to the output file. 5659191Skris 5759191Skris=item B<-sign> 5859191Skris 5959191Skrissign mail using the supplied certificate and private key. Input file is 6059191Skristhe message to be signed. The signed message in MIME format is written 6159191Skristo the output file. 6259191Skris 6359191Skris=item B<-verify> 6459191Skris 6559191Skrisverify signed mail. Expects a signed mail message on input and outputs 6659191Skristhe signed data. Both clear text and opaque signing is supported. 6759191Skris 6859191Skris=item B<-pk7out> 6959191Skris 7059191Skristakes an input message and writes out a PEM encoded PKCS#7 structure. 7159191Skris 7259191Skris=item B<-in filename> 7359191Skris 7459191Skristhe input message to be encrypted or signed or the MIME message to 7559191Skrisbe decrypted or verified. 7659191Skris 7759191Skris=item B<-out filename> 7859191Skris 7959191Skristhe message text that has been decrypted or verified or the output MIME 8059191Skrisformat message that has been signed or verified. 8159191Skris 8259191Skris=item B<-text> 8359191Skris 8459191Skristhis option adds plain text (text/plain) MIME headers to the supplied 8559191Skrismessage if encrypting or signing. If decrypting or verifying it strips 8659191Skrisoff text headers: if the decrypted or verified message is not of MIME 8759191Skristype text/plain then an error occurs. 8859191Skris 8959191Skris=item B<-CAfile file> 9059191Skris 9159191Skrisa file containing trusted CA certificates, only used with B<-verify>. 9259191Skris 9359191Skris=item B<-CApath dir> 9459191Skris 9559191Skrisa directory containing trusted CA certificates, only used with 9659191SkrisB<-verify>. This directory must be a standard certificate directory: that 9759191Skrisis a hash of each subject name (using B<x509 -hash>) should be linked 9859191Skristo each certificate. 9959191Skris 10059191Skris=item B<-des -des3 -rc2-40 -rc2-64 -rc2-128> 10159191Skris 10259191Skristhe encryption algorithm to use. DES (56 bits), triple DES (168 bits) 10359191Skrisor 40, 64 or 128 bit RC2 respectively if not specified 40 bit RC2 is 10459191Skrisused. Only used with B<-encrypt>. 10559191Skris 10659191Skris=item B<-nointern> 10759191Skris 10859191Skriswhen verifying a message normally certificates (if any) included in 10959191Skristhe message are searched for the signing certificate. With this option 11059191Skrisonly the certificates specified in the B<-certfile> option are used. 11159191SkrisThe supplied certificates can still be used as untrusted CAs however. 11259191Skris 11359191Skris=item B<-noverify> 11459191Skris 11559191Skrisdo not verify the signers certificate of a signed message. 11659191Skris 11759191Skris=item B<-nochain> 11859191Skris 11959191Skrisdo not do chain verification of signers certificates: that is don't 12059191Skrisuse the certificates in the signed message as untrusted CAs. 12159191Skris 12259191Skris=item B<-nosigs> 12359191Skris 12459191Skrisdon't try to verify the signatures on the message. 12559191Skris 12659191Skris=item B<-nocerts> 12759191Skris 12859191Skriswhen signing a message the signer's certificate is normally included 12959191Skriswith this option it is excluded. This will reduce the size of the 13059191Skrissigned message but the verifier must have a copy of the signers certificate 13159191Skrisavailable locally (passed using the B<-certfile> option for example). 13259191Skris 13359191Skris=item B<-noattr> 13459191Skris 13559191Skrisnormally when a message is signed a set of attributes are included which 13659191Skrisinclude the signing time and supported symmetric algorithms. With this 13759191Skrisoption they are not included. 13859191Skris 13959191Skris=item B<-binary> 14059191Skris 14159191Skrisnormally the input message is converted to "canonical" format which is 14259191Skriseffectively using CR and LF as end of line: as required by the S/MIME 14359191Skrisspecification. When this option is present no translation occurs. This 14459191Skrisis useful when handling binary data which may not be in MIME format. 14559191Skris 14659191Skris=item B<-nodetach> 14759191Skris 14859191Skriswhen signing a message use opaque signing: this form is more resistant 14959191Skristo translation by mail relays but it cannot be read by mail agents that 15059191Skrisdo not support S/MIME. Without this option cleartext signing with 15159191Skristhe MIME type multipart/signed is used. 15259191Skris 15359191Skris=item B<-certfile file> 15459191Skris 15559191Skrisallows additional certificates to be specified. When signing these will 15659191Skrisbe included with the message. When verifying these will be searched for 15759191Skristhe signers certificates. The certificates should be in PEM format. 15859191Skris 15959191Skris=item B<-signer file> 16059191Skris 16159191Skristhe signers certificate when signing a message. If a message is 16259191Skrisbeing verified then the signers certificates will be written to this 16359191Skrisfile if the verification was successful. 16459191Skris 16559191Skris=item B<-recip file> 16659191Skris 16759191Skristhe recipients certificate when decrypting a message. This certificate 16859191Skrismust match one of the recipients of the message or an error occurs. 16959191Skris 17059191Skris=item B<-inkey file> 17159191Skris 17259191Skristhe private key to use when signing or decrypting. This must match the 17359191Skriscorresponding certificate. If this option is not specified then the 17459191Skrisprivate key must be included in the certificate file specified with 17559191Skristhe B<-recip> or B<-signer> file. 17659191Skris 17759191Skris=item B<-rand file(s)> 17859191Skris 17959191Skrisa file or files containing random data used to seed the random number 18059191Skrisgenerator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 18159191SkrisMultiple files can be specified separated by a OS-dependent character. 18259191SkrisThe separator is B<;> for MS-Windows, B<,> for OpenVSM, and B<:> for 18359191Skrisall others. 18459191Skris 18559191Skris=item B<cert.pem...> 18659191Skris 18759191Skrisone or more certificates of message recipients: used when encrypting 18859191Skrisa message. 18959191Skris 19059191Skris=item B<-to, -from, -subject> 19159191Skris 19259191Skristhe relevant mail headers. These are included outside the signed 19359191Skrisportion of a message so they may be included manually. If signing 19459191Skristhen many S/MIME mail clients check the signers certificate's email 19559191Skrisaddress matches that specified in the From: address. 19659191Skris 19759191Skris=back 19859191Skris 19959191Skris=head1 NOTES 20059191Skris 20159191SkrisThe MIME message must be sent without any blank lines between the 20259191Skrisheaders and the output. Some mail programs will automatically add 20359191Skrisa blank line. Piping the mail directly to sendmail is one way to 20459191Skrisachieve the correct format. 20559191Skris 20659191SkrisThe supplied message to be signed or encrypted must include the 20759191Skrisnecessary MIME headers: or many S/MIME clients wont display it 20859191Skrisproperly (if at all). You can use the B<-text> option to automatically 20959191Skrisadd plain text headers. 21059191Skris 21159191SkrisA "signed and encrypted" message is one where a signed message is 21259191Skristhen encrypted. This can be produced by encrypting an already signed 21359191Skrismessage: see the examples section. 21459191Skris 21559191SkrisThis version of the program only allows one signer per message but it 21659191Skriswill verify multiple signers on received messages. Some S/MIME clients 21759191Skrischoke if a message contains multiple signers. It is possible to sign 21859191Skrismessages "in parallel" by signing an already signed message. 21959191Skris 22059191SkrisThe options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME 22159191Skrisclients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 22259191Skrisencrypted data is used for other purposes. 22359191Skris 22459191Skris=head1 EXIT CODES 22559191Skris 22659191Skris=over 4 22759191Skris 22859191Skris=item 0 22959191Skris 23059191Skristhe operation was completely successfully. 23159191Skris 23259191Skris=item 1 23359191Skris 23459191Skrisan error occurred parsing the command options. 23559191Skris 23659191Skris=item 2 23759191Skris 23859191Skrisone of the input files could not be read. 23959191Skris 24059191Skris=item 3 24159191Skris 24259191Skrisan error occurred creating the PKCS#7 file or when reading the MIME 24359191Skrismessage. 24459191Skris 24559191Skris=item 4 24659191Skris 24759191Skrisan error occurred decrypting or verifying the message. 24859191Skris 24959191Skris=item 5 25059191Skris 25159191Skristhe message was verified correctly but an error occurred writing out 25259191Skristhe signers certificates. 25359191Skris 25459191Skris=back 25559191Skris 25659191Skris=head1 EXAMPLES 25759191Skris 25859191SkrisCreate a cleartext signed message: 25959191Skris 26059191Skris openssl smime -sign -in message.txt -text -out mail.msg \ 26159191Skris -signer mycert.pem 26259191Skris 26359191SkrisCreate and opaque signed message 26459191Skris 26559191Skris openssl smime -sign -in message.txt -text -out mail.msg -nodetach \ 26659191Skris -signer mycert.pem 26759191Skris 26859191SkrisCreate a signed message, include some additional certificates and 26959191Skrisread the private key from another file: 27059191Skris 27159191Skris openssl smime -sign -in in.txt -text -out mail.msg \ 27259191Skris -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem 27359191Skris 27459191SkrisSend a signed message under Unix directly to sendmail, including headers: 27559191Skris 27659191Skris openssl smime -sign -in in.txt -text -signer mycert.pem \ 27759191Skris -from steve@openssl.org -to someone@somewhere \ 27859191Skris -subject "Signed message" | sendmail someone@somewhere 27959191Skris 28059191SkrisVerify a message and extract the signer's certificate if successful: 28159191Skris 28259191Skris openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt 28359191Skris 28459191SkrisSend encrypted mail using triple DES: 28559191Skris 28659191Skris openssl smime -encrypt -in in.txt -from steve@openssl.org \ 28759191Skris -to someone@somewhere -subject "Encrypted message" \ 28859191Skris -des3 user.pem -out mail.msg 28959191Skris 29059191SkrisSign and encrypt mail: 29159191Skris 29259191Skris openssl smime -sign -in ml.txt -signer my.pem -text \ 29359191Skris | openssl -encrypt -out mail.msg \ 29459191Skris -from steve@openssl.org -to someone@somewhere \ 29559191Skris -subject "Signed and Encrypted message" -des3 user.pem 29659191Skris 29759191SkrisNote: the encryption command does not include the B<-text> option because the message 29859191Skrisbeing encrypted already has MIME headers. 29959191Skris 30059191SkrisDecrypt mail: 30159191Skris 30259191Skris openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem 30359191Skris 30459191Skris=head1 BUGS 30559191Skris 30659191SkrisThe MIME parser isn't very clever: it seems to handle most messages that I've thrown 30759191Skrisat it but it may choke on others. 30859191Skris 30959191SkrisThe code currently will only write out the signer's certificate to a file: if the 31059191Skrissigner has a separate encryption certificate this must be manually extracted. There 31159191Skrisshould be some heuristic that determines the correct encryption certificate. 31259191Skris 31359191SkrisIdeally a database should be maintained of a certificates for each email address. 31459191Skris 31559191SkrisThe code doesn't currently take note of the permitted symmetric encryption 31659191Skrisalgorithms as supplied in the SMIMECapabilities signed attribute. this means the 31759191Skrisuser has to manually include the correct encryption algorithm. It should store 31859191Skristhe list of permitted ciphers in a database and only use those. 31959191Skris 32059191SkrisNo revocation checking is done on the signer's certificate. 32159191Skris 32259191SkrisThe current code can only handle S/MIME v2 messages, the more complex S/MIME v3 32359191Skrisstructures may cause parsing errors. 32459191Skris 32559191Skris=cut 326