smime.pod 15.7 KB
Newer Older
1 2 3 4 5 6 7 8 9
=pod

=head1 NAME

smime - S/MIME utility

=head1 SYNOPSIS

B<openssl> B<smime>
10
[B<-help>]
11 12 13
[B<-encrypt>]
[B<-decrypt>]
[B<-sign>]
14
[B<-resign>]
15 16
[B<-verify>]
[B<-pk7out>]
D
Dr. Stephen Henson 已提交
17
[B<-[cipher]>]
18
[B<-in file>]
19 20
[B<-CAfile file>]
[B<-CApath dir>]
21 22
[B<-no-CAfile>]
[B<-no-CApath>]
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
40
[B<-trusted_first>]
41
[B<-no_alt_chains>]
42
[B<-use_deltas>]
43
[B<-auth_level num>]
44 45 46 47 48 49
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
50 51 52
[B<-certfile file>]
[B<-signer file>]
[B<-recip  file>]
D
 
Dr. Stephen Henson 已提交
53
[B<-inform SMIME|PEM|DER>]
54
[B<-passin arg>]
55 56
[B<-inkey file>]
[B<-out file>]
D
 
Dr. Stephen Henson 已提交
57 58
[B<-outform SMIME|PEM|DER>]
[B<-content file>]
59 60 61 62
[B<-to addr>]
[B<-from ad>]
[B<-subject s>]
[B<-text>]
D
Dr. Stephen Henson 已提交
63 64 65
[B<-indef>]
[B<-noindef>]
[B<-stream>]
66
[B<-rand file(s)>]
67
[B<-md digest>]
68 69 70 71 72 73 74 75 76
[cert.pem]...

=head1 DESCRIPTION

The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and
verify S/MIME messages.

=head1 COMMAND OPTIONS

D
Dr. Stephen Henson 已提交
77
There are six operation options that set the type of operation to be performed.
78 79 80 81
The meaning of the other options varies according to the operation type.

=over 4

82 83 84 85
=item B<-help>

Print out a usage message.

86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111
=item B<-encrypt>

encrypt mail for the given recipient certificates. Input file is the message
to be encrypted. The output file is the encrypted mail in MIME format.

=item B<-decrypt>

decrypt mail using the supplied certificate and private key. Expects an
encrypted mail message in MIME format for the input file. The decrypted mail
is written to the output file.

=item B<-sign>

sign mail using the supplied certificate and private key. Input file is
the message to be signed. The signed message in MIME format is written
to the output file.

=item B<-verify>

verify signed mail. Expects a signed mail message on input and outputs
the signed data. Both clear text and opaque signing is supported.

=item B<-pk7out>

takes an input message and writes out a PEM encoded PKCS#7 structure.

112 113 114 115
=item B<-resign>

resign a message: take an existing message and one or more new signers.

116 117 118 119 120
=item B<-in filename>

the input message to be encrypted or signed or the MIME message to
be decrypted or verified.

D
 
Dr. Stephen Henson 已提交
121 122 123 124 125 126 127 128 129
=item B<-inform SMIME|PEM|DER>

this specifies the input format for the PKCS#7 structure. The default
is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER>
format change this to expect PEM and DER format PKCS#7 structures
instead. This currently only affects the input format of the PKCS#7
structure, if no PKCS#7 structure is being input (for example with
B<-encrypt> or B<-sign>) this option has no effect.

130 131 132 133 134
=item B<-out filename>

the message text that has been decrypted or verified or the output MIME
format message that has been signed or verified.

D
 
Dr. Stephen Henson 已提交
135 136 137 138 139 140 141 142 143
=item B<-outform SMIME|PEM|DER>

this specifies the output format for the PKCS#7 structure. The default
is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER>
format change this to write PEM and DER format PKCS#7 structures
instead. This currently only affects the output format of the PKCS#7
structure, if no PKCS#7 structure is being output (for example with
B<-verify> or B<-decrypt>) this option has no effect.

D
Dr. Stephen Henson 已提交
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
=item B<-stream -indef -noindef>

the B<-stream> and B<-indef> options are equivalent and enable streaming I/O
for encoding operations. This permits single pass processing of data without
the need to hold the entire contents in memory, potentially supporting very
large files. Streaming is automatically set for S/MIME signing with detached
data if the output format is B<SMIME> it is currently off by default for all
other operations.

=item B<-noindef>

disable streaming I/O where it would produce and indefinite length constructed
encoding. This option currently has no effect. In future streaming will be
enabled by default on all relevant operations and this option will disable it.

D
 
Dr. Stephen Henson 已提交
159 160 161 162 163 164 165 166
=item B<-content filename>

This specifies a file containing the detached content, this is only
useful with the B<-verify> command. This is only usable if the PKCS#7
structure is using the detached signature form where the content is
not included. This option will override any content if the input format
is S/MIME and it uses the multipart/signed MIME content type.

167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
=item B<-text>

this option adds plain text (text/plain) MIME headers to the supplied
message if encrypting or signing. If decrypting or verifying it strips
off text headers: if the decrypted or verified message is not of MIME 
type text/plain then an error occurs.

=item B<-CAfile file>

a file containing trusted CA certificates, only used with B<-verify>.

=item B<-CApath dir>

a directory containing trusted CA certificates, only used with
B<-verify>. This directory must be a standard certificate directory: that
is a hash of each subject name (using B<x509 -hash>) should be linked
to each certificate.

185 186 187 188 189 190 191 192
=item B<-no-CAfile>

Do not load the trusted CA certificates from the default file location

=item B<-no-CApath>

Do not load the trusted CA certificates from the default directory location

193 194 195 196 197
=item B<-md digest>

digest algorithm to use when signing or resigning. If not present then the
default digest algorithm for the signing key will be used (usually SHA1).

D
Dr. Stephen Henson 已提交
198
=item B<-[cipher]>
199

D
Dr. Stephen Henson 已提交
200 201
the encryption algorithm to use. For example DES  (56 bits) - B<-des>,
triple DES (168 bits) - B<-des3>,
202
EVP_get_cipherbyname() function) can also be used preceded by a dash, for 
V
Viktor Dukhovni 已提交
203
example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for list of ciphers
D
Dr. Stephen Henson 已提交
204
supported by your version of OpenSSL.
205

206
If not specified triple DES is used. Only used with B<-encrypt>.
207 208 209 210 211 212 213 214 215 216 217 218 219 220

=item B<-nointern>

when verifying a message normally certificates (if any) included in
the message are searched for the signing certificate. With this option
only the certificates specified in the B<-certfile> option are used.
The supplied certificates can still be used as untrusted CAs however.

=item B<-noverify>

do not verify the signers certificate of a signed message.

=item B<-nochain>

221
do not do chain verification of signers certificates: that is don't
222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243
use the certificates in the signed message as untrusted CAs.

=item B<-nosigs>

don't try to verify the signatures on the message.

=item B<-nocerts>

when signing a message the signer's certificate is normally included
with this option it is excluded. This will reduce the size of the
signed message but the verifier must have a copy of the signers certificate
available locally (passed using the B<-certfile> option for example).

=item B<-noattr>

normally when a message is signed a set of attributes are included which
include the signing time and supported symmetric algorithms. With this
option they are not included.

=item B<-binary>

normally the input message is converted to "canonical" format which is
244 245 246
effectively using CR and LF as end of line: as required by the S/MIME
specification. When this option is present no translation occurs. This
is useful when handling binary data which may not be in MIME format.
247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262

=item B<-nodetach>

when signing a message use opaque signing: this form is more resistant
to translation by mail relays but it cannot be read by mail agents that
do not support S/MIME.  Without this option cleartext signing with
the MIME type multipart/signed is used.

=item B<-certfile file>

allows additional certificates to be specified. When signing these will
be included with the message. When verifying these will be searched for
the signers certificates. The certificates should be in PEM format.

=item B<-signer file>

263 264 265 266
a signing certificate when signing or resigning a message, this option can be
used multiple times if more than one signer is required. If a message is being
verified then the signers certificates will be written to this file if the
verification was successful.
267 268 269 270 271 272 273 274 275 276 277

=item B<-recip file>

the recipients certificate when decrypting a message. This certificate
must match one of the recipients of the message or an error occurs.

=item B<-inkey file>

the private key to use when signing or decrypting. This must match the
corresponding certificate. If this option is not specified then the
private key must be included in the certificate file specified with
278 279
the B<-recip> or B<-signer> file. When signing this option can be used
multiple times to specify successive keys.
280

281 282 283
=item B<-passin arg>

the private key password source. For more information about the format of B<arg>
R
Rich Salz 已提交
284
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
285

286 287 288
=item B<-rand file(s)>

a file or files containing random data used to seed the random number
R
Rich Salz 已提交
289
generator, or an EGD socket (see L<RAND_egd(3)>).
A
Alex Gaynor 已提交
290
Multiple files can be specified separated by an OS-dependent character.
R
Richard Levitte 已提交
291
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
U
Ulf Möller 已提交
292
all others.
293

294 295 296 297 298 299 300 301 302 303 304 305
=item B<cert.pem...>

one or more certificates of message recipients: used when encrypting
a message. 

=item B<-to, -from, -subject>

the relevant mail headers. These are included outside the signed
portion of a message so they may be included manually. If signing
then many S/MIME mail clients check the signers certificate's email
address matches that specified in the From: address.

306
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
307 308
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-partial_chain>, B<-policy>,
309
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
310
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
311 312
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
D
Dr. Stephen Henson 已提交
313 314

Set various options of certificate chain verification. See
R
Rich Salz 已提交
315
L<verify(1)> manual page for details.
D
Dr. Stephen Henson 已提交
316

317 318 319 320 321 322 323 324 325
=back

=head1 NOTES

The MIME message must be sent without any blank lines between the
headers and the output. Some mail programs will automatically add
a blank line. Piping the mail directly to sendmail is one way to
achieve the correct format.

326
The supplied message to be signed or encrypted must include the
D
 
Dr. Stephen Henson 已提交
327
necessary MIME headers or many S/MIME clients wont display it
328 329 330
properly (if at all). You can use the B<-text> option to automatically
add plain text headers.

331 332
A "signed and encrypted" message is one where a signed message is
then encrypted. This can be produced by encrypting an already signed
333
message: see the examples section.
334 335 336

This version of the program only allows one signer per message but it
will verify multiple signers on received messages. Some S/MIME clients
337
choke if a message contains multiple signers. It is possible to sign
338 339
messages "in parallel" by signing an already signed message.

340 341 342 343
The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7
encrypted data is used for other purposes.

344 345 346 347
The B<-resign> option uses an existing message digest when adding a new
signer. This means that attributes must be present in at least one existing
signer using the same message digest or this operation will fail.

348
The B<-stream> and B<-indef> options enable streaming I/O support.
D
Dr. Stephen Henson 已提交
349 350 351 352 353 354 355 356
As a result the encoding is BER using indefinite length constructed encoding
and no longer DER. Streaming is supported for the B<-encrypt> operation and the
B<-sign> operation if the content is not detached.

Streaming is always used for the B<-sign> operation with detached data but
since the content is no longer part of the PKCS#7 structure the encoding
remains DER.

357 358 359 360
=head1 EXIT CODES

=over 4

L
Lubomir Rintel 已提交
361
=item Z<>0
362

363
the operation was completely successfully.
364

L
Lubomir Rintel 已提交
365
=item Z<>1
366 367 368

an error occurred parsing the command options.

L
Lubomir Rintel 已提交
369
=item Z<>2
370 371 372

one of the input files could not be read.

L
Lubomir Rintel 已提交
373
=item Z<>3
374 375 376 377

an error occurred creating the PKCS#7 file or when reading the MIME
message.

L
Lubomir Rintel 已提交
378
=item Z<>4
379 380 381

an error occurred decrypting or verifying the message.

L
Lubomir Rintel 已提交
382
=item Z<>5
383

384
the message was verified correctly but an error occurred writing out
385 386 387 388 389 390
the signers certificates.

=back

=head1 EXAMPLES

391 392
Create a cleartext signed message:

393 394
 openssl smime -sign -in message.txt -text -out mail.msg \
	-signer mycert.pem
395

396
Create an opaque signed message:
397

398 399
 openssl smime -sign -in message.txt -text -out mail.msg -nodetach \
	-signer mycert.pem
400 401 402 403

Create a signed message, include some additional certificates and
read the private key from another file:

404 405
 openssl smime -sign -in in.txt -text -out mail.msg \
	-signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
406

407 408 409 410 411
Create a signed message with two signers:

 openssl smime -sign -in message.txt -text -out mail.msg \
	-signer mycert.pem -signer othercert.pem

412 413
Send a signed message under Unix directly to sendmail, including headers:

414 415 416
 openssl smime -sign -in in.txt -text -signer mycert.pem \
	-from steve@openssl.org -to someone@somewhere \
	-subject "Signed message" | sendmail someone@somewhere
417 418 419 420 421 422 423

Verify a message and extract the signer's certificate if successful:

 openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt

Send encrypted mail using triple DES:

424 425 426
 openssl smime -encrypt -in in.txt -from steve@openssl.org \
	-to someone@somewhere -subject "Encrypted message" \
	-des3 user.pem -out mail.msg
427 428 429

Sign and encrypt mail:

430
 openssl smime -sign -in ml.txt -signer my.pem -text \
D
 
Dr. Stephen Henson 已提交
431
	| openssl smime -encrypt -out mail.msg \
432 433
	-from steve@openssl.org -to someone@somewhere \
	-subject "Signed and Encrypted message" -des3 user.pem
434

435 436
Note: the encryption command does not include the B<-text> option because the
message being encrypted already has MIME headers.
437 438 439 440 441

Decrypt mail:

 openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem

D
 
Dr. Stephen Henson 已提交
442 443 444 445 446
The output from Netscape form signing is a PKCS#7 structure with the
detached signature format. You can use this program to verify the
signature by line wrapping the base64 encoded structure and surrounding
it with:

D
Typo  
Dr. Stephen Henson 已提交
447 448
 -----BEGIN PKCS7-----
 -----END PKCS7-----
D
 
Dr. Stephen Henson 已提交
449

450
and using the command: 
D
 
Dr. Stephen Henson 已提交
451 452 453

 openssl smime -verify -inform PEM -in signature.pem -content content.txt

454
Alternatively you can base64 decode the signature and use:
D
 
Dr. Stephen Henson 已提交
455 456 457

 openssl smime -verify -inform DER -in signature.der -content content.txt

458 459 460 461
Create an encrypted message using 128 bit Camellia:

 openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem

462 463 464 465
Add a signer to an existing message:

 openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg

466 467
=head1 BUGS

468 469
The MIME parser isn't very clever: it seems to handle most messages that I've
thrown at it but it may choke on others.
470

471 472 473 474
The code currently will only write out the signer's certificate to a file: if
the signer has a separate encryption certificate this must be manually
extracted. There should be some heuristic that determines the correct
encryption certificate.
475

476 477
Ideally a database should be maintained of a certificates for each email
address.
478 479

The code doesn't currently take note of the permitted symmetric encryption
480
algorithms as supplied in the SMIMECapabilities signed attribute. This means the
481 482 483 484 485 486 487
user has to manually include the correct encryption algorithm. It should store
the list of permitted ciphers in a database and only use those.

No revocation checking is done on the signer's certificate.

The current code can only handle S/MIME v2 messages, the more complex S/MIME v3
structures may cause parsing errors.
488

489 490 491
=head1 HISTORY

The use of multiple B<-signer> options and the B<-resign> command were first
492
added in OpenSSL 1.0.0
493

494
The -no_alt_chains options was first added to OpenSSL 1.1.0.
495

496
=cut
R
Rich Salz 已提交
497 498 499 500 501 502 503 504 505 506 507

=head1 COPYRIGHT

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut