doc/apps/smime.pod

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