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