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