1SMIME(1)                            OpenSSL                           SMIME(1)
2
3
4

NAME

6       openssl-smime, smime - S/MIME utility
7

SYNOPSIS

9       openssl smime [-help] [-encrypt] [-decrypt] [-sign] [-resign] [-verify]
10       [-pk7out] [-binary] [-crlfeol] [-cipher] [-in file] [-CAfile file]
11       [-CApath dir] [-no-CAfile] [-no-CApath] [-attime timestamp]
12       [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy]
13       [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map]
14       [-partial_chain] [-policy arg] [-policy_check] [-policy_print]
15       [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192]
16       [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num]
17       [-verify_depth num] [-verify_email email] [-verify_hostname hostname]
18       [-verify_ip ip] [-verify_name name] [-x509_strict] [-certfile file]
19       [-signer file] [-recip  file] [-inform SMIME|PEM|DER] [-passin arg]
20       [-inkey file_or_id] [-out file] [-outform SMIME|PEM|DER] [-content
21       file] [-to addr] [-from ad] [-subject s] [-text] [-indef] [-noindef]
22       [-stream] [-rand file...]  [-writerand file] [-md digest] [cert.pem]...
23

DESCRIPTION

25       The smime command handles S/MIME mail. It can encrypt, decrypt, sign
26       and verify S/MIME messages.
27

OPTIONS

29       There are six operation options that set the type of operation to be
30       performed.  The meaning of the other options varies according to the
31       operation type.
32
33       -help
34           Print out a usage message.
35
36       -encrypt
37           Encrypt mail for the given recipient certificates. Input file is
38           the message to be encrypted. The output file is the encrypted mail
39           in MIME format.
40
41           Note that no revocation check is done for the recipient cert, so if
42           that key has been compromised, others may be able to decrypt the
43           text.
44
45       -decrypt
46           Decrypt mail using the supplied certificate and private key.
47           Expects an encrypted mail message in MIME format for the input
48           file. The decrypted mail is written to the output file.
49
50       -sign
51           Sign mail using the supplied certificate and private key. Input
52           file is the message to be signed. The signed message in MIME format
53           is written to the output file.
54
55       -verify
56           Verify signed mail. Expects a signed mail message on input and
57           outputs the signed data. Both clear text and opaque signing is
58           supported.
59
60       -pk7out
61           Takes an input message and writes out a PEM encoded PKCS#7
62           structure.
63
64       -resign
65           Resign a message: take an existing message and one or more new
66           signers.
67
68       -in filename
69           The input message to be encrypted or signed or the MIME message to
70           be decrypted or verified.
71
72       -inform SMIME|PEM|DER
73           This specifies the input format for the PKCS#7 structure. The
74           default is SMIME which reads an S/MIME format message. PEM and DER
75           format change this to expect PEM and DER format PKCS#7 structures
76           instead. This currently only affects the input format of the PKCS#7
77           structure, if no PKCS#7 structure is being input (for example with
78           -encrypt or -sign) this option has no effect.
79
80       -out filename
81           The message text that has been decrypted or verified or the output
82           MIME format message that has been signed or verified.
83
84       -outform SMIME|PEM|DER
85           This specifies the output format for the PKCS#7 structure. The
86           default is SMIME which write an S/MIME format message. PEM and DER
87           format change this to write PEM and DER format PKCS#7 structures
88           instead. This currently only affects the output format of the
89           PKCS#7 structure, if no PKCS#7 structure is being output (for
90           example with -verify or -decrypt) this option has no effect.
91
92       -stream -indef -noindef
93           The -stream and -indef options are equivalent and enable streaming
94           I/O for encoding operations. This permits single pass processing of
95           data without the need to hold the entire contents in memory,
96           potentially supporting very large files. Streaming is automatically
97           set for S/MIME signing with detached data if the output format is
98           SMIME it is currently off by default for all other operations.
99
100       -noindef
101           Disable streaming I/O where it would produce and indefinite length
102           constructed encoding. This option currently has no effect. In
103           future streaming will be enabled by default on all relevant
104           operations and this option will disable it.
105
106       -content filename
107           This specifies a file containing the detached content, this is only
108           useful with the -verify command. This is only usable if the PKCS#7
109           structure is using the detached signature form where the content is
110           not included. This option will override any content if the input
111           format is S/MIME and it uses the multipart/signed MIME content
112           type.
113
114       -text
115           This option adds plain text (text/plain) MIME headers to the
116           supplied message if encrypting or signing. If decrypting or
117           verifying it strips off text headers: if the decrypted or verified
118           message is not of MIME type text/plain then an error occurs.
119
120       -CAfile file
121           A file containing trusted CA certificates, only used with -verify.
122
123       -CApath dir
124           A directory containing trusted CA certificates, only used with
125           -verify. This directory must be a standard certificate directory:
126           that is a hash of each subject name (using x509 -hash) should be
127           linked to each certificate.
128
129       -no-CAfile
130           Do not load the trusted CA certificates from the default file
131           location.
132
133       -no-CApath
134           Do not load the trusted CA certificates from the default directory
135           location.
136
137       -md digest
138           Digest algorithm to use when signing or resigning. If not present
139           then the default digest algorithm for the signing key will be used
140           (usually SHA1).
141
142       -cipher
143           The encryption algorithm to use. For example DES  (56 bits) - -des,
144           triple DES (168 bits) - -des3, EVP_get_cipherbyname() function) can
145           also be used preceded by a dash, for example -aes-128-cbc. See enc
146           for list of ciphers supported by your version of OpenSSL.
147
148           If not specified triple DES is used. Only used with -encrypt.
149
150       -nointern
151           When verifying a message normally certificates (if any) included in
152           the message are searched for the signing certificate. With this
153           option only the certificates specified in the -certfile option are
154           used.  The supplied certificates can still be used as untrusted CAs
155           however.
156
157       -noverify
158           Do not verify the signers certificate of a signed message.
159
160       -nochain
161           Do not do chain verification of signers certificates: that is don't
162           use the certificates in the signed message as untrusted CAs.
163
164       -nosigs
165           Don't try to verify the signatures on the message.
166
167       -nocerts
168           When signing a message the signer's certificate is normally
169           included with this option it is excluded. This will reduce the size
170           of the signed message but the verifier must have a copy of the
171           signers certificate available locally (passed using the -certfile
172           option for example).
173
174       -noattr
175           Normally when a message is signed a set of attributes are included
176           which include the signing time and supported symmetric algorithms.
177           With this option they are not included.
178
179       -binary
180           Normally the input message is converted to "canonical" format which
181           is effectively using CR and LF as end of line: as required by the
182           S/MIME specification. When this option is present no translation
183           occurs. This is useful when handling binary data which may not be
184           in MIME format.
185
186       -crlfeol
187           Normally the output file uses a single LF as end of line. When this
188           option is present CRLF is used instead.
189
190       -nodetach
191           When signing a message use opaque signing: this form is more
192           resistant to translation by mail relays but it cannot be read by
193           mail agents that do not support S/MIME.  Without this option
194           cleartext signing with the MIME type multipart/signed is used.
195
196       -certfile file
197           Allows additional certificates to be specified. When signing these
198           will be included with the message. When verifying these will be
199           searched for the signers certificates. The certificates should be
200           in PEM format.
201
202       -signer file
203           A signing certificate when signing or resigning a message, this
204           option can be used multiple times if more than one signer is
205           required. If a message is being verified then the signers
206           certificates will be written to this file if the verification was
207           successful.
208
209       -recip file
210           The recipients certificate when decrypting a message. This
211           certificate must match one of the recipients of the message or an
212           error occurs.
213
214       -inkey file_or_id
215           The private key to use when signing or decrypting. This must match
216           the corresponding certificate. If this option is not specified then
217           the private key must be included in the certificate file specified
218           with the -recip or -signer file. When signing this option can be
219           used multiple times to specify successive keys.  If no engine is
220           used, the argument is taken as a file; if an engine is specified,
221           the argument is given to the engine as a key identifier.
222
223       -passin arg
224           The private key password source. For more information about the
225           format of arg see the PASS PHRASE ARGUMENTS section in openssl(1).
226
227       -rand file...
228           A file or files containing random data used to seed the random
229           number generator.  Multiple files can be specified separated by an
230           OS-dependent character.  The separator is ; for MS-Windows, , for
231           OpenVMS, and : for all others.
232
233       [-writerand file]
234           Writes random data to the specified file upon exit.  This can be
235           used with a subsequent -rand flag.
236
237       cert.pem...
238           One or more certificates of message recipients: used when
239           encrypting a message.
240
241       -to, -from, -subject
242           The relevant mail headers. These are included outside the signed
243           portion of a message so they may be included manually. If signing
244           then many S/MIME mail clients check the signers certificate's email
245           address matches that specified in the From: address.
246
247       -attime, -check_ss_sig, -crl_check, -crl_check_all, -explicit_policy,
248       -extended_crl, -ignore_critical, -inhibit_any, -inhibit_map,
249       -no_alt_chains, -partial_chain, -policy, -policy_check, -policy_print,
250       -purpose, -suiteB_128, -suiteB_128_only, -suiteB_192, -trusted_first,
251       -use_deltas, -auth_level, -verify_depth, -verify_email,
252       -verify_hostname, -verify_ip, -verify_name, -x509_strict
253           Set various options of certificate chain verification. See
254           verify(1) manual page for details.
255

NOTES

257       The MIME message must be sent without any blank lines between the
258       headers and the output. Some mail programs will automatically add a
259       blank line. Piping the mail directly to sendmail is one way to achieve
260       the correct format.
261
262       The supplied message to be signed or encrypted must include the
263       necessary MIME headers or many S/MIME clients won't display it properly
264       (if at all). You can use the -text option to automatically add plain
265       text headers.
266
267       A "signed and encrypted" message is one where a signed message is then
268       encrypted. This can be produced by encrypting an already signed
269       message: see the examples section.
270
271       This version of the program only allows one signer per message but it
272       will verify multiple signers on received messages. Some S/MIME clients
273       choke if a message contains multiple signers. It is possible to sign
274       messages "in parallel" by signing an already signed message.
275
276       The options -encrypt and -decrypt reflect common usage in S/MIME
277       clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7
278       encrypted data is used for other purposes.
279
280       The -resign option uses an existing message digest when adding a new
281       signer. This means that attributes must be present in at least one
282       existing signer using the same message digest or this operation will
283       fail.
284
285       The -stream and -indef options enable streaming I/O support.  As a
286       result the encoding is BER using indefinite length constructed encoding
287       and no longer DER. Streaming is supported for the -encrypt operation
288       and the -sign operation if the content is not detached.
289
290       Streaming is always used for the -sign operation with detached data but
291       since the content is no longer part of the PKCS#7 structure the
292       encoding remains DER.
293

EXIT CODES

295       0   The operation was completely successfully.
296
297       1   An error occurred parsing the command options.
298
299       2   One of the input files could not be read.
300
301       3   An error occurred creating the PKCS#7 file or when reading the MIME
302           message.
303
304       4   An error occurred decrypting or verifying the message.
305
306       5   The message was verified correctly but an error occurred writing
307           out the signers certificates.
308

EXAMPLES

310       Create a cleartext signed message:
311
312        openssl smime -sign -in message.txt -text -out mail.msg \
313               -signer mycert.pem
314
315       Create an opaque signed message:
316
317        openssl smime -sign -in message.txt -text -out mail.msg -nodetach \
318               -signer mycert.pem
319
320       Create a signed message, include some additional certificates and read
321       the private key from another file:
322
323        openssl smime -sign -in in.txt -text -out mail.msg \
324               -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
325
326       Create a signed message with two signers:
327
328        openssl smime -sign -in message.txt -text -out mail.msg \
329               -signer mycert.pem -signer othercert.pem
330
331       Send a signed message under Unix directly to sendmail, including
332       headers:
333
334        openssl smime -sign -in in.txt -text -signer mycert.pem \
335               -from steve@openssl.org -to someone@somewhere \
336               -subject "Signed message" | sendmail someone@somewhere
337
338       Verify a message and extract the signer's certificate if successful:
339
340        openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt
341
342       Send encrypted mail using triple DES:
343
344        openssl smime -encrypt -in in.txt -from steve@openssl.org \
345               -to someone@somewhere -subject "Encrypted message" \
346               -des3 user.pem -out mail.msg
347
348       Sign and encrypt mail:
349
350        openssl smime -sign -in ml.txt -signer my.pem -text \
351               | openssl smime -encrypt -out mail.msg \
352               -from steve@openssl.org -to someone@somewhere \
353               -subject "Signed and Encrypted message" -des3 user.pem
354
355       Note: the encryption command does not include the -text option because
356       the message being encrypted already has MIME headers.
357
358       Decrypt mail:
359
360        openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
361
362       The output from Netscape form signing is a PKCS#7 structure with the
363       detached signature format. You can use this program to verify the
364       signature by line wrapping the base64 encoded structure and surrounding
365       it with:
366
367        -----BEGIN PKCS7-----
368        -----END PKCS7-----
369
370       and using the command:
371
372        openssl smime -verify -inform PEM -in signature.pem -content content.txt
373
374       Alternatively you can base64 decode the signature and use:
375
376        openssl smime -verify -inform DER -in signature.der -content content.txt
377
378       Create an encrypted message using 128 bit Camellia:
379
380        openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
381
382       Add a signer to an existing message:
383
384        openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg
385

BUGS

387       The MIME parser isn't very clever: it seems to handle most messages
388       that I've thrown at it but it may choke on others.
389
390       The code currently will only write out the signer's certificate to a
391       file: if the signer has a separate encryption certificate this must be
392       manually extracted. There should be some heuristic that determines the
393       correct encryption certificate.
394
395       Ideally a database should be maintained of a certificates for each
396       email address.
397
398       The code doesn't currently take note of the permitted symmetric
399       encryption algorithms as supplied in the SMIMECapabilities signed
400       attribute. This means the user has to manually include the correct
401       encryption algorithm. It should store the list of permitted ciphers in
402       a database and only use those.
403
404       No revocation checking is done on the signer's certificate.
405
406       The current code can only handle S/MIME v2 messages, the more complex
407       S/MIME v3 structures may cause parsing errors.
408

HISTORY

410       The use of multiple -signer options and the -resign command were first
411       added in OpenSSL 1.0.0
412
413       The -no_alt_chains options was first added to OpenSSL 1.1.0.
414
416       Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
417
418       Licensed under the OpenSSL license (the "License").  You may not use
419       this file except in compliance with the License.  You can obtain a copy
420       in the file LICENSE in the source distribution or at
421       <https://www.openssl.org/source/license.html>.
422
423
424
4251.1.1                             2018-09-11                          SMIME(1)
Impressum