Commit | Line | Data |
---|---|---|
5a44c043 | 1 | .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) |
01185282 PA |
2 | .\" |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sp \" Vertical space (when we can't use .PP) | |
6 | .if t .sp .5v | |
7 | .if n .sp | |
8 | .. | |
9 | .de Vb \" Begin verbatim text | |
10 | .ft CW | |
11 | .nf | |
12 | .ne \\$1 | |
13 | .. | |
14 | .de Ve \" End verbatim text | |
15 | .ft R | |
16 | .fi | |
17 | .. | |
18 | .\" Set up some character translations and predefined strings. \*(-- will | |
19 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
20 | .\" double quote, and \*(R" will give a right double quote. \*(C+ will | |
21 | .\" give a nicer C++. Capital omega is used to do unbreakable dashes and | |
22 | .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, | |
23 | .\" nothing in troff, for use with C<>. | |
24 | .tr \(*W- | |
25 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
26 | .ie n \{\ | |
27 | . ds -- \(*W- | |
28 | . ds PI pi | |
29 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
30 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
31 | . ds L" "" | |
32 | . ds R" "" | |
33 | . ds C` "" | |
34 | . ds C' "" | |
35 | 'br\} | |
36 | .el\{\ | |
37 | . ds -- \|\(em\| | |
38 | . ds PI \(*p | |
39 | . ds L" `` | |
40 | . ds R" '' | |
5a44c043 SW |
41 | . ds C` |
42 | . ds C' | |
01185282 PA |
43 | 'br\} |
44 | .\" | |
45 | .\" Escape single quotes in literal strings from groff's Unicode transform. | |
46 | .ie \n(.g .ds Aq \(aq | |
47 | .el .ds Aq ' | |
48 | .\" | |
49 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
50 | .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index | |
51 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
52 | .\" output yourself in some meaningful fashion. | |
5a44c043 SW |
53 | .\" |
54 | .\" Avoid warning from groff about undefined register 'F'. | |
55 | .de IX | |
01185282 | 56 | .. |
5a44c043 SW |
57 | .nr rF 0 |
58 | .if \n(.g .if rF .nr rF 1 | |
59 | .if (\n(rF:(\n(.g==0)) \{ | |
60 | . if \nF \{ | |
61 | . de IX | |
62 | . tm Index:\\$1\t\\n%\t"\\$2" | |
01185282 | 63 | .. |
5a44c043 SW |
64 | . if !\nF==2 \{ |
65 | . nr % 0 | |
66 | . nr F 2 | |
67 | . \} | |
68 | . \} | |
01185282 | 69 | .\} |
5a44c043 | 70 | .rr rF |
01185282 PA |
71 | .\" |
72 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
73 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
74 | . \" fudge factors for nroff and troff | |
75 | .if n \{\ | |
76 | . ds #H 0 | |
77 | . ds #V .8m | |
78 | . ds #F .3m | |
79 | . ds #[ \f1 | |
80 | . ds #] \fP | |
81 | .\} | |
82 | .if t \{\ | |
83 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
84 | . ds #V .6m | |
85 | . ds #F 0 | |
86 | . ds #[ \& | |
87 | . ds #] \& | |
88 | .\} | |
89 | . \" simple accents for nroff and troff | |
90 | .if n \{\ | |
91 | . ds ' \& | |
92 | . ds ` \& | |
93 | . ds ^ \& | |
94 | . ds , \& | |
95 | . ds ~ ~ | |
96 | . ds / | |
97 | .\} | |
98 | .if t \{\ | |
99 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
100 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
101 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
102 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
103 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
104 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
105 | .\} | |
106 | . \" troff and (daisy-wheel) nroff accents | |
107 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
108 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
109 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
110 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
111 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
112 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
113 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
114 | .ds ae a\h'-(\w'a'u*4/10)'e | |
115 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
116 | . \" corrections for vroff | |
117 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
118 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
119 | . \" for low resolution devices (crt and lpr) | |
120 | .if \n(.H>23 .if \n(.V>19 \ | |
121 | \{\ | |
122 | . ds : e | |
123 | . ds 8 ss | |
124 | . ds o a | |
125 | . ds d- d\h'-1'\(ga | |
126 | . ds D- D\h'-1'\(hy | |
127 | . ds th \o'bp' | |
128 | . ds Th \o'LP' | |
129 | . ds ae ae | |
130 | . ds Ae AE | |
131 | .\} | |
132 | .rm #[ #] #H #V #F C | |
133 | .\" ======================================================================== | |
134 | .\" | |
135 | .IX Title "CMS 1" | |
7dc78669 | 136 | .TH CMS 1 "2015-07-09" "1.0.1p" "OpenSSL" |
01185282 PA |
137 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
138 | .\" way too many mistakes in technical documents. | |
139 | .if n .ad l | |
140 | .nh | |
141 | .SH "NAME" | |
142 | cms \- CMS utility | |
143 | .SH "SYNOPSIS" | |
144 | .IX Header "SYNOPSIS" | |
145 | \&\fBopenssl\fR \fBcms\fR | |
146 | [\fB\-encrypt\fR] | |
147 | [\fB\-decrypt\fR] | |
148 | [\fB\-sign\fR] | |
149 | [\fB\-verify\fR] | |
150 | [\fB\-cmsout\fR] | |
151 | [\fB\-resign\fR] | |
152 | [\fB\-data_create\fR] | |
153 | [\fB\-data_out\fR] | |
154 | [\fB\-digest_create\fR] | |
155 | [\fB\-digest_verify\fR] | |
156 | [\fB\-compress\fR] | |
157 | [\fB\-uncompress\fR] | |
158 | [\fB\-EncryptedData_encrypt\fR] | |
159 | [\fB\-sign_receipt\fR] | |
160 | [\fB\-verify_receipt receipt\fR] | |
161 | [\fB\-in filename\fR] | |
162 | [\fB\-inform SMIME|PEM|DER\fR] | |
163 | [\fB\-rctform SMIME|PEM|DER\fR] | |
164 | [\fB\-out filename\fR] | |
165 | [\fB\-outform SMIME|PEM|DER\fR] | |
166 | [\fB\-stream \-indef \-noindef\fR] | |
167 | [\fB\-noindef\fR] | |
168 | [\fB\-content filename\fR] | |
169 | [\fB\-text\fR] | |
170 | [\fB\-noout\fR] | |
171 | [\fB\-print\fR] | |
172 | [\fB\-CAfile file\fR] | |
173 | [\fB\-CApath dir\fR] | |
60096f03 | 174 | [\fB\-no_alt_chains\fR] |
01185282 PA |
175 | [\fB\-md digest\fR] |
176 | [\fB\-[cipher]\fR] | |
177 | [\fB\-nointern\fR] | |
178 | [\fB\-no_signer_cert_verify\fR] | |
179 | [\fB\-nocerts\fR] | |
180 | [\fB\-noattr\fR] | |
181 | [\fB\-nosmimecap\fR] | |
182 | [\fB\-binary\fR] | |
183 | [\fB\-nodetach\fR] | |
184 | [\fB\-certfile file\fR] | |
185 | [\fB\-certsout file\fR] | |
186 | [\fB\-signer file\fR] | |
187 | [\fB\-recip file\fR] | |
188 | [\fB\-keyid\fR] | |
189 | [\fB\-receipt_request_all \-receipt_request_first\fR] | |
190 | [\fB\-receipt_request_from emailaddress\fR] | |
191 | [\fB\-receipt_request_to emailaddress\fR] | |
192 | [\fB\-receipt_request_print\fR] | |
193 | [\fB\-secretkey key\fR] | |
194 | [\fB\-secretkeyid id\fR] | |
195 | [\fB\-econtent_type type\fR] | |
196 | [\fB\-inkey file\fR] | |
197 | [\fB\-passin arg\fR] | |
198 | [\fB\-rand file(s)\fR] | |
199 | [\fBcert.pem...\fR] | |
200 | [\fB\-to addr\fR] | |
201 | [\fB\-from addr\fR] | |
202 | [\fB\-subject subj\fR] | |
203 | [cert.pem]... | |
204 | .SH "DESCRIPTION" | |
205 | .IX Header "DESCRIPTION" | |
206 | The \fBcms\fR command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and | |
207 | verify, compress and uncompress S/MIME messages. | |
208 | .SH "COMMAND OPTIONS" | |
209 | .IX Header "COMMAND OPTIONS" | |
210 | There are fourteen operation options that set the type of operation to be | |
211 | performed. The meaning of the other options varies according to the operation | |
212 | type. | |
213 | .IP "\fB\-encrypt\fR" 4 | |
214 | .IX Item "-encrypt" | |
215 | encrypt mail for the given recipient certificates. Input file is the message | |
216 | to be encrypted. The output file is the encrypted mail in \s-1MIME\s0 format. The | |
217 | actual \s-1CMS\s0 type is <B>EnvelopedData<B>. | |
218 | .IP "\fB\-decrypt\fR" 4 | |
219 | .IX Item "-decrypt" | |
220 | decrypt mail using the supplied certificate and private key. Expects an | |
221 | encrypted mail message in \s-1MIME\s0 format for the input file. The decrypted mail | |
222 | is written to the output file. | |
34240b21 SW |
223 | .IP "\fB\-debug_decrypt\fR" 4 |
224 | .IX Item "-debug_decrypt" | |
225 | this option sets the \fB\s-1CMS_DEBUG_DECRYPT\s0\fR flag. This option should be used | |
226 | with caution: see the notes section below. | |
01185282 PA |
227 | .IP "\fB\-sign\fR" 4 |
228 | .IX Item "-sign" | |
229 | sign mail using the supplied certificate and private key. Input file is | |
230 | the message to be signed. The signed message in \s-1MIME\s0 format is written | |
231 | to the output file. | |
232 | .IP "\fB\-verify\fR" 4 | |
233 | .IX Item "-verify" | |
234 | verify signed mail. Expects a signed mail message on input and outputs | |
235 | the signed data. Both clear text and opaque signing is supported. | |
236 | .IP "\fB\-cmsout\fR" 4 | |
237 | .IX Item "-cmsout" | |
238 | takes an input message and writes out a \s-1PEM\s0 encoded \s-1CMS\s0 structure. | |
239 | .IP "\fB\-resign\fR" 4 | |
240 | .IX Item "-resign" | |
241 | resign a message: take an existing message and one or more new signers. | |
242 | .IP "\fB\-data_create\fR" 4 | |
243 | .IX Item "-data_create" | |
5a44c043 | 244 | Create a \s-1CMS \s0\fBData\fR type. |
01185282 PA |
245 | .IP "\fB\-data_out\fR" 4 |
246 | .IX Item "-data_out" | |
247 | \&\fBData\fR type and output the content. | |
248 | .IP "\fB\-digest_create\fR" 4 | |
249 | .IX Item "-digest_create" | |
5a44c043 | 250 | Create a \s-1CMS \s0\fBDigestedData\fR type. |
01185282 PA |
251 | .IP "\fB\-digest_verify\fR" 4 |
252 | .IX Item "-digest_verify" | |
5a44c043 | 253 | Verify a \s-1CMS \s0\fBDigestedData\fR type and output the content. |
01185282 PA |
254 | .IP "\fB\-compress\fR" 4 |
255 | .IX Item "-compress" | |
5a44c043 | 256 | Create a \s-1CMS \s0\fBCompressedData\fR type. OpenSSL must be compiled with \fBzlib\fR |
01185282 PA |
257 | support for this option to work, otherwise it will output an error. |
258 | .IP "\fB\-uncompress\fR" 4 | |
259 | .IX Item "-uncompress" | |
5a44c043 | 260 | Uncompress a \s-1CMS \s0\fBCompressedData\fR type and output the content. OpenSSL must be |
01185282 PA |
261 | compiled with \fBzlib\fR support for this option to work, otherwise it will |
262 | output an error. | |
263 | .IP "\fB\-EncryptedData_encrypt\fR" 4 | |
264 | .IX Item "-EncryptedData_encrypt" | |
5a44c043 SW |
265 | Encrypt content using supplied symmetric key and algorithm using a \s-1CMS |
266 | \&\s0\fBEncrytedData\fR type and output the content. | |
01185282 PA |
267 | .IP "\fB\-sign_receipt\fR" 4 |
268 | .IX Item "-sign_receipt" | |
269 | Generate and output a signed receipt for the supplied message. The input | |
270 | message \fBmust\fR contain a signed receipt request. Functionality is otherwise | |
271 | similar to the \fB\-sign\fR operation. | |
272 | .IP "\fB\-verify_receipt receipt\fR" 4 | |
273 | .IX Item "-verify_receipt receipt" | |
274 | Verify a signed receipt in filename \fBreceipt\fR. The input message \fBmust\fR | |
275 | contain the original receipt request. Functionality is otherwise similar | |
276 | to the \fB\-verify\fR operation. | |
277 | .IP "\fB\-in filename\fR" 4 | |
278 | .IX Item "-in filename" | |
279 | the input message to be encrypted or signed or the message to be decrypted | |
280 | or verified. | |
281 | .IP "\fB\-inform SMIME|PEM|DER\fR" 4 | |
282 | .IX Item "-inform SMIME|PEM|DER" | |
283 | this specifies the input format for the \s-1CMS\s0 structure. The default | |
284 | is \fB\s-1SMIME\s0\fR which reads an S/MIME format message. \fB\s-1PEM\s0\fR and \fB\s-1DER\s0\fR | |
285 | format change this to expect \s-1PEM\s0 and \s-1DER\s0 format \s-1CMS\s0 structures | |
286 | instead. This currently only affects the input format of the \s-1CMS\s0 | |
287 | structure, if no \s-1CMS\s0 structure is being input (for example with | |
288 | \&\fB\-encrypt\fR or \fB\-sign\fR) this option has no effect. | |
289 | .IP "\fB\-rctform SMIME|PEM|DER\fR" 4 | |
290 | .IX Item "-rctform SMIME|PEM|DER" | |
291 | specify the format for a signed receipt for use with the \fB\-receipt_verify\fR | |
292 | operation. | |
293 | .IP "\fB\-out filename\fR" 4 | |
294 | .IX Item "-out filename" | |
295 | the message text that has been decrypted or verified or the output \s-1MIME\s0 | |
296 | format message that has been signed or verified. | |
297 | .IP "\fB\-outform SMIME|PEM|DER\fR" 4 | |
298 | .IX Item "-outform SMIME|PEM|DER" | |
299 | this specifies the output format for the \s-1CMS\s0 structure. The default | |
300 | is \fB\s-1SMIME\s0\fR which writes an S/MIME format message. \fB\s-1PEM\s0\fR and \fB\s-1DER\s0\fR | |
301 | format change this to write \s-1PEM\s0 and \s-1DER\s0 format \s-1CMS\s0 structures | |
302 | instead. This currently only affects the output format of the \s-1CMS\s0 | |
303 | structure, if no \s-1CMS\s0 structure is being output (for example with | |
304 | \&\fB\-verify\fR or \fB\-decrypt\fR) this option has no effect. | |
305 | .IP "\fB\-stream \-indef \-noindef\fR" 4 | |
306 | .IX Item "-stream -indef -noindef" | |
307 | the \fB\-stream\fR and \fB\-indef\fR options are equivalent and enable streaming I/O | |
308 | for encoding operations. This permits single pass processing of data without | |
309 | the need to hold the entire contents in memory, potentially supporting very | |
310 | large files. Streaming is automatically set for S/MIME signing with detached | |
311 | data if the output format is \fB\s-1SMIME\s0\fR it is currently off by default for all | |
312 | other operations. | |
313 | .IP "\fB\-noindef\fR" 4 | |
314 | .IX Item "-noindef" | |
315 | disable streaming I/O where it would produce and indefinite length constructed | |
316 | encoding. This option currently has no effect. In future streaming will be | |
317 | enabled by default on all relevant operations and this option will disable it. | |
318 | .IP "\fB\-content filename\fR" 4 | |
319 | .IX Item "-content filename" | |
320 | This specifies a file containing the detached content, this is only | |
321 | useful with the \fB\-verify\fR command. This is only usable if the \s-1CMS\s0 | |
322 | structure is using the detached signature form where the content is | |
323 | not included. This option will override any content if the input format | |
324 | is S/MIME and it uses the multipart/signed \s-1MIME\s0 content type. | |
325 | .IP "\fB\-text\fR" 4 | |
326 | .IX Item "-text" | |
327 | this option adds plain text (text/plain) \s-1MIME\s0 headers to the supplied | |
328 | message if encrypting or signing. If decrypting or verifying it strips | |
5a44c043 | 329 | off text headers: if the decrypted or verified message is not of \s-1MIME \s0 |
01185282 PA |
330 | type text/plain then an error occurs. |
331 | .IP "\fB\-noout\fR" 4 | |
332 | .IX Item "-noout" | |
333 | for the \fB\-cmsout\fR operation do not output the parsed \s-1CMS\s0 structure. This | |
334 | is useful when combined with the \fB\-print\fR option or if the syntax of the \s-1CMS\s0 | |
335 | structure is being checked. | |
336 | .IP "\fB\-print\fR" 4 | |
337 | .IX Item "-print" | |
338 | for the \fB\-cmsout\fR operation print out all fields of the \s-1CMS\s0 structure. This | |
339 | is mainly useful for testing purposes. | |
340 | .IP "\fB\-CAfile file\fR" 4 | |
341 | .IX Item "-CAfile file" | |
342 | a file containing trusted \s-1CA\s0 certificates, only used with \fB\-verify\fR. | |
343 | .IP "\fB\-CApath dir\fR" 4 | |
344 | .IX Item "-CApath dir" | |
345 | a directory containing trusted \s-1CA\s0 certificates, only used with | |
346 | \&\fB\-verify\fR. This directory must be a standard certificate directory: that | |
347 | is a hash of each subject name (using \fBx509 \-hash\fR) should be linked | |
348 | to each certificate. | |
349 | .IP "\fB\-md digest\fR" 4 | |
350 | .IX Item "-md digest" | |
351 | digest algorithm to use when signing or resigning. If not present then the | |
352 | default digest algorithm for the signing key will be used (usually \s-1SHA1\s0). | |
353 | .IP "\fB\-[cipher]\fR" 4 | |
354 | .IX Item "-[cipher]" | |
5a44c043 SW |
355 | the encryption algorithm to use. For example triple \s-1DES \s0(168 bits) \- \fB\-des3\fR |
356 | or 256 bit \s-1AES \- \s0\fB\-aes256\fR. Any standard algorithm name (as used by the | |
01185282 PA |
357 | \&\fIEVP_get_cipherbyname()\fR function) can also be used preceded by a dash, for |
358 | example \fB\-aes_128_cbc\fR. See \fBenc\fR for a list of ciphers | |
359 | supported by your version of OpenSSL. | |
360 | .Sp | |
361 | If not specified triple \s-1DES\s0 is used. Only used with \fB\-encrypt\fR and | |
362 | \&\fB\-EncryptedData_create\fR commands. | |
363 | .IP "\fB\-nointern\fR" 4 | |
364 | .IX Item "-nointern" | |
365 | when verifying a message normally certificates (if any) included in | |
366 | the message are searched for the signing certificate. With this option | |
367 | only the certificates specified in the \fB\-certfile\fR option are used. | |
368 | The supplied certificates can still be used as untrusted CAs however. | |
369 | .IP "\fB\-no_signer_cert_verify\fR" 4 | |
370 | .IX Item "-no_signer_cert_verify" | |
371 | do not verify the signers certificate of a signed message. | |
372 | .IP "\fB\-nocerts\fR" 4 | |
373 | .IX Item "-nocerts" | |
374 | when signing a message the signer's certificate is normally included | |
375 | with this option it is excluded. This will reduce the size of the | |
376 | signed message but the verifier must have a copy of the signers certificate | |
377 | available locally (passed using the \fB\-certfile\fR option for example). | |
378 | .IP "\fB\-noattr\fR" 4 | |
379 | .IX Item "-noattr" | |
380 | normally when a message is signed a set of attributes are included which | |
381 | include the signing time and supported symmetric algorithms. With this | |
382 | option they are not included. | |
383 | .IP "\fB\-nosmimecap\fR" 4 | |
384 | .IX Item "-nosmimecap" | |
385 | exclude the list of supported algorithms from signed attributes, other options | |
386 | such as signing time and content type are still included. | |
387 | .IP "\fB\-binary\fR" 4 | |
388 | .IX Item "-binary" | |
389 | normally the input message is converted to \*(L"canonical\*(R" format which is | |
390 | effectively using \s-1CR\s0 and \s-1LF\s0 as end of line: as required by the S/MIME | |
391 | specification. When this option is present no translation occurs. This | |
392 | is useful when handling binary data which may not be in \s-1MIME\s0 format. | |
393 | .IP "\fB\-nodetach\fR" 4 | |
394 | .IX Item "-nodetach" | |
395 | when signing a message use opaque signing: this form is more resistant | |
396 | to translation by mail relays but it cannot be read by mail agents that | |
397 | do not support S/MIME. Without this option cleartext signing with | |
398 | the \s-1MIME\s0 type multipart/signed is used. | |
399 | .IP "\fB\-certfile file\fR" 4 | |
400 | .IX Item "-certfile file" | |
401 | allows additional certificates to be specified. When signing these will | |
402 | be included with the message. When verifying these will be searched for | |
403 | the signers certificates. The certificates should be in \s-1PEM\s0 format. | |
404 | .IP "\fB\-certsout file\fR" 4 | |
405 | .IX Item "-certsout file" | |
406 | any certificates contained in the message are written to \fBfile\fR. | |
407 | .IP "\fB\-signer file\fR" 4 | |
408 | .IX Item "-signer file" | |
409 | a signing certificate when signing or resigning a message, this option can be | |
410 | used multiple times if more than one signer is required. If a message is being | |
411 | verified then the signers certificates will be written to this file if the | |
412 | verification was successful. | |
413 | .IP "\fB\-recip file\fR" 4 | |
414 | .IX Item "-recip file" | |
415 | the recipients certificate when decrypting a message. This certificate | |
416 | must match one of the recipients of the message or an error occurs. | |
417 | .IP "\fB\-keyid\fR" 4 | |
418 | .IX Item "-keyid" | |
419 | use subject key identifier to identify certificates instead of issuer name and | |
420 | serial number. The supplied certificate \fBmust\fR include a subject key | |
421 | identifier extension. Supported by \fB\-sign\fR and \fB\-encrypt\fR options. | |
422 | .IP "\fB\-receipt_request_all \-receipt_request_first\fR" 4 | |
423 | .IX Item "-receipt_request_all -receipt_request_first" | |
424 | for \fB\-sign\fR option include a signed receipt request. Indicate requests should | |
425 | be provided by all receipient or first tier recipients (those mailed directly | |
426 | and not from a mailing list). Ignored it \fB\-receipt_request_from\fR is included. | |
427 | .IP "\fB\-receipt_request_from emailaddress\fR" 4 | |
428 | .IX Item "-receipt_request_from emailaddress" | |
429 | for \fB\-sign\fR option include a signed receipt request. Add an explicit email | |
430 | address where receipts should be supplied. | |
431 | .IP "\fB\-receipt_request_to emailaddress\fR" 4 | |
432 | .IX Item "-receipt_request_to emailaddress" | |
433 | Add an explicit email address where signed receipts should be sent to. This | |
434 | option \fBmust\fR but supplied if a signed receipt it requested. | |
435 | .IP "\fB\-receipt_request_print\fR" 4 | |
436 | .IX Item "-receipt_request_print" | |
437 | For the \fB\-verify\fR operation print out the contents of any signed receipt | |
438 | requests. | |
439 | .IP "\fB\-secretkey key\fR" 4 | |
440 | .IX Item "-secretkey key" | |
441 | specify symmetric key to use. The key must be supplied in hex format and be | |
442 | consistent with the algorithm used. Supported by the \fB\-EncryptedData_encrypt\fR | |
443 | \&\fB\-EncrryptedData_decrypt\fR, \fB\-encrypt\fR and \fB\-decrypt\fR options. When used | |
444 | with \fB\-encrypt\fR or \fB\-decrypt\fR the supplied key is used to wrap or unwrap the | |
445 | content encryption key using an \s-1AES\s0 key in the \fBKEKRecipientInfo\fR type. | |
446 | .IP "\fB\-secretkeyid id\fR" 4 | |
447 | .IX Item "-secretkeyid id" | |
448 | the key identifier for the supplied symmetric key for \fBKEKRecipientInfo\fR type. | |
449 | This option \fBmust\fR be present if the \fB\-secretkey\fR option is used with | |
450 | \&\fB\-encrypt\fR. With \fB\-decrypt\fR operations the \fBid\fR is used to locate the | |
451 | relevant key if it is not supplied then an attempt is used to decrypt any | |
452 | \&\fBKEKRecipientInfo\fR structures. | |
453 | .IP "\fB\-econtent_type type\fR" 4 | |
454 | .IX Item "-econtent_type type" | |
455 | set the encapsulated content type to \fBtype\fR if not supplied the \fBData\fR type | |
456 | is used. The \fBtype\fR argument can be any valid \s-1OID\s0 name in either text or | |
457 | numerical format. | |
458 | .IP "\fB\-inkey file\fR" 4 | |
459 | .IX Item "-inkey file" | |
460 | the private key to use when signing or decrypting. This must match the | |
461 | corresponding certificate. If this option is not specified then the | |
462 | private key must be included in the certificate file specified with | |
463 | the \fB\-recip\fR or \fB\-signer\fR file. When signing this option can be used | |
464 | multiple times to specify successive keys. | |
465 | .IP "\fB\-passin arg\fR" 4 | |
466 | .IX Item "-passin arg" | |
467 | the private key password source. For more information about the format of \fBarg\fR | |
5a44c043 | 468 | see the \fB\s-1PASS PHRASE ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1). |
01185282 PA |
469 | .IP "\fB\-rand file(s)\fR" 4 |
470 | .IX Item "-rand file(s)" | |
471 | a file or files containing random data used to seed the random number | |
472 | generator, or an \s-1EGD\s0 socket (see \fIRAND_egd\fR\|(3)). | |
473 | Multiple files can be specified separated by a OS-dependent character. | |
474 | The separator is \fB;\fR for MS-Windows, \fB,\fR for OpenVMS, and \fB:\fR for | |
475 | all others. | |
476 | .IP "\fBcert.pem...\fR" 4 | |
477 | .IX Item "cert.pem..." | |
478 | one or more certificates of message recipients: used when encrypting | |
479 | a message. | |
480 | .IP "\fB\-to, \-from, \-subject\fR" 4 | |
481 | .IX Item "-to, -from, -subject" | |
482 | the relevant mail headers. These are included outside the signed | |
483 | portion of a message so they may be included manually. If signing | |
484 | then many S/MIME mail clients check the signers certificate's email | |
485 | address matches that specified in the From: address. | |
60096f03 SW |
486 | .IP "\fB\-purpose, \-ignore_critical, \-issuer_checks, \-crl_check, \-crl_check_all, \-policy_check, \-extended_crl, \-x509_strict, \-policy \-check_ss_sig \-no_alt_chains\fR" 4 |
487 | .IX Item "-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains" | |
01185282 PA |
488 | Set various certificate chain valiadition option. See the |
489 | \&\fBverify\fR manual page for details. | |
490 | .SH "NOTES" | |
491 | .IX Header "NOTES" | |
492 | The \s-1MIME\s0 message must be sent without any blank lines between the | |
493 | headers and the output. Some mail programs will automatically add | |
494 | a blank line. Piping the mail directly to sendmail is one way to | |
495 | achieve the correct format. | |
496 | .PP | |
497 | The supplied message to be signed or encrypted must include the | |
498 | necessary \s-1MIME\s0 headers or many S/MIME clients wont display it | |
499 | properly (if at all). You can use the \fB\-text\fR option to automatically | |
500 | add plain text headers. | |
501 | .PP | |
502 | A \*(L"signed and encrypted\*(R" message is one where a signed message is | |
503 | then encrypted. This can be produced by encrypting an already signed | |
504 | message: see the examples section. | |
505 | .PP | |
506 | This version of the program only allows one signer per message but it | |
507 | will verify multiple signers on received messages. Some S/MIME clients | |
508 | choke if a message contains multiple signers. It is possible to sign | |
509 | messages \*(L"in parallel\*(R" by signing an already signed message. | |
510 | .PP | |
511 | The options \fB\-encrypt\fR and \fB\-decrypt\fR reflect common usage in S/MIME | |
512 | clients. Strictly speaking these process \s-1CMS\s0 enveloped data: \s-1CMS\s0 | |
513 | encrypted data is used for other purposes. | |
514 | .PP | |
515 | The \fB\-resign\fR option uses an existing message digest when adding a new | |
516 | signer. This means that attributes must be present in at least one existing | |
517 | signer using the same message digest or this operation will fail. | |
518 | .PP | |
519 | The \fB\-stream\fR and \fB\-indef\fR options enable experimental streaming I/O support. | |
520 | As a result the encoding is \s-1BER\s0 using indefinite length constructed encoding | |
5a44c043 | 521 | and no longer \s-1DER.\s0 Streaming is supported for the \fB\-encrypt\fR operation and the |
01185282 PA |
522 | \&\fB\-sign\fR operation if the content is not detached. |
523 | .PP | |
524 | Streaming is always used for the \fB\-sign\fR operation with detached data but | |
525 | since the content is no longer part of the \s-1CMS\s0 structure the encoding | |
5a44c043 | 526 | remains \s-1DER.\s0 |
34240b21 SW |
527 | .PP |
528 | If the \fB\-decrypt\fR option is used without a recipient certificate then an | |
529 | attempt is made to locate the recipient by trying each potential recipient | |
530 | in turn using the supplied private key. To thwart the \s-1MMA\s0 attack | |
531 | (Bleichenbacher's attack on \s-1PKCS\s0 #1 v1.5 \s-1RSA\s0 padding) all recipients are | |
532 | tried whether they succeed or not and if no recipients match the message | |
533 | is \*(L"decrypted\*(R" using a random key which will typically output garbage. | |
534 | The \fB\-debug_decrypt\fR option can be used to disable the \s-1MMA\s0 attack protection | |
535 | and return an error if no recipient can be found: this option should be used | |
536 | with caution. For a fuller description see \fICMS_decrypt\fR\|(3)). | |
01185282 PA |
537 | .SH "EXIT CODES" |
538 | .IX Header "EXIT CODES" | |
539 | .IP "0" 4 | |
540 | the operation was completely successfully. | |
541 | .IP "1" 4 | |
542 | .IX Item "1" | |
543 | an error occurred parsing the command options. | |
544 | .IP "2" 4 | |
545 | .IX Item "2" | |
546 | one of the input files could not be read. | |
547 | .IP "3" 4 | |
548 | .IX Item "3" | |
549 | an error occurred creating the \s-1CMS\s0 file or when reading the \s-1MIME\s0 | |
550 | message. | |
551 | .IP "4" 4 | |
552 | .IX Item "4" | |
553 | an error occurred decrypting or verifying the message. | |
554 | .IP "5" 4 | |
555 | .IX Item "5" | |
556 | the message was verified correctly but an error occurred writing out | |
557 | the signers certificates. | |
558 | .SH "COMPATIBILITY WITH PKCS#7 format." | |
559 | .IX Header "COMPATIBILITY WITH PKCS#7 format." | |
560 | The \fBsmime\fR utility can only process the older \fBPKCS#7\fR format. The \fBcms\fR | |
561 | utility supports Cryptographic Message Syntax format. Use of some features | |
562 | will result in messages which cannot be processed by applications which only | |
563 | support the older format. These are detailed below. | |
564 | .PP | |
565 | The use of the \fB\-keyid\fR option with \fB\-sign\fR or \fB\-encrypt\fR. | |
566 | .PP | |
567 | The \fB\-outform \s-1PEM\s0\fR option uses different headers. | |
568 | .PP | |
569 | The \fB\-compress\fR option. | |
570 | .PP | |
571 | The \fB\-secretkey\fR option when used with \fB\-encrypt\fR. | |
572 | .PP | |
573 | Additionally the \fB\-EncryptedData_create\fR and \fB\-data_create\fR type cannot | |
574 | be processed by the older \fBsmime\fR command. | |
575 | .SH "EXAMPLES" | |
576 | .IX Header "EXAMPLES" | |
577 | Create a cleartext signed message: | |
578 | .PP | |
579 | .Vb 2 | |
580 | \& openssl cms \-sign \-in message.txt \-text \-out mail.msg \e | |
581 | \& \-signer mycert.pem | |
582 | .Ve | |
583 | .PP | |
584 | Create an opaque signed message | |
585 | .PP | |
586 | .Vb 2 | |
587 | \& openssl cms \-sign \-in message.txt \-text \-out mail.msg \-nodetach \e | |
588 | \& \-signer mycert.pem | |
589 | .Ve | |
590 | .PP | |
591 | Create a signed message, include some additional certificates and | |
592 | read the private key from another file: | |
593 | .PP | |
594 | .Vb 2 | |
595 | \& openssl cms \-sign \-in in.txt \-text \-out mail.msg \e | |
596 | \& \-signer mycert.pem \-inkey mykey.pem \-certfile mycerts.pem | |
597 | .Ve | |
598 | .PP | |
599 | Create a signed message with two signers, use key identifier: | |
600 | .PP | |
601 | .Vb 2 | |
602 | \& openssl cms \-sign \-in message.txt \-text \-out mail.msg \e | |
603 | \& \-signer mycert.pem \-signer othercert.pem \-keyid | |
604 | .Ve | |
605 | .PP | |
606 | Send a signed message under Unix directly to sendmail, including headers: | |
607 | .PP | |
608 | .Vb 3 | |
609 | \& openssl cms \-sign \-in in.txt \-text \-signer mycert.pem \e | |
610 | \& \-from steve@openssl.org \-to someone@somewhere \e | |
611 | \& \-subject "Signed message" | sendmail someone@somewhere | |
612 | .Ve | |
613 | .PP | |
614 | Verify a message and extract the signer's certificate if successful: | |
615 | .PP | |
616 | .Vb 1 | |
617 | \& openssl cms \-verify \-in mail.msg \-signer user.pem \-out signedtext.txt | |
618 | .Ve | |
619 | .PP | |
620 | Send encrypted mail using triple \s-1DES:\s0 | |
621 | .PP | |
622 | .Vb 3 | |
623 | \& openssl cms \-encrypt \-in in.txt \-from steve@openssl.org \e | |
624 | \& \-to someone@somewhere \-subject "Encrypted message" \e | |
625 | \& \-des3 user.pem \-out mail.msg | |
626 | .Ve | |
627 | .PP | |
628 | Sign and encrypt mail: | |
629 | .PP | |
630 | .Vb 4 | |
631 | \& openssl cms \-sign \-in ml.txt \-signer my.pem \-text \e | |
632 | \& | openssl cms \-encrypt \-out mail.msg \e | |
633 | \& \-from steve@openssl.org \-to someone@somewhere \e | |
634 | \& \-subject "Signed and Encrypted message" \-des3 user.pem | |
635 | .Ve | |
636 | .PP | |
637 | Note: the encryption command does not include the \fB\-text\fR option because the | |
638 | message being encrypted already has \s-1MIME\s0 headers. | |
639 | .PP | |
640 | Decrypt mail: | |
641 | .PP | |
642 | .Vb 1 | |
643 | \& openssl cms \-decrypt \-in mail.msg \-recip mycert.pem \-inkey key.pem | |
644 | .Ve | |
645 | .PP | |
646 | The output from Netscape form signing is a PKCS#7 structure with the | |
647 | detached signature format. You can use this program to verify the | |
648 | signature by line wrapping the base64 encoded structure and surrounding | |
649 | it with: | |
650 | .PP | |
651 | .Vb 2 | |
652 | \& \-\-\-\-\-BEGIN PKCS7\-\-\-\-\- | |
653 | \& \-\-\-\-\-END PKCS7\-\-\-\-\- | |
654 | .Ve | |
655 | .PP | |
656 | and using the command, | |
657 | .PP | |
658 | .Vb 1 | |
659 | \& openssl cms \-verify \-inform PEM \-in signature.pem \-content content.txt | |
660 | .Ve | |
661 | .PP | |
662 | alternatively you can base64 decode the signature and use | |
663 | .PP | |
664 | .Vb 1 | |
665 | \& openssl cms \-verify \-inform DER \-in signature.der \-content content.txt | |
666 | .Ve | |
667 | .PP | |
668 | Create an encrypted message using 128 bit Camellia: | |
669 | .PP | |
670 | .Vb 1 | |
671 | \& openssl cms \-encrypt \-in plain.txt \-camellia128 \-out mail.msg cert.pem | |
672 | .Ve | |
673 | .PP | |
674 | Add a signer to an existing message: | |
675 | .PP | |
676 | .Vb 1 | |
677 | \& openssl cms \-resign \-in mail.msg \-signer newsign.pem \-out mail2.msg | |
678 | .Ve | |
679 | .SH "BUGS" | |
680 | .IX Header "BUGS" | |
681 | The \s-1MIME\s0 parser isn't very clever: it seems to handle most messages that I've | |
682 | thrown at it but it may choke on others. | |
683 | .PP | |
684 | The code currently will only write out the signer's certificate to a file: if | |
685 | the signer has a separate encryption certificate this must be manually | |
686 | extracted. There should be some heuristic that determines the correct | |
687 | encryption certificate. | |
688 | .PP | |
689 | Ideally a database should be maintained of a certificates for each email | |
690 | address. | |
691 | .PP | |
692 | The code doesn't currently take note of the permitted symmetric encryption | |
693 | algorithms as supplied in the SMIMECapabilities signed attribute. this means the | |
694 | user has to manually include the correct encryption algorithm. It should store | |
695 | the list of permitted ciphers in a database and only use those. | |
696 | .PP | |
697 | No revocation checking is done on the signer's certificate. | |
698 | .SH "HISTORY" | |
699 | .IX Header "HISTORY" | |
700 | The use of multiple \fB\-signer\fR options and the \fB\-resign\fR command were first | |
701 | added in OpenSSL 1.0.0 | |
60096f03 SW |
702 | .PP |
703 | The \-no_alt_chains options was first added to OpenSSL 1.0.1n and 1.0.2b. |