smime.pod revision 162911
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>] 20127128Snectar[B<-aes128>] 21127128Snectar[B<-aes192>] 22127128Snectar[B<-aes256>] 23162911Ssimon[B<-camellia128>] 24162911Ssimon[B<-camellia192>] 25162911Ssimon[B<-camellia256>] 2659191Skris[B<-in file>] 2759191Skris[B<-certfile file>] 2859191Skris[B<-signer file>] 2959191Skris[B<-recip file>] 3068651Skris[B<-inform SMIME|PEM|DER>] 3168651Skris[B<-passin arg>] 3259191Skris[B<-inkey file>] 3359191Skris[B<-out file>] 3468651Skris[B<-outform SMIME|PEM|DER>] 3568651Skris[B<-content file>] 3659191Skris[B<-to addr>] 3759191Skris[B<-from ad>] 3859191Skris[B<-subject s>] 3959191Skris[B<-text>] 4059191Skris[B<-rand file(s)>] 4159191Skris[cert.pem]... 4259191Skris 4359191Skris=head1 DESCRIPTION 4459191Skris 4559191SkrisThe B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and 4659191Skrisverify S/MIME messages. 4759191Skris 4859191Skris=head1 COMMAND OPTIONS 4959191Skris 5059191SkrisThere are five operation options that set the type of operation to be performed. 5159191SkrisThe meaning of the other options varies according to the operation type. 5259191Skris 5359191Skris=over 4 5459191Skris 5559191Skris=item B<-encrypt> 5659191Skris 5759191Skrisencrypt mail for the given recipient certificates. Input file is the message 5859191Skristo be encrypted. The output file is the encrypted mail in MIME format. 5959191Skris 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 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 10968651Skris=item B<-content filename> 11068651Skris 11168651SkrisThis specifies a file containing the detached content, this is only 11268651Skrisuseful with the B<-verify> command. This is only usable if the PKCS#7 11368651Skrisstructure is using the detached signature form where the content is 11468651Skrisnot included. This option will override any content if the input format 11568651Skrisis S/MIME and it uses the multipart/signed MIME content type. 11668651Skris 11759191Skris=item B<-text> 11859191Skris 11959191Skristhis option adds plain text (text/plain) MIME headers to the supplied 12059191Skrismessage if encrypting or signing. If decrypting or verifying it strips 12159191Skrisoff text headers: if the decrypted or verified message is not of MIME 12259191Skristype text/plain then an error occurs. 12359191Skris 12459191Skris=item B<-CAfile file> 12559191Skris 12659191Skrisa file containing trusted CA certificates, only used with B<-verify>. 12759191Skris 12859191Skris=item B<-CApath dir> 12959191Skris 13059191Skrisa directory containing trusted CA certificates, only used with 13159191SkrisB<-verify>. This directory must be a standard certificate directory: that 13259191Skrisis a hash of each subject name (using B<x509 -hash>) should be linked 13359191Skristo each certificate. 13459191Skris 135162911Ssimon=item B<-des -des3 -rc2-40 -rc2-64 -rc2-128 -aes128 -aes192 -aes256 -camellia128 -camellia192 -camellia256> 13659191Skris 137127128Snectarthe encryption algorithm to use. DES (56 bits), triple DES (168 bits), 138162911Ssimon40, 64 or 128 bit RC2, 128, 192 or 256 bit AES, or 128, 192 or 256 bit Camellia respectively. If not 139127128Snectarspecified 40 bit RC2 is used. Only used with B<-encrypt>. 14059191Skris 14159191Skris=item B<-nointern> 14259191Skris 14359191Skriswhen verifying a message normally certificates (if any) included in 14459191Skristhe message are searched for the signing certificate. With this option 14559191Skrisonly the certificates specified in the B<-certfile> option are used. 14659191SkrisThe supplied certificates can still be used as untrusted CAs however. 14759191Skris 14859191Skris=item B<-noverify> 14959191Skris 15059191Skrisdo not verify the signers certificate of a signed message. 15159191Skris 15259191Skris=item B<-nochain> 15359191Skris 15459191Skrisdo not do chain verification of signers certificates: that is don't 15559191Skrisuse the certificates in the signed message as untrusted CAs. 15659191Skris 15759191Skris=item B<-nosigs> 15859191Skris 15959191Skrisdon't try to verify the signatures on the message. 16059191Skris 16159191Skris=item B<-nocerts> 16259191Skris 16359191Skriswhen signing a message the signer's certificate is normally included 16459191Skriswith this option it is excluded. This will reduce the size of the 16559191Skrissigned message but the verifier must have a copy of the signers certificate 16659191Skrisavailable locally (passed using the B<-certfile> option for example). 16759191Skris 16859191Skris=item B<-noattr> 16959191Skris 17059191Skrisnormally when a message is signed a set of attributes are included which 17159191Skrisinclude the signing time and supported symmetric algorithms. With this 17259191Skrisoption they are not included. 17359191Skris 17459191Skris=item B<-binary> 17559191Skris 17659191Skrisnormally the input message is converted to "canonical" format which is 17759191Skriseffectively using CR and LF as end of line: as required by the S/MIME 17859191Skrisspecification. When this option is present no translation occurs. This 17959191Skrisis useful when handling binary data which may not be in MIME format. 18059191Skris 18159191Skris=item B<-nodetach> 18259191Skris 18359191Skriswhen signing a message use opaque signing: this form is more resistant 18459191Skristo translation by mail relays but it cannot be read by mail agents that 18559191Skrisdo not support S/MIME. Without this option cleartext signing with 18659191Skristhe MIME type multipart/signed is used. 18759191Skris 18859191Skris=item B<-certfile file> 18959191Skris 19059191Skrisallows additional certificates to be specified. When signing these will 19159191Skrisbe included with the message. When verifying these will be searched for 19259191Skristhe signers certificates. The certificates should be in PEM format. 19359191Skris 19459191Skris=item B<-signer file> 19559191Skris 19659191Skristhe signers certificate when signing a message. If a message is 19759191Skrisbeing verified then the signers certificates will be written to this 19859191Skrisfile if the verification was successful. 19959191Skris 20059191Skris=item B<-recip file> 20159191Skris 20259191Skristhe recipients certificate when decrypting a message. This certificate 20359191Skrismust match one of the recipients of the message or an error occurs. 20459191Skris 20559191Skris=item B<-inkey file> 20659191Skris 20759191Skristhe private key to use when signing or decrypting. This must match the 20859191Skriscorresponding certificate. If this option is not specified then the 20959191Skrisprivate key must be included in the certificate file specified with 21059191Skristhe B<-recip> or B<-signer> file. 21159191Skris 21268651Skris=item B<-passin arg> 21368651Skris 21468651Skristhe private key password source. For more information about the format of B<arg> 21568651Skrissee the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 21668651Skris 21759191Skris=item B<-rand file(s)> 21859191Skris 21959191Skrisa file or files containing random data used to seed the random number 22059191Skrisgenerator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 22159191SkrisMultiple files can be specified separated by a OS-dependent character. 22268651SkrisThe separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for 22359191Skrisall others. 22459191Skris 22559191Skris=item B<cert.pem...> 22659191Skris 22759191Skrisone or more certificates of message recipients: used when encrypting 22859191Skrisa message. 22959191Skris 23059191Skris=item B<-to, -from, -subject> 23159191Skris 23259191Skristhe relevant mail headers. These are included outside the signed 23359191Skrisportion of a message so they may be included manually. If signing 23459191Skristhen many S/MIME mail clients check the signers certificate's email 23559191Skrisaddress matches that specified in the From: address. 23659191Skris 23759191Skris=back 23859191Skris 23959191Skris=head1 NOTES 24059191Skris 24159191SkrisThe MIME message must be sent without any blank lines between the 24259191Skrisheaders and the output. Some mail programs will automatically add 24359191Skrisa blank line. Piping the mail directly to sendmail is one way to 24459191Skrisachieve the correct format. 24559191Skris 24659191SkrisThe supplied message to be signed or encrypted must include the 24768651Skrisnecessary MIME headers or many S/MIME clients wont display it 24859191Skrisproperly (if at all). You can use the B<-text> option to automatically 24959191Skrisadd plain text headers. 25059191Skris 25159191SkrisA "signed and encrypted" message is one where a signed message is 25259191Skristhen encrypted. This can be produced by encrypting an already signed 25359191Skrismessage: see the examples section. 25459191Skris 25559191SkrisThis version of the program only allows one signer per message but it 25659191Skriswill verify multiple signers on received messages. Some S/MIME clients 25759191Skrischoke if a message contains multiple signers. It is possible to sign 25859191Skrismessages "in parallel" by signing an already signed message. 25959191Skris 26059191SkrisThe options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME 26159191Skrisclients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 26259191Skrisencrypted data is used for other purposes. 26359191Skris 26459191Skris=head1 EXIT CODES 26559191Skris 26659191Skris=over 4 26759191Skris 26859191Skris=item 0 26959191Skris 27059191Skristhe operation was completely successfully. 27159191Skris 27259191Skris=item 1 27359191Skris 27459191Skrisan error occurred parsing the command options. 27559191Skris 27659191Skris=item 2 27759191Skris 27859191Skrisone of the input files could not be read. 27959191Skris 28059191Skris=item 3 28159191Skris 28259191Skrisan error occurred creating the PKCS#7 file or when reading the MIME 28359191Skrismessage. 28459191Skris 28559191Skris=item 4 28659191Skris 28759191Skrisan error occurred decrypting or verifying the message. 28859191Skris 28959191Skris=item 5 29059191Skris 29159191Skristhe message was verified correctly but an error occurred writing out 29259191Skristhe signers certificates. 29359191Skris 29459191Skris=back 29559191Skris 29659191Skris=head1 EXAMPLES 29759191Skris 29859191SkrisCreate a cleartext signed message: 29959191Skris 30059191Skris openssl smime -sign -in message.txt -text -out mail.msg \ 30159191Skris -signer mycert.pem 30259191Skris 30359191SkrisCreate and opaque signed message 30459191Skris 30559191Skris openssl smime -sign -in message.txt -text -out mail.msg -nodetach \ 30659191Skris -signer mycert.pem 30759191Skris 30859191SkrisCreate a signed message, include some additional certificates and 30959191Skrisread the private key from another file: 31059191Skris 31159191Skris openssl smime -sign -in in.txt -text -out mail.msg \ 31259191Skris -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem 31359191Skris 31459191SkrisSend a signed message under Unix directly to sendmail, including headers: 31559191Skris 31659191Skris openssl smime -sign -in in.txt -text -signer mycert.pem \ 31759191Skris -from steve@openssl.org -to someone@somewhere \ 31859191Skris -subject "Signed message" | sendmail someone@somewhere 31959191Skris 32059191SkrisVerify a message and extract the signer's certificate if successful: 32159191Skris 32259191Skris openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt 32359191Skris 32459191SkrisSend encrypted mail using triple DES: 32559191Skris 32659191Skris openssl smime -encrypt -in in.txt -from steve@openssl.org \ 32759191Skris -to someone@somewhere -subject "Encrypted message" \ 32859191Skris -des3 user.pem -out mail.msg 32959191Skris 33059191SkrisSign and encrypt mail: 33159191Skris 33259191Skris openssl smime -sign -in ml.txt -signer my.pem -text \ 33368651Skris | openssl smime -encrypt -out mail.msg \ 33459191Skris -from steve@openssl.org -to someone@somewhere \ 33559191Skris -subject "Signed and Encrypted message" -des3 user.pem 33659191Skris 33759191SkrisNote: the encryption command does not include the B<-text> option because the message 33859191Skrisbeing encrypted already has MIME headers. 33959191Skris 34059191SkrisDecrypt mail: 34159191Skris 34259191Skris openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem 34359191Skris 34468651SkrisThe output from Netscape form signing is a PKCS#7 structure with the 34568651Skrisdetached signature format. You can use this program to verify the 34668651Skrissignature by line wrapping the base64 encoded structure and surrounding 34768651Skrisit with: 34868651Skris 349109998Smarkm -----BEGIN PKCS7----- 350109998Smarkm -----END PKCS7----- 35168651Skris 35268651Skrisand using the command, 35368651Skris 35468651Skris openssl smime -verify -inform PEM -in signature.pem -content content.txt 35568651Skris 35668651Skrisalternatively you can base64 decode the signature and use 35768651Skris 35868651Skris openssl smime -verify -inform DER -in signature.der -content content.txt 35968651Skris 360162911SsimonCreate an encrypted message using 128 bit Camellia: 361162911Ssimon 362162911Ssimon openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem 363162911Ssimon 36459191Skris=head1 BUGS 36559191Skris 36659191SkrisThe MIME parser isn't very clever: it seems to handle most messages that I've thrown 36759191Skrisat it but it may choke on others. 36859191Skris 36959191SkrisThe code currently will only write out the signer's certificate to a file: if the 37059191Skrissigner has a separate encryption certificate this must be manually extracted. There 37159191Skrisshould be some heuristic that determines the correct encryption certificate. 37259191Skris 37359191SkrisIdeally a database should be maintained of a certificates for each email address. 37459191Skris 37559191SkrisThe code doesn't currently take note of the permitted symmetric encryption 37659191Skrisalgorithms as supplied in the SMIMECapabilities signed attribute. this means the 37759191Skrisuser has to manually include the correct encryption algorithm. It should store 37859191Skristhe list of permitted ciphers in a database and only use those. 37959191Skris 38059191SkrisNo revocation checking is done on the signer's certificate. 38159191Skris 38259191SkrisThe current code can only handle S/MIME v2 messages, the more complex S/MIME v3 38359191Skrisstructures may cause parsing errors. 38459191Skris 38559191Skris=cut 386