smime.pod revision 68651
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>] 2568651Skris[B<-inform SMIME|PEM|DER>] 2668651Skris[B<-passin arg>] 2759191Skris[B<-inkey file>] 2859191Skris[B<-out file>] 2968651Skris[B<-outform SMIME|PEM|DER>] 3068651Skris[B<-content file>] 3159191Skris[B<-to addr>] 3259191Skris[B<-from ad>] 3359191Skris[B<-subject s>] 3459191Skris[B<-text>] 3559191Skris[B<-rand file(s)>] 3659191Skris[cert.pem]... 3759191Skris 3859191Skris=head1 DESCRIPTION 3959191Skris 4059191SkrisThe B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and 4159191Skrisverify S/MIME messages. 4259191Skris 4359191Skris=head1 COMMAND OPTIONS 4459191Skris 4559191SkrisThere are five operation options that set the type of operation to be performed. 4659191SkrisThe meaning of the other options varies according to the operation type. 4759191Skris 4859191Skris=over 4 4959191Skris 5059191Skris=item B<-encrypt> 5159191Skris 5259191Skrisencrypt mail for the given recipient certificates. Input file is the message 5359191Skristo be encrypted. The output file is the encrypted mail in MIME format. 5459191Skris 5559191Skris=item B<-decrypt> 5659191Skris 5759191Skrisdecrypt mail using the supplied certificate and private key. Expects an 5859191Skrisencrypted mail message in MIME format for the input file. The decrypted mail 5959191Skrisis written to the output file. 6059191Skris 6159191Skris=item B<-sign> 6259191Skris 6359191Skrissign mail using the supplied certificate and private key. Input file is 6459191Skristhe message to be signed. The signed message in MIME format is written 6559191Skristo the output file. 6659191Skris 6759191Skris=item B<-verify> 6859191Skris 6959191Skrisverify signed mail. Expects a signed mail message on input and outputs 7059191Skristhe signed data. Both clear text and opaque signing is supported. 7159191Skris 7259191Skris=item B<-pk7out> 7359191Skris 7459191Skristakes an input message and writes out a PEM encoded PKCS#7 structure. 7559191Skris 7659191Skris=item B<-in filename> 7759191Skris 7859191Skristhe input message to be encrypted or signed or the MIME message to 7959191Skrisbe decrypted or verified. 8059191Skris 8168651Skris=item B<-inform SMIME|PEM|DER> 8268651Skris 8368651Skristhis specifies the input format for the PKCS#7 structure. The default 8468651Skrisis B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> 8568651Skrisformat change this to expect PEM and DER format PKCS#7 structures 8668651Skrisinstead. This currently only affects the input format of the PKCS#7 8768651Skrisstructure, if no PKCS#7 structure is being input (for example with 8868651SkrisB<-encrypt> or B<-sign>) this option has no effect. 8968651Skris 9059191Skris=item B<-out filename> 9159191Skris 9259191Skristhe message text that has been decrypted or verified or the output MIME 9359191Skrisformat message that has been signed or verified. 9459191Skris 9568651Skris=item B<-outform SMIME|PEM|DER> 9668651Skris 9768651Skristhis specifies the output format for the PKCS#7 structure. The default 9868651Skrisis B<SMIME> which write an S/MIME format message. B<PEM> and B<DER> 9968651Skrisformat change this to write PEM and DER format PKCS#7 structures 10068651Skrisinstead. This currently only affects the output format of the PKCS#7 10168651Skrisstructure, if no PKCS#7 structure is being output (for example with 10268651SkrisB<-verify> or B<-decrypt>) this option has no effect. 10368651Skris 10468651Skris=item B<-content filename> 10568651Skris 10668651SkrisThis specifies a file containing the detached content, this is only 10768651Skrisuseful with the B<-verify> command. This is only usable if the PKCS#7 10868651Skrisstructure is using the detached signature form where the content is 10968651Skrisnot included. This option will override any content if the input format 11068651Skrisis S/MIME and it uses the multipart/signed MIME content type. 11168651Skris 11259191Skris=item B<-text> 11359191Skris 11459191Skristhis option adds plain text (text/plain) MIME headers to the supplied 11559191Skrismessage if encrypting or signing. If decrypting or verifying it strips 11659191Skrisoff text headers: if the decrypted or verified message is not of MIME 11759191Skristype text/plain then an error occurs. 11859191Skris 11959191Skris=item B<-CAfile file> 12059191Skris 12159191Skrisa file containing trusted CA certificates, only used with B<-verify>. 12259191Skris 12359191Skris=item B<-CApath dir> 12459191Skris 12559191Skrisa directory containing trusted CA certificates, only used with 12659191SkrisB<-verify>. This directory must be a standard certificate directory: that 12759191Skrisis a hash of each subject name (using B<x509 -hash>) should be linked 12859191Skristo each certificate. 12959191Skris 13059191Skris=item B<-des -des3 -rc2-40 -rc2-64 -rc2-128> 13159191Skris 13259191Skristhe encryption algorithm to use. DES (56 bits), triple DES (168 bits) 13359191Skrisor 40, 64 or 128 bit RC2 respectively if not specified 40 bit RC2 is 13459191Skrisused. Only used with B<-encrypt>. 13559191Skris 13659191Skris=item B<-nointern> 13759191Skris 13859191Skriswhen verifying a message normally certificates (if any) included in 13959191Skristhe message are searched for the signing certificate. With this option 14059191Skrisonly the certificates specified in the B<-certfile> option are used. 14159191SkrisThe supplied certificates can still be used as untrusted CAs however. 14259191Skris 14359191Skris=item B<-noverify> 14459191Skris 14559191Skrisdo not verify the signers certificate of a signed message. 14659191Skris 14759191Skris=item B<-nochain> 14859191Skris 14959191Skrisdo not do chain verification of signers certificates: that is don't 15059191Skrisuse the certificates in the signed message as untrusted CAs. 15159191Skris 15259191Skris=item B<-nosigs> 15359191Skris 15459191Skrisdon't try to verify the signatures on the message. 15559191Skris 15659191Skris=item B<-nocerts> 15759191Skris 15859191Skriswhen signing a message the signer's certificate is normally included 15959191Skriswith this option it is excluded. This will reduce the size of the 16059191Skrissigned message but the verifier must have a copy of the signers certificate 16159191Skrisavailable locally (passed using the B<-certfile> option for example). 16259191Skris 16359191Skris=item B<-noattr> 16459191Skris 16559191Skrisnormally when a message is signed a set of attributes are included which 16659191Skrisinclude the signing time and supported symmetric algorithms. With this 16759191Skrisoption they are not included. 16859191Skris 16959191Skris=item B<-binary> 17059191Skris 17159191Skrisnormally the input message is converted to "canonical" format which is 17259191Skriseffectively using CR and LF as end of line: as required by the S/MIME 17359191Skrisspecification. When this option is present no translation occurs. This 17459191Skrisis useful when handling binary data which may not be in MIME format. 17559191Skris 17659191Skris=item B<-nodetach> 17759191Skris 17859191Skriswhen signing a message use opaque signing: this form is more resistant 17959191Skristo translation by mail relays but it cannot be read by mail agents that 18059191Skrisdo not support S/MIME. Without this option cleartext signing with 18159191Skristhe MIME type multipart/signed is used. 18259191Skris 18359191Skris=item B<-certfile file> 18459191Skris 18559191Skrisallows additional certificates to be specified. When signing these will 18659191Skrisbe included with the message. When verifying these will be searched for 18759191Skristhe signers certificates. The certificates should be in PEM format. 18859191Skris 18959191Skris=item B<-signer file> 19059191Skris 19159191Skristhe signers certificate when signing a message. If a message is 19259191Skrisbeing verified then the signers certificates will be written to this 19359191Skrisfile if the verification was successful. 19459191Skris 19559191Skris=item B<-recip file> 19659191Skris 19759191Skristhe recipients certificate when decrypting a message. This certificate 19859191Skrismust match one of the recipients of the message or an error occurs. 19959191Skris 20059191Skris=item B<-inkey file> 20159191Skris 20259191Skristhe private key to use when signing or decrypting. This must match the 20359191Skriscorresponding certificate. If this option is not specified then the 20459191Skrisprivate key must be included in the certificate file specified with 20559191Skristhe B<-recip> or B<-signer> file. 20659191Skris 20768651Skris=item B<-passin arg> 20868651Skris 20968651Skristhe private key password source. For more information about the format of B<arg> 21068651Skrissee the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 21168651Skris 21259191Skris=item B<-rand file(s)> 21359191Skris 21459191Skrisa file or files containing random data used to seed the random number 21559191Skrisgenerator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 21659191SkrisMultiple files can be specified separated by a OS-dependent character. 21768651SkrisThe separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for 21859191Skrisall others. 21959191Skris 22059191Skris=item B<cert.pem...> 22159191Skris 22259191Skrisone or more certificates of message recipients: used when encrypting 22359191Skrisa message. 22459191Skris 22559191Skris=item B<-to, -from, -subject> 22659191Skris 22759191Skristhe relevant mail headers. These are included outside the signed 22859191Skrisportion of a message so they may be included manually. If signing 22959191Skristhen many S/MIME mail clients check the signers certificate's email 23059191Skrisaddress matches that specified in the From: address. 23159191Skris 23259191Skris=back 23359191Skris 23459191Skris=head1 NOTES 23559191Skris 23659191SkrisThe MIME message must be sent without any blank lines between the 23759191Skrisheaders and the output. Some mail programs will automatically add 23859191Skrisa blank line. Piping the mail directly to sendmail is one way to 23959191Skrisachieve the correct format. 24059191Skris 24159191SkrisThe supplied message to be signed or encrypted must include the 24268651Skrisnecessary MIME headers or many S/MIME clients wont display it 24359191Skrisproperly (if at all). You can use the B<-text> option to automatically 24459191Skrisadd plain text headers. 24559191Skris 24659191SkrisA "signed and encrypted" message is one where a signed message is 24759191Skristhen encrypted. This can be produced by encrypting an already signed 24859191Skrismessage: see the examples section. 24959191Skris 25059191SkrisThis version of the program only allows one signer per message but it 25159191Skriswill verify multiple signers on received messages. Some S/MIME clients 25259191Skrischoke if a message contains multiple signers. It is possible to sign 25359191Skrismessages "in parallel" by signing an already signed message. 25459191Skris 25559191SkrisThe options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME 25659191Skrisclients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 25759191Skrisencrypted data is used for other purposes. 25859191Skris 25959191Skris=head1 EXIT CODES 26059191Skris 26159191Skris=over 4 26259191Skris 26359191Skris=item 0 26459191Skris 26559191Skristhe operation was completely successfully. 26659191Skris 26759191Skris=item 1 26859191Skris 26959191Skrisan error occurred parsing the command options. 27059191Skris 27159191Skris=item 2 27259191Skris 27359191Skrisone of the input files could not be read. 27459191Skris 27559191Skris=item 3 27659191Skris 27759191Skrisan error occurred creating the PKCS#7 file or when reading the MIME 27859191Skrismessage. 27959191Skris 28059191Skris=item 4 28159191Skris 28259191Skrisan error occurred decrypting or verifying the message. 28359191Skris 28459191Skris=item 5 28559191Skris 28659191Skristhe message was verified correctly but an error occurred writing out 28759191Skristhe signers certificates. 28859191Skris 28959191Skris=back 29059191Skris 29159191Skris=head1 EXAMPLES 29259191Skris 29359191SkrisCreate a cleartext signed message: 29459191Skris 29559191Skris openssl smime -sign -in message.txt -text -out mail.msg \ 29659191Skris -signer mycert.pem 29759191Skris 29859191SkrisCreate and opaque signed message 29959191Skris 30059191Skris openssl smime -sign -in message.txt -text -out mail.msg -nodetach \ 30159191Skris -signer mycert.pem 30259191Skris 30359191SkrisCreate a signed message, include some additional certificates and 30459191Skrisread the private key from another file: 30559191Skris 30659191Skris openssl smime -sign -in in.txt -text -out mail.msg \ 30759191Skris -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem 30859191Skris 30959191SkrisSend a signed message under Unix directly to sendmail, including headers: 31059191Skris 31159191Skris openssl smime -sign -in in.txt -text -signer mycert.pem \ 31259191Skris -from steve@openssl.org -to someone@somewhere \ 31359191Skris -subject "Signed message" | sendmail someone@somewhere 31459191Skris 31559191SkrisVerify a message and extract the signer's certificate if successful: 31659191Skris 31759191Skris openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt 31859191Skris 31959191SkrisSend encrypted mail using triple DES: 32059191Skris 32159191Skris openssl smime -encrypt -in in.txt -from steve@openssl.org \ 32259191Skris -to someone@somewhere -subject "Encrypted message" \ 32359191Skris -des3 user.pem -out mail.msg 32459191Skris 32559191SkrisSign and encrypt mail: 32659191Skris 32759191Skris openssl smime -sign -in ml.txt -signer my.pem -text \ 32868651Skris | openssl smime -encrypt -out mail.msg \ 32959191Skris -from steve@openssl.org -to someone@somewhere \ 33059191Skris -subject "Signed and Encrypted message" -des3 user.pem 33159191Skris 33259191SkrisNote: the encryption command does not include the B<-text> option because the message 33359191Skrisbeing encrypted already has MIME headers. 33459191Skris 33559191SkrisDecrypt mail: 33659191Skris 33759191Skris openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem 33859191Skris 33968651SkrisThe output from Netscape form signing is a PKCS#7 structure with the 34068651Skrisdetached signature format. You can use this program to verify the 34168651Skrissignature by line wrapping the base64 encoded structure and surrounding 34268651Skrisit with: 34368651Skris 34468651Skris -----BEGIN PKCS7---- 34568651Skris -----END PKCS7---- 34668651Skris 34768651Skrisand using the command, 34868651Skris 34968651Skris openssl smime -verify -inform PEM -in signature.pem -content content.txt 35068651Skris 35168651Skrisalternatively you can base64 decode the signature and use 35268651Skris 35368651Skris openssl smime -verify -inform DER -in signature.der -content content.txt 35468651Skris 35559191Skris=head1 BUGS 35659191Skris 35759191SkrisThe MIME parser isn't very clever: it seems to handle most messages that I've thrown 35859191Skrisat it but it may choke on others. 35959191Skris 36059191SkrisThe code currently will only write out the signer's certificate to a file: if the 36159191Skrissigner has a separate encryption certificate this must be manually extracted. There 36259191Skrisshould be some heuristic that determines the correct encryption certificate. 36359191Skris 36459191SkrisIdeally a database should be maintained of a certificates for each email address. 36559191Skris 36659191SkrisThe code doesn't currently take note of the permitted symmetric encryption 36759191Skrisalgorithms as supplied in the SMIMECapabilities signed attribute. this means the 36859191Skrisuser has to manually include the correct encryption algorithm. It should store 36959191Skristhe list of permitted ciphers in a database and only use those. 37059191Skris 37159191SkrisNo revocation checking is done on the signer's certificate. 37259191Skris 37359191SkrisThe current code can only handle S/MIME v2 messages, the more complex S/MIME v3 37459191Skrisstructures may cause parsing errors. 37559191Skris 37659191Skris=cut 377