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