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