]>
Commit | Line | Data |
---|---|---|
aba3e65f DSH |
1 | |
2 | =pod | |
3 | ||
4 | =head1 NAME | |
5 | ||
6 | x509 - Certificate display and signing utility | |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | B<openssl> B<x509> | |
11 | [B<-inform DER|PEM|NET>] | |
12 | [B<-outform DER|PEM|NET>] | |
13 | [B<-keyform DER|PEM>] | |
14 | [B<-CAform DER|PEM>] | |
15 | [B<-CAkeyform DER|PEM>] | |
16 | [B<-in filename>] | |
17 | [B<-out filename>] | |
18 | [B<-serial>] | |
19 | [B<-hash>] | |
20 | [B<-subject>] | |
21 | [B<-issuer>] | |
22 | [B<-startdate>] | |
23 | [B<-enddate>] | |
24 | [B<-purpose>] | |
25 | [B<-dates>] | |
26 | [B<-modulus>] | |
27 | [B<-fingerprint>] | |
28 | [B<-alias>] | |
29 | [B<-noout>] | |
30 | [B<-trustout>] | |
31 | [B<-clrtrust>] | |
9868232a | 32 | [B<-clrreject>] |
aba3e65f | 33 | [B<-addtrust arg>] |
9868232a | 34 | [B<-addreject arg>] |
aba3e65f DSH |
35 | [B<-setalias arg>] |
36 | [B<-days arg>] | |
37 | [B<-signkey filename>] | |
38 | [B<-x509toreq>] | |
39 | [B<-req>] | |
40 | [B<-CA filename>] | |
41 | [B<-CAkey filename>] | |
42 | [B<-CAcreateserial>] | |
43 | [B<-CAserial filename>] | |
44 | [B<-text>] | |
45 | [B<-C>] | |
46 | [B<-md2|-md5|-sha1|-mdc2>] | |
47 | [B<-clrext>] | |
48 | [B<-extfile filename>] | |
49 | [B<-extensions section>] | |
50 | ||
51 | =head1 DESCRIPTION | |
52 | ||
53 | The B<x509> command is a multi purpose certificate utility. It can be | |
54 | used to display certificate information, convert certificates to | |
55 | various forms, sign certificate requests like a "mini CA" or edit | |
56 | certificate trust settings. | |
57 | ||
58 | Since there are a large number of options they will split up into | |
59 | various sections. | |
60 | ||
61 | ||
9868232a | 62 | =head1 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS |
aba3e65f DSH |
63 | |
64 | =over 4 | |
65 | ||
66 | =item B<-inform DER|PEM|NET> | |
67 | ||
68 | This specifies the input format normally the command will expect an X509 | |
69 | certificate but this can change if other options such as B<-req> are | |
70 | present. The DER format is the DER encoding of the certificate and PEM | |
71 | is the base64 encoding of the DER encoding with header and footer lines | |
72 | added. The NET option is an obscure Netscape server format that is now | |
73 | obsolete. | |
74 | ||
75 | =item B<-outform DER|PEM|NET> | |
76 | ||
77 | This specifies the output format, the options have the same meaning as the | |
78 | B<-inform> option. | |
79 | ||
80 | =item B<-in filename> | |
81 | ||
82 | This specifies the input filename to read a certificate from or standard input | |
83 | if this option is not specified. | |
84 | ||
85 | =item B<-out filename> | |
86 | ||
87 | This specifies the output filename to write to or standard output by | |
88 | default. | |
89 | ||
9868232a DSH |
90 | =item B<-md2|-md5|-sha1|-mdc2> |
91 | ||
92 | the digest to use. This affects any signing or display option that uses a message | |
93 | digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. If not | |
94 | specified then MD5 is used. If the key being used to sign with is a DSA key then | |
95 | this option has no effect: SHA1 is always used with DSA keys. | |
96 | ||
97 | ||
aba3e65f DSH |
98 | =back |
99 | ||
100 | =head1 DISPLAY OPTIONS | |
101 | ||
102 | Note: the B<-alias> and B<-purpose> options are also display options | |
103 | but are desribed in the B<TRUST OPTIONS> section. | |
104 | ||
105 | =over 4 | |
106 | ||
107 | =item B<-text> | |
108 | ||
109 | prints out the certificate in text form. Full details are output including the | |
110 | public key, signature algorithms, issuer and subject names, serial number | |
111 | any extensions present and any trust settings. | |
112 | ||
113 | =item B<-noout> | |
114 | ||
115 | this option prevents output of the encoded version of the request. | |
116 | ||
117 | =item B<-modulus> | |
118 | ||
119 | this option prints out the value of the modulus of the public key | |
120 | contained in the certificate. | |
121 | ||
122 | =item B<-serial> | |
123 | ||
124 | outputs the certificate serial number. | |
125 | ||
126 | =item B<-hash> | |
127 | ||
938ead8f DSH |
128 | outputs the "hash" of the certificate subject name. This is used in OpenSSL to |
129 | form an index to allow certificates in a directory to be looked up by subject | |
aba3e65f DSH |
130 | name. |
131 | ||
132 | =item B<-subject> | |
133 | ||
134 | outputs the subject name. | |
135 | ||
136 | =item B<-issuer> | |
137 | ||
138 | outputs the issuer name. | |
139 | ||
140 | =item B<-startdate> | |
141 | ||
142 | prints out the start date of the certificate, that is the notBefore date. | |
143 | ||
144 | =item B<-enddate> | |
145 | ||
146 | prints out the expiry date of the certificate, that is the notAfter date. | |
147 | ||
148 | =item B<-dates> | |
149 | ||
150 | prints out the start and expiry dates of a certificate. | |
151 | ||
152 | =item B<-fingerprint> | |
153 | ||
9868232a | 154 | prints out the digest of the DER encoded version of the whole certificate. |
aba3e65f DSH |
155 | |
156 | =item B<-C> | |
157 | ||
158 | this outputs the certificate in the form of a C source file. | |
159 | ||
160 | =back | |
161 | ||
162 | =head1 TRUST SETTINGS | |
163 | ||
164 | Please note these options are currently experimental and may well change. | |
165 | ||
166 | A B<trusted certificate> is an ordinary certificate which has several | |
167 | additional pieces of information attached to it such as the permitted | |
168 | and prohibited uses of the certificate and an "alias". | |
169 | ||
170 | Normally when a certificate is being verified at least one certificate | |
171 | must be "trusted". By default a trusted certificate must be stored | |
172 | locally and must be a root CA: any certificate chain ending in this CA | |
173 | is then usable for any purpose. | |
174 | ||
175 | Adding trust settings modifies this behaviour: if a certificate is being | |
176 | verified and one of the certificate chain is marked as trusted for that | |
177 | specific purpose then the verify succeeds without looking up any more | |
178 | certificates. Similarly if the use is prohibited then the certificate | |
179 | is automatically rejected. If a purpose is neither permitted nor prohibited | |
180 | then the certificate extensions are checked for consistency with the required | |
181 | purpose and the process continues. | |
182 | ||
183 | If a root CA is reached then it must be marked as trusted for the required | |
184 | purpose or the verify fails. | |
185 | ||
186 | See the description of the B<verify> utility for more information on the | |
187 | meaning of trust settings. | |
188 | ||
189 | =over 4 | |
190 | ||
191 | =item B<-trustout> | |
192 | ||
193 | this causes B<x509> to output a B<trusted> certificate. An ordinary | |
194 | or trusted certificate can be input but by default an ordinary | |
195 | certificate is output and any trust settings are discarded. With the | |
196 | B<-trustout> option a trusted certificate is output. A trusted | |
197 | certificate is automatically output if any trust settings are modified. | |
198 | ||
199 | =item B<-setalias arg> | |
200 | ||
201 | sets the alias of the certificate. This will allow the certificate | |
202 | to be reffered to using a nickname for example "Steve's Certificate". | |
203 | ||
204 | =item B<-alias> | |
205 | ||
206 | outputs the certificate alias, if any. | |
207 | ||
208 | =item B<-clrtrust> | |
209 | ||
210 | clears all the permitted or trusted uses of the certificate. | |
211 | ||
9868232a | 212 | =item B<-clrreject> |
aba3e65f DSH |
213 | |
214 | clears all the prohibited or untrusted uses of the certificate. | |
215 | ||
216 | =item B<-addtrust arg> | |
217 | ||
218 | adds a trusted certificate use. Currently acceptable values | |
219 | are all (any purpose), sslclient (SSL client use), sslserver | |
220 | (SSL server use) email (S/MIME email) and objsign (Object signing). | |
221 | ||
9868232a | 222 | =item B<-addreject arg> |
aba3e65f DSH |
223 | |
224 | adds a prohibited use. It accepts the same values as the B<-addtrust> | |
225 | option. | |
226 | ||
227 | =item B<-purpose> | |
228 | ||
229 | this option performs tests on the certificate extensions and outputs | |
230 | the results. It checks to see if the certificate can be used as an | |
231 | end user or CA certificate for various purposes. Since many commercial | |
232 | certificates have invalid extensions it is possible that warnings will | |
233 | be output for some certificates. Known problems have work arounds added. | |
234 | ||
235 | =back | |
236 | ||
237 | =head1 SIGNING OPTIONS | |
238 | ||
239 | The B<x509> utility can be used to sign certificates and requests: it | |
240 | can thus behave like a "mini CA". | |
241 | ||
242 | =over 4 | |
243 | ||
244 | =item B<-signkey filename> | |
245 | ||
246 | this option causes the input file to be self signed using the supplied | |
247 | private key. | |
248 | ||
249 | If the input file is a certificate it sets the issuer name to the | |
250 | subject name (i.e. makes it self signed) changes the public key to the | |
251 | supplied value and changes the start and end dates. The start date is | |
252 | set to the current time and the end date is set to a value determined | |
253 | by the B<-days> option. Any certificate extensions are retained unless | |
254 | the B<-clrext> option is supplied. | |
255 | ||
256 | If the input is a certificate request then a self signed certificate | |
257 | is created using the supplied private key using the subject name in | |
258 | the request. | |
259 | ||
260 | =item B<-clrext> | |
261 | ||
262 | delete any extensions from a certificate. This option is used when a | |
263 | certificate is being created from another certificate (for example with | |
264 | the B<-signkey> or the B<-CA> options). Normally all extensions are | |
265 | retained. | |
266 | ||
267 | =item B<-keyform PEM|DER> | |
268 | ||
269 | specifies the format (DER or PEM) of the private key file used in the | |
270 | B<-signkey> option. | |
271 | ||
272 | =item B<-days arg> | |
273 | ||
274 | specifies the number of days to make a certificate valid for. The default | |
275 | is 30 days. | |
276 | ||
277 | =item B<-x509toreq> | |
278 | ||
279 | converts a certificate into a certificate request. The B<-signkey> option | |
280 | is used to pass the required private key. | |
281 | ||
282 | =item B<-req> | |
283 | ||
284 | by default a certificate is expected on input. With this option a | |
285 | certificate request is expected instead. | |
286 | ||
287 | =item B<-CA filename> | |
288 | ||
289 | specifies the CA certificate to be used for signing. When this option is | |
290 | present B<x509> behaves like a "mini CA". The input file is signed by this | |
291 | CA using this option: that is its issuer name is set to the subject name | |
292 | of the CA and it is digitally signed using the CAs private key. | |
293 | ||
294 | This option is normally combined with the B<-req> option. Without the | |
295 | B<-req> option the input is a certificate which must be self signed. | |
296 | ||
297 | =item B<-CAkey filename> | |
298 | ||
299 | sets the CA private key to sign a certificate with. If this option is | |
300 | not specified then it is assumed that the CA private key is present in | |
301 | the CA certificate file. | |
302 | ||
303 | =item B<-CAserial filename> | |
304 | ||
305 | sets the CA serial number file to use. | |
306 | ||
307 | When the B<-CA> option is used to sign a certificate it uses a serial | |
308 | number specified in a file. This file consist of one line containing | |
309 | an even number of hex digits with the serial number to use. After each | |
310 | use the serial number is incremented and written out to the file again. | |
311 | ||
312 | The default filename consists of the CA certificate file base name with | |
313 | ".srl" appended. For example if the CA certificate file is called | |
314 | "mycacert.pem" it expects to find a serial number file called "mycacert.srl". | |
315 | ||
316 | =item B<-CAcreateserial filename> | |
317 | ||
318 | with this option the CA serial number file is created if it does not exist: | |
319 | it will contain the serial number "01". Normally if the B<-CA> option is | |
320 | specified and the serial number file does not exist it is an error. | |
321 | ||
aba3e65f DSH |
322 | =item B<-extfile filename> |
323 | ||
324 | file containing certificate extensions to use. If not specified then | |
325 | no extensions are added to the certificate. | |
326 | ||
327 | =item B<-extensions section> | |
328 | ||
329 | the section to add certificate extensions from. If this option is not | |
330 | specified then the extensions should either be contained in the unnamed | |
331 | (default) section or the default section should contain a variable called | |
332 | "extensions" which contains the section to use. | |
333 | ||
334 | =back | |
335 | ||
336 | =head1 EXAMPLES | |
337 | ||
338 | Note: in these examples the '\' means the example should be all on one | |
339 | line. | |
340 | ||
341 | Display the contents of a certificate: | |
342 | ||
343 | openssl x509 -in cert.pem -noout -text | |
344 | ||
9868232a | 345 | Display the certificate serial number: |
aba3e65f DSH |
346 | |
347 | openssl x509 -in cert.pem -noout -serial | |
348 | ||
9868232a DSH |
349 | Display the certificate MD5 fingerprint: |
350 | ||
351 | openssl x509 -in cert.pem -noout -fingerprint | |
352 | ||
353 | Display the certificate SHA1 fingerprint: | |
354 | ||
355 | openssl x509 -sha1 -in cert.pem -noout -fingerprint | |
aba3e65f DSH |
356 | |
357 | Convert a certificate from PEM to DER format: | |
358 | ||
359 | openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER | |
360 | ||
361 | Convert a certificate to a certificate request: | |
362 | ||
363 | openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem | |
364 | ||
365 | Convert a certificate request into a self signed certificate using | |
366 | extensions for a CA: | |
367 | ||
368 | openssl x509 -req -in careq.pem -config openssl.cnf -extensions v3_ca \ | |
369 | -signkey key.pem -out cacert.pem | |
370 | ||
371 | Sign a certificate request using the CA certifcate above and add user | |
372 | certificate extensions: | |
373 | ||
374 | openssl x509 -req -in req.pem -config openssl.cnf -extensions v3_usr \ | |
375 | -CA cacert.pem -CAkey key.pem -CAcreateserial | |
376 | ||
377 | ||
378 | Set a certificate to be trusted for SSL client use and change set its alias to | |
379 | "Steve's Class 1 CA" | |
380 | ||
381 | openssl x509 -in cert.pem -addtrust sslclient \ | |
382 | -alias "Steve's Class 1 CA" -out trust.pem | |
383 | ||
0286d944 DSH |
384 | =head1 NOTES |
385 | ||
386 | The PEM format uses the header and footer lines: | |
387 | ||
388 | -----BEGIN CERTIFICATE---- | |
389 | -----END CERTIFICATE---- | |
390 | ||
391 | it will also handle files containing: | |
392 | ||
393 | -----BEGIN X509 CERTIFICATE---- | |
394 | -----END X509 CERTIFICATE---- | |
395 | ||
9868232a DSH |
396 | Trusted certificates have the lines |
397 | ||
398 | -----BEGIN TRUSTED CERTIFICATE---- | |
399 | -----END TRUSTED CERTIFICATE---- | |
400 | ||
401 | The B<-fingerprint> option takes the digest of the DER encoded certificate. | |
402 | This is commonly called a "fingerprint". Because of the nature of message | |
403 | digests the fingerprint of a certificate is unique to that certificate and | |
404 | two certificates with the same fingerprint can be considered to be the same. | |
405 | ||
406 | The Netscape fingerprint uses MD5 whereas MSIE uses SHA1. | |
407 | ||
aba3e65f DSH |
408 | =head1 BUGS |
409 | ||
410 | The way DNs are printed is in a "historical SSLeay" format which doesn't | |
411 | follow any published standard. It should follow some standard like RFC2253 | |
412 | or RFC1779 with options to make the stuff more readable. | |
413 | ||
414 | Extensions in certificates are not transferred to certificate requests and | |
415 | vice versa. | |
416 | ||
417 | It is possible to produce invalid certificates or requests by specifying the | |
418 | wrong private key or using inconsistent options in some cases: these should | |
419 | be checked. | |
420 | ||
9868232a | 421 | There should be options to explicitly set such things as start and end |
aba3e65f DSH |
422 | dates rather than an offset from the current time. |
423 | ||
424 | The code to implement the verify behaviour described in the B<TRUST SETTINGS> | |
425 | is currently being developed. It thus describes the intended behavior rather | |
426 | than the current behaviour. It is hoped that it will represent reality in | |
427 | OpenSSL 0.9.5 and later. | |
428 | ||
aba3e65f DSH |
429 | =head1 SEE ALSO |
430 | ||
431 | req(1), ca(1), genrsa(1), gendsa(1) | |
432 | ||
433 | =cut |