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