1OPENSSL-SMIME(1ossl)                OpenSSL               OPENSSL-SMIME(1ossl)
2
3
4

NAME

6       openssl-smime - S/MIME command
7

SYNOPSIS

9       openssl smime [-help] [-encrypt] [-decrypt] [-sign] [-resign] [-verify]
10       [-pk7out] [-binary] [-crlfeol] [-cipher] [-in file] [-certfile file]
11       [-signer file] [-nointern] [-noverify] [-nochain] [-nosigs] [-nocerts]
12       [-noattr] [-nodetach] [-nosmimecap] [-recip  file] [-inform
13       DER|PEM|SMIME] [-outform DER|PEM|SMIME] [-keyform DER|PEM|P12|ENGINE]
14       [-passin arg] [-inkey filename|uri] [-out file] [-content file] [-to
15       addr] [-from ad] [-subject s] [-text] [-indef] [-noindef] [-stream]
16       [-md digest] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath]
17       [-CAstore uri] [-no-CAstore] [-engine id] [-rand files] [-writerand
18       file] [-allow_proxy_certs] [-attime timestamp] [-no_check_time]
19       [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy]
20       [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map]
21       [-partial_chain] [-policy arg] [-policy_check] [-policy_print]
22       [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192]
23       [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num]
24       [-verify_depth num] [-verify_email email] [-verify_hostname hostname]
25       [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks]
26       [-provider name] [-provider-path path] [-propquery propq] [-config
27       configfile] recipcert ...
28

DESCRIPTION

30       This command handles S/MIME mail. It can encrypt, decrypt, sign and
31       verify S/MIME messages.
32

OPTIONS

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

NOTES

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

EXIT CODES

303       0   The operation was completely successfully.
304
305       1   An error occurred parsing the command options.
306
307       2   One of the input files could not be read.
308
309       3   An error occurred creating the PKCS#7 file or when reading the MIME
310           message.
311
312       4   An error occurred decrypting or verifying the message.
313
314       5   The message was verified correctly but an error occurred writing
315           out the signers certificates.
316

EXAMPLES

318       Create a cleartext signed message:
319
320        openssl smime -sign -in message.txt -text -out mail.msg \
321               -signer mycert.pem
322
323       Create an opaque signed message:
324
325        openssl smime -sign -in message.txt -text -out mail.msg -nodetach \
326               -signer mycert.pem
327
328       Create a signed message, include some additional certificates and read
329       the private key from another file:
330
331        openssl smime -sign -in in.txt -text -out mail.msg \
332               -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
333
334       Create a signed message with two signers:
335
336        openssl smime -sign -in message.txt -text -out mail.msg \
337               -signer mycert.pem -signer othercert.pem
338
339       Send a signed message under Unix directly to sendmail, including
340       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 -text option because
364       the 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

BUGS

395       The MIME parser isn't very clever: it seems to handle most messages
396       that I've thrown at it but it may choke on others.
397
398       The code currently will only write out the signer's certificate to a
399       file: if the signer has a separate encryption certificate this must be
400       manually extracted. There should be some heuristic that determines the
401       correct encryption certificate.
402
403       Ideally a database should be maintained of a certificates for each
404       email address.
405
406       The code doesn't currently take note of the permitted symmetric
407       encryption algorithms as supplied in the SMIMECapabilities signed
408       attribute. This means the user has to manually include the correct
409       encryption algorithm. It should store the list of permitted ciphers in
410       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
415       S/MIME v3 structures may cause parsing errors.
416

SEE ALSO

418       ossl_store-file(7)
419

HISTORY

421       The use of multiple -signer options and the -resign command were first
422       added in OpenSSL 1.0.0
423
424       The -no_alt_chains option was added in OpenSSL 1.1.0.
425
426       The -engine option was deprecated in OpenSSL 3.0.
427
429       Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
430
431       Licensed under the Apache License 2.0 (the "License").  You may not use
432       this file except in compliance with the License.  You can obtain a copy
433       in the file LICENSE in the source distribution or at
434       <https://www.openssl.org/source/license.html>.
435
436
437
4383.0.9                             2023-07-27              OPENSSL-SMIME(1ossl)
Impressum