smime.pod revision 59191
1=pod 2 3=head1 NAME 4 5smime - S/MIME utility 6 7=head1 SYNOPSIS 8 9B<openssl> B<smime> 10[B<-encrypt>] 11[B<-decrypt>] 12[B<-sign>] 13[B<-verify>] 14[B<-pk7out>] 15[B<-des>] 16[B<-des3>] 17[B<-rc2-40>] 18[B<-rc2-64>] 19[B<-rc2-128>] 20[B<-in file>] 21[B<-certfile file>] 22[B<-signer file>] 23[B<-recip file>] 24[B<-in file>] 25[B<-inkey file>] 26[B<-out file>] 27[B<-to addr>] 28[B<-from ad>] 29[B<-subject s>] 30[B<-text>] 31[B<-rand file(s)>] 32[cert.pem]... 33 34=head1 DESCRIPTION 35 36The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and 37verify S/MIME messages. 38 39=head1 COMMAND OPTIONS 40 41There are five operation options that set the type of operation to be performed. 42The meaning of the other options varies according to the operation type. 43 44=over 4 45 46=item B<-encrypt> 47 48encrypt mail for the given recipient certificates. Input file is the message 49to be encrypted. The output file is the encrypted mail in MIME format. 50 51=item B<-decrypt> 52 53decrypt mail using the supplied certificate and private key. Expects an 54encrypted mail message in MIME format for the input file. The decrypted mail 55is written to the output file. 56 57=item B<-sign> 58 59sign mail using the supplied certificate and private key. Input file is 60the message to be signed. The signed message in MIME format is written 61to the output file. 62 63=item B<-verify> 64 65verify signed mail. Expects a signed mail message on input and outputs 66the signed data. Both clear text and opaque signing is supported. 67 68=item B<-pk7out> 69 70takes an input message and writes out a PEM encoded PKCS#7 structure. 71 72=item B<-in filename> 73 74the input message to be encrypted or signed or the MIME message to 75be decrypted or verified. 76 77=item B<-out filename> 78 79the message text that has been decrypted or verified or the output MIME 80format message that has been signed or verified. 81 82=item B<-text> 83 84this option adds plain text (text/plain) MIME headers to the supplied 85message if encrypting or signing. If decrypting or verifying it strips 86off text headers: if the decrypted or verified message is not of MIME 87type text/plain then an error occurs. 88 89=item B<-CAfile file> 90 91a file containing trusted CA certificates, only used with B<-verify>. 92 93=item B<-CApath dir> 94 95a directory containing trusted CA certificates, only used with 96B<-verify>. This directory must be a standard certificate directory: that 97is a hash of each subject name (using B<x509 -hash>) should be linked 98to each certificate. 99 100=item B<-des -des3 -rc2-40 -rc2-64 -rc2-128> 101 102the encryption algorithm to use. DES (56 bits), triple DES (168 bits) 103or 40, 64 or 128 bit RC2 respectively if not specified 40 bit RC2 is 104used. Only used with B<-encrypt>. 105 106=item B<-nointern> 107 108when verifying a message normally certificates (if any) included in 109the message are searched for the signing certificate. With this option 110only the certificates specified in the B<-certfile> option are used. 111The supplied certificates can still be used as untrusted CAs however. 112 113=item B<-noverify> 114 115do not verify the signers certificate of a signed message. 116 117=item B<-nochain> 118 119do not do chain verification of signers certificates: that is don't 120use the certificates in the signed message as untrusted CAs. 121 122=item B<-nosigs> 123 124don't try to verify the signatures on the message. 125 126=item B<-nocerts> 127 128when signing a message the signer's certificate is normally included 129with this option it is excluded. This will reduce the size of the 130signed message but the verifier must have a copy of the signers certificate 131available locally (passed using the B<-certfile> option for example). 132 133=item B<-noattr> 134 135normally when a message is signed a set of attributes are included which 136include the signing time and supported symmetric algorithms. With this 137option they are not included. 138 139=item B<-binary> 140 141normally the input message is converted to "canonical" format which is 142effectively using CR and LF as end of line: as required by the S/MIME 143specification. When this option is present no translation occurs. This 144is useful when handling binary data which may not be in MIME format. 145 146=item B<-nodetach> 147 148when signing a message use opaque signing: this form is more resistant 149to translation by mail relays but it cannot be read by mail agents that 150do not support S/MIME. Without this option cleartext signing with 151the MIME type multipart/signed is used. 152 153=item B<-certfile file> 154 155allows additional certificates to be specified. When signing these will 156be included with the message. When verifying these will be searched for 157the signers certificates. The certificates should be in PEM format. 158 159=item B<-signer file> 160 161the signers certificate when signing a message. If a message is 162being verified then the signers certificates will be written to this 163file if the verification was successful. 164 165=item B<-recip file> 166 167the recipients certificate when decrypting a message. This certificate 168must match one of the recipients of the message or an error occurs. 169 170=item B<-inkey file> 171 172the private key to use when signing or decrypting. This must match the 173corresponding certificate. If this option is not specified then the 174private key must be included in the certificate file specified with 175the B<-recip> or B<-signer> file. 176 177=item B<-rand file(s)> 178 179a file or files containing random data used to seed the random number 180generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 181Multiple files can be specified separated by a OS-dependent character. 182The separator is B<;> for MS-Windows, B<,> for OpenVSM, and B<:> for 183all others. 184 185=item B<cert.pem...> 186 187one or more certificates of message recipients: used when encrypting 188a message. 189 190=item B<-to, -from, -subject> 191 192the relevant mail headers. These are included outside the signed 193portion of a message so they may be included manually. If signing 194then many S/MIME mail clients check the signers certificate's email 195address matches that specified in the From: address. 196 197=back 198 199=head1 NOTES 200 201The MIME message must be sent without any blank lines between the 202headers and the output. Some mail programs will automatically add 203a blank line. Piping the mail directly to sendmail is one way to 204achieve the correct format. 205 206The supplied message to be signed or encrypted must include the 207necessary MIME headers: or many S/MIME clients wont display it 208properly (if at all). You can use the B<-text> option to automatically 209add plain text headers. 210 211A "signed and encrypted" message is one where a signed message is 212then encrypted. This can be produced by encrypting an already signed 213message: see the examples section. 214 215This version of the program only allows one signer per message but it 216will verify multiple signers on received messages. Some S/MIME clients 217choke if a message contains multiple signers. It is possible to sign 218messages "in parallel" by signing an already signed message. 219 220The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME 221clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 222encrypted data is used for other purposes. 223 224=head1 EXIT CODES 225 226=over 4 227 228=item 0 229 230the operation was completely successfully. 231 232=item 1 233 234an error occurred parsing the command options. 235 236=item 2 237 238one of the input files could not be read. 239 240=item 3 241 242an error occurred creating the PKCS#7 file or when reading the MIME 243message. 244 245=item 4 246 247an error occurred decrypting or verifying the message. 248 249=item 5 250 251the message was verified correctly but an error occurred writing out 252the signers certificates. 253 254=back 255 256=head1 EXAMPLES 257 258Create a cleartext signed message: 259 260 openssl smime -sign -in message.txt -text -out mail.msg \ 261 -signer mycert.pem 262 263Create and opaque signed message 264 265 openssl smime -sign -in message.txt -text -out mail.msg -nodetach \ 266 -signer mycert.pem 267 268Create a signed message, include some additional certificates and 269read the private key from another file: 270 271 openssl smime -sign -in in.txt -text -out mail.msg \ 272 -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem 273 274Send a signed message under Unix directly to sendmail, including headers: 275 276 openssl smime -sign -in in.txt -text -signer mycert.pem \ 277 -from steve@openssl.org -to someone@somewhere \ 278 -subject "Signed message" | sendmail someone@somewhere 279 280Verify a message and extract the signer's certificate if successful: 281 282 openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt 283 284Send encrypted mail using triple DES: 285 286 openssl smime -encrypt -in in.txt -from steve@openssl.org \ 287 -to someone@somewhere -subject "Encrypted message" \ 288 -des3 user.pem -out mail.msg 289 290Sign and encrypt mail: 291 292 openssl smime -sign -in ml.txt -signer my.pem -text \ 293 | openssl -encrypt -out mail.msg \ 294 -from steve@openssl.org -to someone@somewhere \ 295 -subject "Signed and Encrypted message" -des3 user.pem 296 297Note: the encryption command does not include the B<-text> option because the message 298being encrypted already has MIME headers. 299 300Decrypt mail: 301 302 openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem 303 304=head1 BUGS 305 306The MIME parser isn't very clever: it seems to handle most messages that I've thrown 307at it but it may choke on others. 308 309The code currently will only write out the signer's certificate to a file: if the 310signer has a separate encryption certificate this must be manually extracted. There 311should be some heuristic that determines the correct encryption certificate. 312 313Ideally a database should be maintained of a certificates for each email address. 314 315The code doesn't currently take note of the permitted symmetric encryption 316algorithms as supplied in the SMIMECapabilities signed attribute. this means the 317user has to manually include the correct encryption algorithm. It should store 318the list of permitted ciphers in a database and only use those. 319 320No revocation checking is done on the signer's certificate. 321 322The current code can only handle S/MIME v2 messages, the more complex S/MIME v3 323structures may cause parsing errors. 324 325=cut 326