doc/man1/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<-help>]
  11 [B<-encrypt>]
  12 [B<-decrypt>]
  13 [B<-sign>]
  14 [B<-resign>]
  15 [B<-verify>]
  16 [B<-pk7out>]
  17 [B<-binary>]
  18 [B<-crlfeol>]
  19 [B<-[cipher]>]
  20 [B<-in file>]
  21 [B<-CAfile file>]
  22 [B<-CApath dir>]
  23 [B<-no-CAfile>]
  24 [B<-no-CApath>]
  25 [B<-attime timestamp>]
  26 [B<-check_ss_sig>]
  27 [B<-crl_check>]
  28 [B<-crl_check_all>]
  29 [B<-explicit_policy>]
  30 [B<-extended_crl>]
  31 [B<-ignore_critical>]
  32 [B<-inhibit_any>]
  33 [B<-inhibit_map>]
  34 [B<-partial_chain>]
  35 [B<-policy arg>]
  36 [B<-policy_check>]
  37 [B<-policy_print>]
  38 [B<-purpose purpose>]
  39 [B<-suiteB_128>]
  40 [B<-suiteB_128_only>]
  41 [B<-suiteB_192>]
  42 [B<-trusted_first>]
  43 [B<-no_alt_chains>]
  44 [B<-use_deltas>]
  45 [B<-auth_level num>]
  46 [B<-verify_depth num>]
  47 [B<-verify_email email>]
  48 [B<-verify_hostname hostname>]
  49 [B<-verify_ip ip>]
  50 [B<-verify_name name>]
  51 [B<-x509_strict>]
  52 [B<-certfile file>]
  53 [B<-signer file>]
  54 [B<-recip  file>]
  55 [B<-inform SMIME|PEM|DER>]
  56 [B<-passin arg>]
  57 [B<-inkey file_or_id>]
  58 [B<-out file>]
  59 [B<-outform SMIME|PEM|DER>]
  60 [B<-content file>]
  61 [B<-to addr>]
  62 [B<-from ad>]
  63 [B<-subject s>]
  64 [B<-text>]
  65 [B<-indef>]
  66 [B<-noindef>]
  67 [B<-stream>]
  68 [B<-rand file...>]
  69 [B<-writerand file>]
  70 [B<-md digest>]
  71 [cert.pem]...
  72
  73 =head1 DESCRIPTION
  74
  75 The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and
  76 verify S/MIME messages.
  77
  78 =head1 OPTIONS
  79
  80 There are six operation options that set the type of operation to be performed.
  81 The meaning of the other options varies according to the operation type.
  82
  83 =over 4
  84
  85 =item B<-help>
  86
  87 Print out a usage message.
  88
  89 =item B<-encrypt>
  90
  91 Encrypt mail for the given recipient certificates. Input file is the message
  92 to be encrypted. The output file is the encrypted mail in MIME format.
  93
  94 Note that no revocation check is done for the recipient cert, so if that
  95 key has been compromised, others may be able to decrypt the text.
  96
  97 =item B<-decrypt>
  98
  99 Decrypt mail using the supplied certificate and private key. Expects an
 100 encrypted mail message in MIME format for the input file. The decrypted mail
 101 is written to the output file.
 102
 103 =item B<-sign>
 104
 105 Sign mail using the supplied certificate and private key. Input file is
 106 the message to be signed. The signed message in MIME format is written
 107 to the output file.
 108
 109 =item B<-verify>
 110
 111 Verify signed mail. Expects a signed mail message on input and outputs
 112 the signed data. Both clear text and opaque signing is supported.
 113
 114 =item B<-pk7out>
 115
 116 Takes an input message and writes out a PEM encoded PKCS#7 structure.
 117
 118 =item B<-resign>
 119
 120 Resign a message: take an existing message and one or more new signers.
 121
 122 =item B<-in filename>
 123
 124 The input message to be encrypted or signed or the MIME message to
 125 be decrypted or verified.
 126
 127 =item B<-inform SMIME|PEM|DER>
 128
 129 This specifies the input format for the PKCS#7 structure. The default
 130 is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER>
 131 format change this to expect PEM and DER format PKCS#7 structures
 132 instead. This currently only affects the input format of the PKCS#7
 133 structure, if no PKCS#7 structure is being input (for example with
 134 B<-encrypt> or B<-sign>) this option has no effect.
 135
 136 =item B<-out filename>
 137
 138 The message text that has been decrypted or verified or the output MIME
 139 format message that has been signed or verified.
 140
 141 =item B<-outform SMIME|PEM|DER>
 142
 143 This specifies the output format for the PKCS#7 structure. The default
 144 is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER>
 145 format change this to write PEM and DER format PKCS#7 structures
 146 instead. This currently only affects the output format of the PKCS#7
 147 structure, if no PKCS#7 structure is being output (for example with
 148 B<-verify> or B<-decrypt>) this option has no effect.
 149
 150 =item B<-stream -indef -noindef>
 151
 152 The B<-stream> and B<-indef> options are equivalent and enable streaming I/O
 153 for encoding operations. This permits single pass processing of data without
 154 the need to hold the entire contents in memory, potentially supporting very
 155 large files. Streaming is automatically set for S/MIME signing with detached
 156 data if the output format is B<SMIME> it is currently off by default for all
 157 other operations.
 158
 159 =item B<-noindef>
 160
 161 Disable streaming I/O where it would produce and indefinite length constructed
 162 encoding. This option currently has no effect. In future streaming will be
 163 enabled by default on all relevant operations and this option will disable it.
 164
 165 =item B<-content filename>
 166
 167 This specifies a file containing the detached content, this is only
 168 useful with the B<-verify> command. This is only usable if the PKCS#7
 169 structure is using the detached signature form where the content is
 170 not included. This option will override any content if the input format
 171 is S/MIME and it uses the multipart/signed MIME content type.
 172
 173 =item B<-text>
 174
 175 This option adds plain text (text/plain) MIME headers to the supplied
 176 message if encrypting or signing. If decrypting or verifying it strips
 177 off text headers: if the decrypted or verified message is not of MIME
 178 type text/plain then an error occurs.
 179
 180 =item B<-CAfile file>
 181
 182 A file containing trusted CA certificates, only used with B<-verify>.
 183
 184 =item B<-CApath dir>
 185
 186 A directory containing trusted CA certificates, only used with
 187 B<-verify>. This directory must be a standard certificate directory: that
 188 is a hash of each subject name (using B<x509 -hash>) should be linked
 189 to each certificate.
 190
 191 =item B<-no-CAfile>
 192
 193 Do not load the trusted CA certificates from the default file location.
 194
 195 =item B<-no-CApath>
 196
 197 Do not load the trusted CA certificates from the default directory location.
 198
 199 =item B<-md digest>
 200
 201 Digest algorithm to use when signing or resigning. If not present then the
 202 default digest algorithm for the signing key will be used (usually SHA1).
 203
 204 =item B<-[cipher]>
 205
 206 The encryption algorithm to use. For example DES  (56 bits) - B<-des>,
 207 triple DES (168 bits) - B<-des3>,
 208 EVP_get_cipherbyname() function) can also be used preceded by a dash, for
 209 example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for list of ciphers
 210 supported by your version of OpenSSL.
 211
 212 If not specified triple DES is used. Only used with B<-encrypt>.
 213
 214 =item B<-nointern>
 215
 216 When verifying a message normally certificates (if any) included in
 217 the message are searched for the signing certificate. With this option
 218 only the certificates specified in the B<-certfile> option are used.
 219 The supplied certificates can still be used as untrusted CAs however.
 220
 221 =item B<-noverify>
 222
 223 Do not verify the signers certificate of a signed message.
 224
 225 =item B<-nochain>
 226
 227 Do not do chain verification of signers certificates: that is don't
 228 use the certificates in the signed message as untrusted CAs.
 229
 230 =item B<-nosigs>
 231
 232 Don't try to verify the signatures on the message.
 233
 234 =item B<-nocerts>
 235
 236 When signing a message the signer's certificate is normally included
 237 with this option it is excluded. This will reduce the size of the
 238 signed message but the verifier must have a copy of the signers certificate
 239 available locally (passed using the B<-certfile> option for example).
 240
 241 =item B<-noattr>
 242
 243 Normally when a message is signed a set of attributes are included which
 244 include the signing time and supported symmetric algorithms. With this
 245 option they are not included.
 246
 247 =item B<-binary>
 248
 249 Normally the input message is converted to "canonical" format which is
 250 effectively using CR and LF as end of line: as required by the S/MIME
 251 specification. When this option is present no translation occurs. This
 252 is useful when handling binary data which may not be in MIME format.
 253
 254 =item B<-crlfeol>
 255
 256 Normally the output file uses a single B<LF> as end of line. When this
 257 option is present B<CRLF> is used instead.
 258
 259 =item B<-nodetach>
 260
 261 When signing a message use opaque signing: this form is more resistant
 262 to translation by mail relays but it cannot be read by mail agents that
 263 do not support S/MIME.  Without this option cleartext signing with
 264 the MIME type multipart/signed is used.
 265
 266 =item B<-certfile file>
 267
 268 Allows additional certificates to be specified. When signing these will
 269 be included with the message. When verifying these will be searched for
 270 the signers certificates. The certificates should be in PEM format.
 271
 272 =item B<-signer file>
 273
 274 A signing certificate when signing or resigning a message, this option can be
 275 used multiple times if more than one signer is required. If a message is being
 276 verified then the signers certificates will be written to this file if the
 277 verification was successful.
 278
 279 =item B<-recip file>
 280
 281 The recipients certificate when decrypting a message. This certificate
 282 must match one of the recipients of the message or an error occurs.
 283
 284 =item B<-inkey file_or_id>
 285
 286 The private key to use when signing or decrypting. This must match the
 287 corresponding certificate. If this option is not specified then the
 288 private key must be included in the certificate file specified with
 289 the B<-recip> or B<-signer> file. When signing this option can be used
 290 multiple times to specify successive keys.
 291 If no engine is used, the argument is taken as a file; if an engine is
 292 specified, the argument is given to the engine as a key identifier.
 293
 294 =item B<-passin arg>
 295
 296 The private key password source. For more information about the format of B<arg>
 297 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
 298
 299 =item B<-rand file...>
 300
 301 A file or files containing random data used to seed the random number
 302 generator.
 303 Multiple files can be specified separated by an OS-dependent character.
 304 The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
 305 all others.
 306
 307 =item [B<-writerand file>]
 308
 309 Writes random data to the specified I<file> upon exit.
 310 This can be used with a subsequent B<-rand> flag.
 311
 312 =item B<cert.pem...>
 313
 314 One or more certificates of message recipients: used when encrypting
 315 a message.
 316
 317 =item B<-to, -from, -subject>
 318
 319 The relevant mail headers. These are included outside the signed
 320 portion of a message so they may be included manually. If signing
 321 then many S/MIME mail clients check the signers certificate's email
 322 address matches that specified in the From: address.
 323
 324 =item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
 325 B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
 326 B<-inhibit_map>, B<-no_alt_chains>, B<-partial_chain>, B<-policy>,
 327 B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
 328 B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
 329 B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
 330 B<-verify_ip>, B<-verify_name>, B<-x509_strict>
 331
 332 Set various options of certificate chain verification. See
 333 L<verify(1)> manual page for details.
 334
 335 =back
 336
 337 =head1 NOTES
 338
 339 The MIME message must be sent without any blank lines between the
 340 headers and the output. Some mail programs will automatically add
 341 a blank line. Piping the mail directly to sendmail is one way to
 342 achieve the correct format.
 343
 344 The supplied message to be signed or encrypted must include the
 345 necessary MIME headers or many S/MIME clients won't display it
 346 properly (if at all). You can use the B<-text> option to automatically
 347 add plain text headers.
 348
 349 A "signed and encrypted" message is one where a signed message is
 350 then encrypted. This can be produced by encrypting an already signed
 351 message: see the examples section.
 352
 353 This version of the program only allows one signer per message but it
 354 will verify multiple signers on received messages. Some S/MIME clients
 355 choke if a message contains multiple signers. It is possible to sign
 356 messages "in parallel" by signing an already signed message.
 357
 358 The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
 359 clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7
 360 encrypted data is used for other purposes.
 361
 362 The B<-resign> option uses an existing message digest when adding a new
 363 signer. This means that attributes must be present in at least one existing
 364 signer using the same message digest or this operation will fail.
 365
 366 The B<-stream> and B<-indef> options enable streaming I/O support.
 367 As a result the encoding is BER using indefinite length constructed encoding
 368 and no longer DER. Streaming is supported for the B<-encrypt> operation and the
 369 B<-sign> operation if the content is not detached.
 370
 371 Streaming is always used for the B<-sign> operation with detached data but
 372 since the content is no longer part of the PKCS#7 structure the encoding
 373 remains DER.
 374
 375 =head1 EXIT CODES
 376
 377 =over 4
 378
 379 =item Z<>0
 380
 381 The operation was completely successfully.
 382
 383 =item Z<>1
 384
 385 An error occurred parsing the command options.
 386
 387 =item Z<>2
 388
 389 One of the input files could not be read.
 390
 391 =item Z<>3
 392
 393 An error occurred creating the PKCS#7 file or when reading the MIME
 394 message.
 395
 396 =item Z<>4
 397
 398 An error occurred decrypting or verifying the message.
 399
 400 =item Z<>5
 401
 402 The message was verified correctly but an error occurred writing out
 403 the signers certificates.
 404
 405 =back
 406
 407 =head1 EXAMPLES
 408
 409 Create a cleartext signed message:
 410
 411  openssl smime -sign -in message.txt -text -out mail.msg \
 412         -signer mycert.pem
 413
 414 Create an opaque signed message:
 415
 416  openssl smime -sign -in message.txt -text -out mail.msg -nodetach \
 417         -signer mycert.pem
 418
 419 Create a signed message, include some additional certificates and
 420 read the private key from another file:
 421
 422  openssl smime -sign -in in.txt -text -out mail.msg \
 423         -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
 424
 425 Create a signed message with two signers:
 426
 427  openssl smime -sign -in message.txt -text -out mail.msg \
 428         -signer mycert.pem -signer othercert.pem
 429
 430 Send a signed message under Unix directly to sendmail, including headers:
 431
 432  openssl smime -sign -in in.txt -text -signer mycert.pem \
 433         -from steve@openssl.org -to someone@somewhere \
 434         -subject "Signed message" | sendmail someone@somewhere
 435
 436 Verify a message and extract the signer's certificate if successful:
 437
 438  openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt
 439
 440 Send encrypted mail using triple DES:
 441
 442  openssl smime -encrypt -in in.txt -from steve@openssl.org \
 443         -to someone@somewhere -subject "Encrypted message" \
 444         -des3 user.pem -out mail.msg
 445
 446 Sign and encrypt mail:
 447
 448  openssl smime -sign -in ml.txt -signer my.pem -text \
 449         | openssl smime -encrypt -out mail.msg \
 450         -from steve@openssl.org -to someone@somewhere \
 451         -subject "Signed and Encrypted message" -des3 user.pem
 452
 453 Note: the encryption command does not include the B<-text> option because the
 454 message being encrypted already has MIME headers.
 455
 456 Decrypt mail:
 457
 458  openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
 459
 460 The output from Netscape form signing is a PKCS#7 structure with the
 461 detached signature format. You can use this program to verify the
 462 signature by line wrapping the base64 encoded structure and surrounding
 463 it with:
 464
 465  -----BEGIN PKCS7-----
 466  -----END PKCS7-----
 467
 468 and using the command:
 469
 470  openssl smime -verify -inform PEM -in signature.pem -content content.txt
 471
 472 Alternatively you can base64 decode the signature and use:
 473
 474  openssl smime -verify -inform DER -in signature.der -content content.txt
 475
 476 Create an encrypted message using 128 bit Camellia:
 477
 478  openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
 479
 480 Add a signer to an existing message:
 481
 482  openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg
 483
 484 =head1 BUGS
 485
 486 The MIME parser isn't very clever: it seems to handle most messages that I've
 487 thrown at it but it may choke on others.
 488
 489 The code currently will only write out the signer's certificate to a file: if
 490 the signer has a separate encryption certificate this must be manually
 491 extracted. There should be some heuristic that determines the correct
 492 encryption certificate.
 493
 494 Ideally a database should be maintained of a certificates for each email
 495 address.
 496
 497 The code doesn't currently take note of the permitted symmetric encryption
 498 algorithms as supplied in the SMIMECapabilities signed attribute. This means the
 499 user has to manually include the correct encryption algorithm. It should store
 500 the list of permitted ciphers in a database and only use those.
 501
 502 No revocation checking is done on the signer's certificate.
 503
 504 The current code can only handle S/MIME v2 messages, the more complex S/MIME v3
 505 structures may cause parsing errors.
 506
 507 =head1 HISTORY
 508
 509 The use of multiple B<-signer> options and the B<-resign> command were first
 510 added in OpenSSL 1.0.0
 511
 512 The -no_alt_chains options was first added to OpenSSL 1.1.0.
 513
 514 =head1 COPYRIGHT
 515
 516 Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 517
 518 Licensed under the OpenSSL license (the "License").  You may not use
 519 this file except in compliance with the License.  You can obtain a copy
 520 in the file LICENSE in the source distribution or at
 521 L<https://www.openssl.org/source/license.html>.
 522
 523 =cut