]>
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>] | |
13 | [B<-verify>] | |
14 | [B<-pk7out>] | |
3fc9635e | 15 | [B<-des>] |
e3775a33 DSH |
16 | [B<-des3>] |
17 | [B<-rc2-40>] | |
18 | [B<-rc2-64>] | |
19 | [B<-rc2-128>] | |
20 | [B<-in file>] | |
21 | [B<-certfile file>] | |
22 | [B<-signer file>] | |
23 | [B<-recip file>] | |
24 | [B<-in file>] | |
fd13f0ee | 25 | [B<-inform SMIME|PEM|DER>] |
e3775a33 DSH |
26 | [B<-inkey file>] |
27 | [B<-out file>] | |
fd13f0ee DSH |
28 | [B<-outform SMIME|PEM|DER>] |
29 | [B<-content file>] | |
e3775a33 DSH |
30 | [B<-to addr>] |
31 | [B<-from ad>] | |
32 | [B<-subject s>] | |
33 | [B<-text>] | |
d13e4eb0 | 34 | [B<-rand file(s)>] |
e3775a33 DSH |
35 | [cert.pem]... |
36 | ||
37 | =head1 DESCRIPTION | |
38 | ||
39 | The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and | |
40 | verify S/MIME messages. | |
41 | ||
42 | =head1 COMMAND OPTIONS | |
43 | ||
44 | There are five operation options that set the type of operation to be performed. | |
45 | The meaning of the other options varies according to the operation type. | |
46 | ||
47 | =over 4 | |
48 | ||
49 | =item B<-encrypt> | |
50 | ||
51 | encrypt mail for the given recipient certificates. Input file is the message | |
52 | to be encrypted. The output file is the encrypted mail in MIME format. | |
53 | ||
54 | =item B<-decrypt> | |
55 | ||
56 | decrypt mail using the supplied certificate and private key. Expects an | |
57 | encrypted mail message in MIME format for the input file. The decrypted mail | |
58 | is written to the output file. | |
59 | ||
60 | =item B<-sign> | |
61 | ||
62 | sign mail using the supplied certificate and private key. Input file is | |
63 | the message to be signed. The signed message in MIME format is written | |
64 | to the output file. | |
65 | ||
66 | =item B<-verify> | |
67 | ||
68 | verify signed mail. Expects a signed mail message on input and outputs | |
69 | the signed data. Both clear text and opaque signing is supported. | |
70 | ||
71 | =item B<-pk7out> | |
72 | ||
73 | takes an input message and writes out a PEM encoded PKCS#7 structure. | |
74 | ||
75 | =item B<-in filename> | |
76 | ||
77 | the input message to be encrypted or signed or the MIME message to | |
78 | be decrypted or verified. | |
79 | ||
fd13f0ee DSH |
80 | =item B<-inform SMIME|PEM|DER> |
81 | ||
82 | this specifies the input format for the PKCS#7 structure. The default | |
83 | is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> | |
84 | format change this to expect PEM and DER format PKCS#7 structures | |
85 | instead. This currently only affects the input format of the PKCS#7 | |
86 | structure, if no PKCS#7 structure is being input (for example with | |
87 | B<-encrypt> or B<-sign>) this option has no effect. | |
88 | ||
e3775a33 DSH |
89 | =item B<-out filename> |
90 | ||
91 | the message text that has been decrypted or verified or the output MIME | |
92 | format message that has been signed or verified. | |
93 | ||
fd13f0ee DSH |
94 | =item B<-outform SMIME|PEM|DER> |
95 | ||
96 | this specifies the output format for the PKCS#7 structure. The default | |
97 | is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER> | |
98 | format change this to write PEM and DER format PKCS#7 structures | |
99 | instead. This currently only affects the output format of the PKCS#7 | |
100 | structure, if no PKCS#7 structure is being output (for example with | |
101 | B<-verify> or B<-decrypt>) this option has no effect. | |
102 | ||
103 | =item B<-content filename> | |
104 | ||
105 | This specifies a file containing the detached content, this is only | |
106 | useful with the B<-verify> command. This is only usable if the PKCS#7 | |
107 | structure is using the detached signature form where the content is | |
108 | not included. This option will override any content if the input format | |
109 | is S/MIME and it uses the multipart/signed MIME content type. | |
110 | ||
e3775a33 DSH |
111 | =item B<-text> |
112 | ||
113 | this option adds plain text (text/plain) MIME headers to the supplied | |
114 | message if encrypting or signing. If decrypting or verifying it strips | |
115 | off text headers: if the decrypted or verified message is not of MIME | |
116 | type text/plain then an error occurs. | |
117 | ||
118 | =item B<-CAfile file> | |
119 | ||
120 | a file containing trusted CA certificates, only used with B<-verify>. | |
121 | ||
122 | =item B<-CApath dir> | |
123 | ||
124 | a directory containing trusted CA certificates, only used with | |
125 | B<-verify>. This directory must be a standard certificate directory: that | |
126 | is a hash of each subject name (using B<x509 -hash>) should be linked | |
127 | to each certificate. | |
128 | ||
3fc9635e | 129 | =item B<-des -des3 -rc2-40 -rc2-64 -rc2-128> |
e3775a33 DSH |
130 | |
131 | the encryption algorithm to use. DES (56 bits), triple DES (168 bits) | |
132 | or 40, 64 or 128 bit RC2 respectively if not specified 40 bit RC2 is | |
133 | used. Only used with B<-encrypt>. | |
134 | ||
135 | =item B<-nointern> | |
136 | ||
137 | when verifying a message normally certificates (if any) included in | |
138 | the message are searched for the signing certificate. With this option | |
139 | only the certificates specified in the B<-certfile> option are used. | |
140 | The supplied certificates can still be used as untrusted CAs however. | |
141 | ||
142 | =item B<-noverify> | |
143 | ||
144 | do not verify the signers certificate of a signed message. | |
145 | ||
146 | =item B<-nochain> | |
147 | ||
19d2bb57 | 148 | do not do chain verification of signers certificates: that is don't |
e3775a33 DSH |
149 | use the certificates in the signed message as untrusted CAs. |
150 | ||
151 | =item B<-nosigs> | |
152 | ||
153 | don't try to verify the signatures on the message. | |
154 | ||
155 | =item B<-nocerts> | |
156 | ||
157 | when signing a message the signer's certificate is normally included | |
158 | with this option it is excluded. This will reduce the size of the | |
159 | signed message but the verifier must have a copy of the signers certificate | |
160 | available locally (passed using the B<-certfile> option for example). | |
161 | ||
162 | =item B<-noattr> | |
163 | ||
164 | normally when a message is signed a set of attributes are included which | |
165 | include the signing time and supported symmetric algorithms. With this | |
166 | option they are not included. | |
167 | ||
168 | =item B<-binary> | |
169 | ||
170 | normally the input message is converted to "canonical" format which is | |
3fc9635e DSH |
171 | effectively using CR and LF as end of line: as required by the S/MIME |
172 | specification. When this option is present no translation occurs. This | |
173 | is useful when handling binary data which may not be in MIME format. | |
e3775a33 DSH |
174 | |
175 | =item B<-nodetach> | |
176 | ||
177 | when signing a message use opaque signing: this form is more resistant | |
178 | to translation by mail relays but it cannot be read by mail agents that | |
179 | do not support S/MIME. Without this option cleartext signing with | |
180 | the MIME type multipart/signed is used. | |
181 | ||
182 | =item B<-certfile file> | |
183 | ||
184 | allows additional certificates to be specified. When signing these will | |
185 | be included with the message. When verifying these will be searched for | |
186 | the signers certificates. The certificates should be in PEM format. | |
187 | ||
188 | =item B<-signer file> | |
189 | ||
190 | the signers certificate when signing a message. If a message is | |
191 | being verified then the signers certificates will be written to this | |
192 | file if the verification was successful. | |
193 | ||
194 | =item B<-recip file> | |
195 | ||
196 | the recipients certificate when decrypting a message. This certificate | |
197 | must match one of the recipients of the message or an error occurs. | |
198 | ||
199 | =item B<-inkey file> | |
200 | ||
201 | the private key to use when signing or decrypting. This must match the | |
202 | corresponding certificate. If this option is not specified then the | |
203 | private key must be included in the certificate file specified with | |
204 | the B<-recip> or B<-signer> file. | |
205 | ||
d13e4eb0 DSH |
206 | =item B<-rand file(s)> |
207 | ||
208 | a file or files containing random data used to seed the random number | |
a4cfd178 UM |
209 | generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). |
210 | Multiple files can be specified separated by a OS-dependent character. | |
b87ef946 | 211 | The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for |
a4cfd178 | 212 | all others. |
d13e4eb0 | 213 | |
e3775a33 DSH |
214 | =item B<cert.pem...> |
215 | ||
216 | one or more certificates of message recipients: used when encrypting | |
217 | a message. | |
218 | ||
219 | =item B<-to, -from, -subject> | |
220 | ||
221 | the relevant mail headers. These are included outside the signed | |
222 | portion of a message so they may be included manually. If signing | |
223 | then many S/MIME mail clients check the signers certificate's email | |
224 | address matches that specified in the From: address. | |
225 | ||
226 | =back | |
227 | ||
228 | =head1 NOTES | |
229 | ||
230 | The MIME message must be sent without any blank lines between the | |
231 | headers and the output. Some mail programs will automatically add | |
232 | a blank line. Piping the mail directly to sendmail is one way to | |
233 | achieve the correct format. | |
234 | ||
3fc9635e | 235 | The supplied message to be signed or encrypted must include the |
fd13f0ee | 236 | necessary MIME headers or many S/MIME clients wont display it |
3fc9635e DSH |
237 | properly (if at all). You can use the B<-text> option to automatically |
238 | add plain text headers. | |
239 | ||
e3775a33 DSH |
240 | A "signed and encrypted" message is one where a signed message is |
241 | then encrypted. This can be produced by encrypting an already signed | |
3fc9635e | 242 | message: see the examples section. |
e3775a33 DSH |
243 | |
244 | This version of the program only allows one signer per message but it | |
245 | will verify multiple signers on received messages. Some S/MIME clients | |
19d2bb57 | 246 | choke if a message contains multiple signers. It is possible to sign |
e3775a33 DSH |
247 | messages "in parallel" by signing an already signed message. |
248 | ||
3fc9635e DSH |
249 | The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME |
250 | clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 | |
251 | encrypted data is used for other purposes. | |
252 | ||
e3775a33 DSH |
253 | =head1 EXIT CODES |
254 | ||
255 | =over 4 | |
256 | ||
257 | =item 0 | |
258 | ||
3fc9635e | 259 | the operation was completely successfully. |
e3775a33 DSH |
260 | |
261 | =item 1 | |
262 | ||
263 | an error occurred parsing the command options. | |
264 | ||
265 | =item 2 | |
266 | ||
267 | one of the input files could not be read. | |
268 | ||
269 | =item 3 | |
270 | ||
271 | an error occurred creating the PKCS#7 file or when reading the MIME | |
272 | message. | |
273 | ||
274 | =item 4 | |
275 | ||
276 | an error occurred decrypting or verifying the message. | |
277 | ||
278 | =item 5 | |
279 | ||
19d2bb57 | 280 | the message was verified correctly but an error occurred writing out |
e3775a33 DSH |
281 | the signers certificates. |
282 | ||
283 | =back | |
284 | ||
285 | =head1 EXAMPLES | |
286 | ||
3fc9635e DSH |
287 | Create a cleartext signed message: |
288 | ||
1675f6eb RL |
289 | openssl smime -sign -in message.txt -text -out mail.msg \ |
290 | -signer mycert.pem | |
3fc9635e DSH |
291 | |
292 | Create and opaque signed message | |
293 | ||
1675f6eb RL |
294 | openssl smime -sign -in message.txt -text -out mail.msg -nodetach \ |
295 | -signer mycert.pem | |
3fc9635e DSH |
296 | |
297 | Create a signed message, include some additional certificates and | |
298 | read the private key from another file: | |
299 | ||
1675f6eb RL |
300 | openssl smime -sign -in in.txt -text -out mail.msg \ |
301 | -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem | |
3fc9635e DSH |
302 | |
303 | Send a signed message under Unix directly to sendmail, including headers: | |
304 | ||
1675f6eb RL |
305 | openssl smime -sign -in in.txt -text -signer mycert.pem \ |
306 | -from steve@openssl.org -to someone@somewhere \ | |
307 | -subject "Signed message" | sendmail someone@somewhere | |
3fc9635e DSH |
308 | |
309 | Verify a message and extract the signer's certificate if successful: | |
310 | ||
311 | openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt | |
312 | ||
313 | Send encrypted mail using triple DES: | |
314 | ||
1675f6eb RL |
315 | openssl smime -encrypt -in in.txt -from steve@openssl.org \ |
316 | -to someone@somewhere -subject "Encrypted message" \ | |
317 | -des3 user.pem -out mail.msg | |
3fc9635e DSH |
318 | |
319 | Sign and encrypt mail: | |
320 | ||
1675f6eb RL |
321 | openssl smime -sign -in ml.txt -signer my.pem -text \ |
322 | | openssl -encrypt -out mail.msg \ | |
323 | -from steve@openssl.org -to someone@somewhere \ | |
324 | -subject "Signed and Encrypted message" -des3 user.pem | |
3fc9635e DSH |
325 | |
326 | Note: the encryption command does not include the B<-text> option because the message | |
327 | being encrypted already has MIME headers. | |
328 | ||
329 | Decrypt mail: | |
330 | ||
331 | openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem | |
332 | ||
fd13f0ee DSH |
333 | The output from Netscape form signing is a PKCS#7 structure with the |
334 | detached signature format. You can use this program to verify the | |
335 | signature by line wrapping the base64 encoded structure and surrounding | |
336 | it with: | |
337 | ||
338 | -----BEGIN PKCS7---- | |
339 | -----END PKCS7---- | |
340 | ||
341 | and using the command, | |
342 | ||
343 | openssl smime -verify -inform PEM -in signature.pem -content content.txt | |
344 | ||
345 | alternatively you can base64 decode the signature and use | |
346 | ||
347 | openssl smime -verify -inform DER -in signature.der -content content.txt | |
348 | ||
3fc9635e DSH |
349 | =head1 BUGS |
350 | ||
351 | The MIME parser isn't very clever: it seems to handle most messages that I've thrown | |
352 | at it but it may choke on others. | |
353 | ||
354 | The code currently will only write out the signer's certificate to a file: if the | |
355 | signer has a separate encryption certificate this must be manually extracted. There | |
356 | should be some heuristic that determines the correct encryption certificate. | |
357 | ||
358 | Ideally a database should be maintained of a certificates for each email address. | |
359 | ||
360 | The code doesn't currently take note of the permitted symmetric encryption | |
361 | algorithms as supplied in the SMIMECapabilities signed attribute. this means the | |
362 | user has to manually include the correct encryption algorithm. It should store | |
363 | the list of permitted ciphers in a database and only use those. | |
364 | ||
365 | No revocation checking is done on the signer's certificate. | |
366 | ||
367 | The current code can only handle S/MIME v2 messages, the more complex S/MIME v3 | |
368 | structures may cause parsing errors. | |
e3775a33 DSH |
369 | |
370 | =cut |