Update per latest manual pages after 'man-update'.
[dragonfly.git] / secure / usr.bin / openssl / man / x509.1
1 .rn '' }`
2 ''' $RCSfile$$Revision$$Date$
3 '''
4 ''' $Log$
5 '''
6 .de Sh
7 .br
8 .if t .Sp
9 .ne 5
10 .PP
11 \fB\\$1\fR
12 .PP
13 ..
14 .de Sp
15 .if t .sp .5v
16 .if n .sp
17 ..
18 .de Ip
19 .br
20 .ie \\n(.$>=3 .ne \\$3
21 .el .ne 3
22 .IP "\\$1" \\$2
23 ..
24 .de Vb
25 .ft CW
26 .nf
27 .ne \\$1
28 ..
29 .de Ve
30 .ft R
31
32 .fi
33 ..
34 '''
35 '''
36 '''     Set up \*(-- to give an unbreakable dash;
37 '''     string Tr holds user defined translation string.
38 '''     Bell System Logo is used as a dummy character.
39 '''
40 .tr \(*W-|\(bv\*(Tr
41 .ie n \{\
42 .ds -- \(*W-
43 .ds PI pi
44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46 .ds L" ""
47 .ds R" ""
48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
50 '''   such as .IP and .SH, which do another additional levels of
51 '''   double-quote interpretation
52 .ds M" """
53 .ds S" """
54 .ds N" """""
55 .ds T" """""
56 .ds L' '
57 .ds R' '
58 .ds M' '
59 .ds S' '
60 .ds N' '
61 .ds T' '
62 'br\}
63 .el\{\
64 .ds -- \(em\|
65 .tr \*(Tr
66 .ds L" ``
67 .ds R" ''
68 .ds M" ``
69 .ds S" ''
70 .ds N" ``
71 .ds T" ''
72 .ds L' `
73 .ds R' '
74 .ds M' `
75 .ds S' '
76 .ds N' `
77 .ds T' '
78 .ds PI \(*p
79 'br\}
80 .\"     If the F register is turned on, we'll generate
81 .\"     index entries out stderr for the following things:
82 .\"             TH      Title 
83 .\"             SH      Header
84 .\"             Sh      Subsection 
85 .\"             Ip      Item
86 .\"             X<>     Xref  (embedded
87 .\"     Of course, you have to process the output yourself
88 .\"     in some meaninful fashion.
89 .if \nF \{
90 .de IX
91 .tm Index:\\$1\t\\n%\t"\\$2"
92 ..
93 .nr % 0
94 .rr F
95 .\}
96 .TH X509 1 "0.9.7d" "2/Sep/2004" "OpenSSL"
97 .UC
98 .if n .hy 0
99 .if n .na
100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101 .de CQ          \" put $1 in typewriter font
102 .ft CW
103 'if n "\c
104 'if t \\&\\$1\c
105 'if n \\&\\$1\c
106 'if n \&"
107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108 '.ft R
109 ..
110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111 .       \" AM - accent mark definitions
112 .bd B 3
113 .       \" fudge factors for nroff and troff
114 .if n \{\
115 .       ds #H 0
116 .       ds #V .8m
117 .       ds #F .3m
118 .       ds #[ \f1
119 .       ds #] \fP
120 .\}
121 .if t \{\
122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123 .       ds #V .6m
124 .       ds #F 0
125 .       ds #[ \&
126 .       ds #] \&
127 .\}
128 .       \" simple accents for nroff and troff
129 .if n \{\
130 .       ds ' \&
131 .       ds ` \&
132 .       ds ^ \&
133 .       ds , \&
134 .       ds ~ ~
135 .       ds ? ?
136 .       ds ! !
137 .       ds /
138 .       ds q
139 .\}
140 .if t \{\
141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
150 .\}
151 .       \" troff and (daisy-wheel) nroff accents
152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163 .ds ae a\h'-(\w'a'u*4/10)'e
164 .ds Ae A\h'-(\w'A'u*4/10)'E
165 .ds oe o\h'-(\w'o'u*4/10)'e
166 .ds Oe O\h'-(\w'O'u*4/10)'E
167 .       \" corrections for vroff
168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
170 .       \" for low resolution devices (crt and lpr)
171 .if \n(.H>23 .if \n(.V>19 \
172 \{\
173 .       ds : e
174 .       ds 8 ss
175 .       ds v \h'-1'\o'\(aa\(ga'
176 .       ds _ \h'-1'^
177 .       ds . \h'-1'.
178 .       ds 3 3
179 .       ds o a
180 .       ds d- d\h'-1'\(ga
181 .       ds D- D\h'-1'\(hy
182 .       ds th \o'bp'
183 .       ds Th \o'LP'
184 .       ds ae ae
185 .       ds Ae AE
186 .       ds oe oe
187 .       ds Oe OE
188 .\}
189 .rm #[ #] #H #V #F C
190 .SH "NAME"
191 x509 \- Certificate display and signing utility
192 .SH "SYNOPSIS"
193 \fBopenssl\fR \fBx509\fR
194 [\fB\-inform DER|PEM|NET\fR]
195 [\fB\-outform DER|PEM|NET\fR]
196 [\fB\-keyform DER|PEM\fR]
197 [\fB\-CAform DER|PEM\fR]
198 [\fB\-CAkeyform DER|PEM\fR]
199 [\fB\-in filename\fR]
200 [\fB\-out filename\fR]
201 [\fB\-serial\fR]
202 [\fB\-hash\fR]
203 [\fB\-subject\fR]
204 [\fB\-issuer\fR]
205 [\fB\-nameopt option\fR]
206 [\fB\-email\fR]
207 [\fB\-startdate\fR]
208 [\fB\-enddate\fR]
209 [\fB\-purpose\fR]
210 [\fB\-dates\fR]
211 [\fB\-modulus\fR]
212 [\fB\-fingerprint\fR]
213 [\fB\-alias\fR]
214 [\fB\-noout\fR]
215 [\fB\-trustout\fR]
216 [\fB\-clrtrust\fR]
217 [\fB\-clrreject\fR]
218 [\fB\-addtrust arg\fR]
219 [\fB\-addreject arg\fR]
220 [\fB\-setalias arg\fR]
221 [\fB\-days arg\fR]
222 [\fB\-set_serial n\fR]
223 [\fB\-signkey filename\fR]
224 [\fB\-x509toreq\fR]
225 [\fB\-req\fR]
226 [\fB\-CA filename\fR]
227 [\fB\-CAkey filename\fR]
228 [\fB\-CAcreateserial\fR]
229 [\fB\-CAserial filename\fR]
230 [\fB\-text\fR]
231 [\fB\-C\fR]
232 [\fB\-md2|\-md5|\-sha1|\-mdc2\fR]
233 [\fB\-clrext\fR]
234 [\fB\-extfile filename\fR]
235 [\fB\-extensions section\fR]
236 [\fB\-engine id\fR]
237 .SH "DESCRIPTION"
238 The \fBx509\fR command is a multi purpose certificate utility. It can be
239 used to display certificate information, convert certificates to
240 various forms, sign certificate requests like a \*(L"mini CA\*(R" or edit
241 certificate trust settings.
242 .PP
243 Since there are a large number of options they will split up into
244 various sections.
245 .SH "OPTIONS"
246 .Sh "\s-1INPUT\s0, \s-1OUTPUT\s0 \s-1AND\s0 \s-1GENERAL\s0 \s-1PURPOSE\s0 \s-1OPTIONS\s0"
247 .Ip "\fB\-inform \s-1DER\s0|\s-1PEM\s0|\s-1NET\s0\fR" 4
248 This specifies the input format normally the command will expect an X509
249 certificate but this can change if other options such as \fB\-req\fR are
250 present. The \s-1DER\s0 format is the \s-1DER\s0 encoding of the certificate and \s-1PEM\s0
251 is the base64 encoding of the \s-1DER\s0 encoding with header and footer lines
252 added. The \s-1NET\s0 option is an obscure Netscape server format that is now
253 obsolete.
254 .Ip "\fB\-outform \s-1DER\s0|\s-1PEM\s0|\s-1NET\s0\fR" 4
255 This specifies the output format, the options have the same meaning as the 
256 \fB\-inform\fR option.
257 .Ip "\fB\-in filename\fR" 4
258 This specifies the input filename to read a certificate from or standard input
259 if this option is not specified.
260 .Ip "\fB\-out filename\fR" 4
261 This specifies the output filename to write to or standard output by
262 default.
263 .Ip "\fB\-md2|\-md5|\-sha1|\-mdc2\fR" 4
264 the digest to use. This affects any signing or display option that uses a message
265 digest, such as the \fB\-fingerprint\fR, \fB\-signkey\fR and \fB\-\s-1CA\s0\fR options. If not
266 specified then \s-1MD5\s0 is used. If the key being used to sign with is a \s-1DSA\s0 key then
267 this option has no effect: \s-1SHA1\s0 is always used with \s-1DSA\s0 keys.
268 .Ip "\fB\-engine id\fR" 4
269 specifying an engine (by it's unique \fBid\fR string) will cause \fBreq\fR
270 to attempt to obtain a functional reference to the specified engine,
271 thus initialising it if needed. The engine will then be set as the default
272 for all available algorithms.
273 .Sh "\s-1DISPLAY\s0 \s-1OPTIONS\s0"
274 Note: the \fB\-alias\fR and \fB\-purpose\fR options are also display options
275 but are described in the \fB\s-1TRUST\s0 \s-1SETTINGS\s0\fR section.
276 .Ip "\fB\-text\fR" 4
277 prints out the certificate in text form. Full details are output including the
278 public key, signature algorithms, issuer and subject names, serial number
279 any extensions present and any trust settings.
280 .Ip "\fB\-certopt option\fR" 4
281 customise the output format used with \fB\-text\fR. The \fBoption\fR argument can be
282 a single option or multiple options separated by commas. The \fB\-certopt\fR switch
283 may be also be used more than once to set multiple options. See the \fB\s-1TEXT\s0 \s-1OPTIONS\s0\fR
284 section for more information.
285 .Ip "\fB\-noout\fR" 4
286 this option prevents output of the encoded version of the request.
287 .Ip "\fB\-modulus\fR" 4
288 this option prints out the value of the modulus of the public key
289 contained in the certificate.
290 .Ip "\fB\-serial\fR" 4
291 outputs the certificate serial number.
292 .Ip "\fB\-hash\fR" 4
293 outputs the \*(L"hash\*(R" of the certificate subject name. This is used in OpenSSL to
294 form an index to allow certificates in a directory to be looked up by subject
295 name.
296 .Ip "\fB\-subject\fR" 4
297 outputs the subject name.
298 .Ip "\fB\-issuer\fR" 4
299 outputs the issuer name.
300 .Ip "\fB\-nameopt option\fR" 4
301 option which determines how the subject or issuer names are displayed. The
302 \fBoption\fR argument can be a single option or multiple options separated by
303 commas.  Alternatively the \fB\-nameopt\fR switch may be used more than once to
304 set multiple options. See the \fB\s-1NAME\s0 \s-1OPTIONS\s0\fR section for more information.
305 .Ip "\fB\-email\fR" 4
306 outputs the email \fIaddress\fR\|(es) if any.
307 .Ip "\fB\-startdate\fR" 4
308 prints out the start date of the certificate, that is the notBefore date.
309 .Ip "\fB\-enddate\fR" 4
310 prints out the expiry date of the certificate, that is the notAfter date.
311 .Ip "\fB\-dates\fR" 4
312 prints out the start and expiry dates of a certificate.
313 .Ip "\fB\-fingerprint\fR" 4
314 prints out the digest of the \s-1DER\s0 encoded version of the whole certificate
315 (see digest options).
316 .Ip "\fB\-C\fR" 4
317 this outputs the certificate in the form of a C source file.
318 .Sh "\s-1TRUST\s0 \s-1SETTINGS\s0"
319 Please note these options are currently experimental and may well change.
320 .PP
321 A \fBtrusted certificate\fR is an ordinary certificate which has several
322 additional pieces of information attached to it such as the permitted
323 and prohibited uses of the certificate and an \*(L"alias\*(R".
324 .PP
325 Normally when a certificate is being verified at least one certificate
326 must be \*(L"trusted\*(R". By default a trusted certificate must be stored
327 locally and must be a root \s-1CA\s0: any certificate chain ending in this \s-1CA\s0
328 is then usable for any purpose.
329 .PP
330 Trust settings currently are only used with a root \s-1CA\s0. They allow a finer
331 control over the purposes the root \s-1CA\s0 can be used for. For example a \s-1CA\s0
332 may be trusted for \s-1SSL\s0 client but not \s-1SSL\s0 server use.
333 .PP
334 See the description of the \fBverify\fR utility for more information on the
335 meaning of trust settings.
336 .PP
337 Future versions of OpenSSL will recognize trust settings on any
338 certificate: not just root CAs.
339 .Ip "\fB\-trustout\fR" 4
340 this causes \fBx509\fR to output a \fBtrusted\fR certificate. An ordinary
341 or trusted certificate can be input but by default an ordinary
342 certificate is output and any trust settings are discarded. With the
343 \fB\-trustout\fR option a trusted certificate is output. A trusted
344 certificate is automatically output if any trust settings are modified.
345 .Ip "\fB\-setalias arg\fR" 4
346 sets the alias of the certificate. This will allow the certificate
347 to be referred to using a nickname for example \*(L"Steve's Certificate\*(R".
348 .Ip "\fB\-alias\fR" 4
349 outputs the certificate alias, if any.
350 .Ip "\fB\-clrtrust\fR" 4
351 clears all the permitted or trusted uses of the certificate.
352 .Ip "\fB\-clrreject\fR" 4
353 clears all the prohibited or rejected uses of the certificate.
354 .Ip "\fB\-addtrust arg\fR" 4
355 adds a trusted certificate use. Any object name can be used here
356 but currently only \fBclientAuth\fR (\s-1SSL\s0 client use), \fBserverAuth\fR
357 (\s-1SSL\s0 server use) and \fBemailProtection\fR (S/\s-1MIME\s0 email) are used.
358 Other OpenSSL applications may define additional uses.
359 .Ip "\fB\-addreject arg\fR" 4
360 adds a prohibited use. It accepts the same values as the \fB\-addtrust\fR
361 option.
362 .Ip "\fB\-purpose\fR" 4
363 this option performs tests on the certificate extensions and outputs
364 the results. For a more complete description see the \fB\s-1CERTIFICATE\s0
365 \s-1EXTENSIONS\s0\fR section.
366 .Sh "\s-1SIGNING\s0 \s-1OPTIONS\s0"
367 The \fBx509\fR utility can be used to sign certificates and requests: it
368 can thus behave like a \*(L"mini \s-1CA\s0\*(R".
369 .Ip "\fB\-signkey filename\fR" 4
370 this option causes the input file to be self signed using the supplied
371 private key. 
372 .Sp
373 If the input file is a certificate it sets the issuer name to the
374 subject name (i.e.  makes it self signed) changes the public key to the
375 supplied value and changes the start and end dates. The start date is
376 set to the current time and the end date is set to a value determined
377 by the \fB\-days\fR option. Any certificate extensions are retained unless
378 the \fB\-clrext\fR option is supplied.
379 .Sp
380 If the input is a certificate request then a self signed certificate
381 is created using the supplied private key using the subject name in
382 the request.
383 .Ip "\fB\-clrext\fR" 4
384 delete any extensions from a certificate. This option is used when a
385 certificate is being created from another certificate (for example with
386 the \fB\-signkey\fR or the \fB\-\s-1CA\s0\fR options). Normally all extensions are
387 retained.
388 .Ip "\fB\-keyform \s-1PEM\s0|\s-1DER\s0\fR" 4
389 specifies the format (\s-1DER\s0 or \s-1PEM\s0) of the private key file used in the
390 \fB\-signkey\fR option.
391 .Ip "\fB\-days arg\fR" 4
392 specifies the number of days to make a certificate valid for. The default
393 is 30 days.
394 .Ip "\fB\-x509toreq\fR" 4
395 converts a certificate into a certificate request. The \fB\-signkey\fR option
396 is used to pass the required private key.
397 .Ip "\fB\-req\fR" 4
398 by default a certificate is expected on input. With this option a
399 certificate request is expected instead.
400 .Ip "\fB\-set_serial n\fR" 4
401 specifies the serial number to use. This option can be used with either
402 the \fB\-signkey\fR or \fB\-\s-1CA\s0\fR options. If used in conjunction with the \fB\-\s-1CA\s0\fR
403 option the serial number file (as specified by the \fB\-CAserial\fR or
404 \fB\-CAcreateserial\fR options) is not used.
405 .Sp
406 The serial number can be decimal or hex (if preceded by \fB0x\fR). Negative
407 serial numbers can also be specified but their use is not recommended.
408 .Ip "\fB\-\s-1CA\s0 filename\fR" 4
409 specifies the \s-1CA\s0 certificate to be used for signing. When this option is
410 present \fBx509\fR behaves like a \*(L"mini \s-1CA\s0\*(R". The input file is signed by this
411 \s-1CA\s0 using this option: that is its issuer name is set to the subject name
412 of the \s-1CA\s0 and it is digitally signed using the CAs private key.
413 .Sp
414 This option is normally combined with the \fB\-req\fR option. Without the
415 \fB\-req\fR option the input is a certificate which must be self signed.
416 .Ip "\fB\-CAkey filename\fR" 4
417 sets the \s-1CA\s0 private key to sign a certificate with. If this option is
418 not specified then it is assumed that the \s-1CA\s0 private key is present in
419 the \s-1CA\s0 certificate file.
420 .Ip "\fB\-CAserial filename\fR" 4
421 sets the \s-1CA\s0 serial number file to use.
422 .Sp
423 When the \fB\-\s-1CA\s0\fR option is used to sign a certificate it uses a serial
424 number specified in a file. This file consist of one line containing
425 an even number of hex digits with the serial number to use. After each
426 use the serial number is incremented and written out to the file again.
427 .Sp
428 The default filename consists of the \s-1CA\s0 certificate file base name with
429 \*(L".srl\*(R" appended. For example if the \s-1CA\s0 certificate file is called 
430 \*(L"mycacert.pem\*(R" it expects to find a serial number file called \*(L"mycacert.srl\*(R".
431 .Ip "\fB\-CAcreateserial\fR" 4
432 with this option the \s-1CA\s0 serial number file is created if it does not exist:
433 it will contain the serial number \*(L"02\*(R" and the certificate being signed will
434 have the 1 as its serial number. Normally if the \fB\-\s-1CA\s0\fR option is specified
435 and the serial number file does not exist it is an error.
436 .Ip "\fB\-extfile filename\fR" 4
437 file containing certificate extensions to use. If not specified then
438 no extensions are added to the certificate.
439 .Ip "\fB\-extensions section\fR" 4
440 the section to add certificate extensions from. If this option is not
441 specified then the extensions should either be contained in the unnamed
442 (default) section or the default section should contain a variable called
443 \*(L"extensions\*(R" which contains the section to use.
444 .Sh "\s-1NAME\s0 \s-1OPTIONS\s0"
445 The \fBnameopt\fR command line switch determines how the subject and issuer
446 names are displayed. If no \fBnameopt\fR switch is present the default \*(L"oneline\*(R"
447 format is used which is compatible with previous versions of OpenSSL.
448 Each option is described in detail below, all options can be preceded by
449 a \fB\-\fR to turn the option off. Only the first four will normally be used.
450 .Ip "\fBcompat\fR" 4
451 use the old format. This is equivalent to specifying no name options at all.
452 .Ip "\fB\s-1RFC2253\s0\fR" 4
453 displays names compatible with \s-1RFC2253\s0 equivalent to \fBesc_2253\fR, \fBesc_ctrl\fR,
454 \fBesc_msb\fR, \fButf8\fR, \fBdump_nostr\fR, \fBdump_unknown\fR, \fBdump_der\fR,
455 \fBsep_comma_plus\fR, \fBdn_rev\fR and \fBsname\fR.
456 .Ip "\fBoneline\fR" 4
457 a oneline format which is more readable than \s-1RFC2253\s0. It is equivalent to
458 specifying the  \fBesc_2253\fR, \fBesc_ctrl\fR, \fBesc_msb\fR, \fButf8\fR, \fBdump_nostr\fR,
459 \fBdump_der\fR, \fBuse_quote\fR, \fBsep_comma_plus_spc\fR, \fBspc_eq\fR and \fBsname\fR
460 options.
461 .Ip "\fBmultiline\fR" 4
462 a multiline format. It is equivalent \fBesc_ctrl\fR, \fBesc_msb\fR, \fBsep_multiline\fR,
463 \fBspc_eq\fR, \fBlname\fR and \fBalign\fR.
464 .Ip "\fBesc_2253\fR" 4
465 escape the \*(L"special\*(R" characters required by \s-1RFC2253\s0 in a field That is
466 \fB,+"<>;\fR. Additionally \fB#\fR is escaped at the beginning of a string
467 and a space character at the beginning or end of a string.
468 .Ip "\fBesc_ctrl\fR" 4
469 escape control characters. That is those with \s-1ASCII\s0 values less than
470 0x20 (space) and the delete (0x7f) character. They are escaped using the
471 \s-1RFC2253\s0 \eXX notation (where \s-1XX\s0 are two hex digits representing the
472 character value).
473 .Ip "\fBesc_msb\fR" 4
474 escape characters with the \s-1MSB\s0 set, that is with \s-1ASCII\s0 values larger than
475 127.
476 .Ip "\fBuse_quote\fR" 4
477 escapes some characters by surrounding the whole string with \fB\*(R"\fR characters,
478 without the option all escaping is done with the \fB\e\fR character.
479 .Ip "\fButf8\fR" 4
480 convert all strings to \s-1UTF8\s0 format first. This is required by \s-1RFC2253\s0. If
481 you are lucky enough to have a \s-1UTF8\s0 compatible terminal then the use
482 of this option (and \fBnot\fR setting \fBesc_msb\fR) may result in the correct
483 display of multibyte (international) characters. Is this option is not
484 present then multibyte characters larger than 0xff will be represented
485 using the format \eUXXXX for 16 bits and \eWXXXXXXXX for 32 bits.
486 Also if this option is off any UTF8Strings will be converted to their
487 character form first.
488 .Ip "\fBno_type\fR" 4
489 this option does not attempt to interpret multibyte characters in any
490 way. That is their content octets are merely dumped as though one octet
491 represents each character. This is useful for diagnostic purposes but
492 will result in rather odd looking output.
493 .Ip "\fBshow_type\fR" 4
494 show the type of the \s-1ASN1\s0 character string. The type precedes the
495 field contents. For example \*(L"\s-1BMPSTRING\s0: Hello World\*(R".
496 .Ip "\fBdump_der\fR" 4
497 when this option is set any fields that need to be hexdumped will
498 be dumped using the \s-1DER\s0 encoding of the field. Otherwise just the
499 content octets will be displayed. Both options use the \s-1RFC2253\s0
500 \fB#\s-1XXXX\s0...\fR format.
501 .Ip "\fBdump_nostr\fR" 4
502 dump non character string types (for example \s-1OCTET\s0 \s-1STRING\s0) if this
503 option is not set then non character string types will be displayed
504 as though each content octet represents a single character.
505 .Ip "\fBdump_all\fR" 4
506 dump all fields. This option when used with \fBdump_der\fR allows the
507 \s-1DER\s0 encoding of the structure to be unambiguously determined.
508 .Ip "\fBdump_unknown\fR" 4
509 dump any field whose \s-1OID\s0 is not recognised by OpenSSL.
510 .Ip "\fBsep_comma_plus\fR, \fBsep_comma_plus_space\fR, \fBsep_semi_plus_space\fR, \fBsep_multiline\fR" 4
511 these options determine the field separators. The first character is
512 between RDNs and the second between multiple AVAs (multiple AVAs are
513 very rare and their use is discouraged). The options ending in
514 \*(L"space\*(R" additionally place a space after the separator to make it
515 more readable. The \fBsep_multiline\fR uses a linefeed character for
516 the \s-1RDN\s0 separator and a spaced \fB+\fR for the \s-1AVA\s0 separator. It also
517 indents the fields by four characters.
518 .Ip "\fBdn_rev\fR" 4
519 reverse the fields of the \s-1DN\s0. This is required by \s-1RFC2253\s0. As a side
520 effect this also reverses the order of multiple AVAs but this is
521 permissible.
522 .Ip "\fBnofname\fR, \fBsname\fR, \fBlname\fR, \fBoid\fR" 4
523 these options alter how the field name is displayed. \fBnofname\fR does
524 not display the field at all. \fBsname\fR uses the \*(L"short name\*(R" form
525 (\s-1CN\s0 for commonName for example). \fBlname\fR uses the long form.
526 \fBoid\fR represents the \s-1OID\s0 in numerical form and is useful for
527 diagnostic purpose.
528 .Ip "\fBalign\fR" 4
529 align field values for a more readable output. Only usable with
530 \fBsep_multiline\fR.
531 .Ip "\fBspc_eq\fR" 4
532 places spaces round the \fB=\fR character which follows the field
533 name.
534 .Sh "\s-1TEXT\s0 \s-1OPTIONS\s0"
535 As well as customising the name output format, it is also possible to
536 customise the actual fields printed using the \fBcertopt\fR options when
537 the \fBtext\fR option is present. The default behaviour is to print all fields.
538 .Ip "\fBcompatible\fR" 4
539 use the old format. This is equivalent to specifying no output options at all.
540 .Ip "\fBno_header\fR" 4
541 don't print header information: that is the lines saying \*(L"Certificate\*(R" and \*(L"Data\*(R".
542 .Ip "\fBno_version\fR" 4
543 don't print out the version number.
544 .Ip "\fBno_serial\fR" 4
545 don't print out the serial number.
546 .Ip "\fBno_signame\fR" 4
547 don't print out the signature algorithm used.
548 .Ip "\fBno_validity\fR" 4
549 don't print the validity, that is the \fBnotBefore\fR and \fBnotAfter\fR fields.
550 .Ip "\fBno_subject\fR" 4
551 don't print out the subject name.
552 .Ip "\fBno_issuer\fR" 4
553 don't print out the issuer name.
554 .Ip "\fBno_pubkey\fR" 4
555 don't print out the public key.
556 .Ip "\fBno_sigdump\fR" 4
557 don't give a hexadecimal dump of the certificate signature.
558 .Ip "\fBno_aux\fR" 4
559 don't print out certificate trust information.
560 .Ip "\fBno_extensions\fR" 4
561 don't print out any X509V3 extensions.
562 .Ip "\fBext_default\fR" 4
563 retain default extension behaviour: attempt to print out unsupported certificate extensions.
564 .Ip "\fBext_error\fR" 4
565 print an error message for unsupported certificate extensions.
566 .Ip "\fBext_parse\fR" 4
567 \s-1ASN1\s0 parse unsupported extensions.
568 .Ip "\fBext_dump\fR" 4
569 hex dump unsupported extensions.
570 .Ip "\fBca_default\fR" 4
571 the value used by the \fBca\fR utility, equivalent to \fBno_issuer\fR, \fBno_pubkey\fR, \fBno_header\fR,
572 \fBno_version\fR, \fBno_sigdump\fR and \fBno_signame\fR.
573 .SH "EXAMPLES"
574 Note: in these examples the \*(L'\e\*(R' means the example should be all on one
575 line.
576 .PP
577 Display the contents of a certificate:
578 .PP
579 .Vb 1
580 \& openssl x509 -in cert.pem -noout -text
581 .Ve
582 Display the certificate serial number:
583 .PP
584 .Vb 1
585 \& openssl x509 -in cert.pem -noout -serial
586 .Ve
587 Display the certificate subject name:
588 .PP
589 .Vb 1
590 \& openssl x509 -in cert.pem -noout -subject
591 .Ve
592 Display the certificate subject name in RFC2253 form:
593 .PP
594 .Vb 1
595 \& openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
596 .Ve
597 Display the certificate subject name in oneline form on a terminal
598 supporting UTF8:
599 .PP
600 .Vb 1
601 \& openssl x509 -in cert.pem -noout -subject -nameopt oneline,-escmsb
602 .Ve
603 Display the certificate MD5 fingerprint:
604 .PP
605 .Vb 1
606 \& openssl x509 -in cert.pem -noout -fingerprint
607 .Ve
608 Display the certificate SHA1 fingerprint:
609 .PP
610 .Vb 1
611 \& openssl x509 -sha1 -in cert.pem -noout -fingerprint
612 .Ve
613 Convert a certificate from PEM to DER format:
614 .PP
615 .Vb 1
616 \& openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
617 .Ve
618 Convert a certificate to a certificate request:
619 .PP
620 .Vb 1
621 \& openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
622 .Ve
623 Convert a certificate request into a self signed certificate using
624 extensions for a CA:
625 .PP
626 .Vb 2
627 \& openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \e
628 \&        -signkey key.pem -out cacert.pem
629 .Ve
630 Sign a certificate request using the CA certificate above and add user
631 certificate extensions:
632 .PP
633 .Vb 2
634 \& openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \e
635 \&        -CA cacert.pem -CAkey key.pem -CAcreateserial
636 .Ve
637 Set a certificate to be trusted for SSL client use and change set its alias to
638 \*(L"Steve's Class 1 CA\*(R"
639 .PP
640 .Vb 2
641 \& openssl x509 -in cert.pem -addtrust clientAuth \e
642 \&        -setalias "Steve's Class 1 CA" -out trust.pem
643 .Ve
644 .SH "NOTES"
645 The PEM format uses the header and footer lines:
646 .PP
647 .Vb 2
648 \& -----BEGIN CERTIFICATE-----
649 \& -----END CERTIFICATE-----
650 .Ve
651 it will also handle files containing:
652 .PP
653 .Vb 2
654 \& -----BEGIN X509 CERTIFICATE-----
655 \& -----END X509 CERTIFICATE-----
656 .Ve
657 Trusted certificates have the lines
658 .PP
659 .Vb 2
660 \& -----BEGIN TRUSTED CERTIFICATE-----
661 \& -----END TRUSTED CERTIFICATE-----
662 .Ve
663 The conversion to UTF8 format used with the name options assumes that
664 T61Strings use the ISO8859-1 character set. This is wrong but Netscape
665 and MSIE do this as do many certificates. So although this is incorrect
666 it is more likely to display the majority of certificates correctly.
667 .PP
668 The \fB\-fingerprint\fR option takes the digest of the DER encoded certificate.
669 This is commonly called a \*(L"fingerprint\*(R". Because of the nature of message
670 digests the fingerprint of a certificate is unique to that certificate and
671 two certificates with the same fingerprint can be considered to be the same.
672 .PP
673 The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
674 .PP
675 The \fB\-email\fR option searches the subject name and the subject alternative
676 name extension. Only unique email addresses will be printed out: it will
677 not print the same address more than once.
678 .SH "CERTIFICATE EXTENSIONS"
679 The \fB\-purpose\fR option checks the certificate extensions and determines
680 what the certificate can be used for. The actual checks done are rather
681 complex and include various hacks and workarounds to handle broken
682 certificates and software.
683 .PP
684 The same code is used when verifying untrusted certificates in chains
685 so this section is useful if a chain is rejected by the verify code.
686 .PP
687 The basicConstraints extension CA flag is used to determine whether the
688 certificate can be used as a CA. If the CA flag is true then it is a CA,
689 if the CA flag is false then it is not a CA. \fBAll\fR CAs should have the
690 CA flag set to true.
691 .PP
692 If the basicConstraints extension is absent then the certificate is
693 considered to be a \*(L"possible CA\*(R" other extensions are checked according
694 to the intended use of the certificate. A warning is given in this case
695 because the certificate should really not be regarded as a CA: however
696 it is allowed to be a CA to work around some broken software.
697 .PP
698 If the certificate is a V1 certificate (and thus has no extensions) and
699 it is self signed it is also assumed to be a CA but a warning is again
700 given: this is to work around the problem of Verisign roots which are V1
701 self signed certificates.
702 .PP
703 If the keyUsage extension is present then additional restraints are
704 made on the uses of the certificate. A CA certificate \fBmust\fR have the
705 keyCertSign bit set if the keyUsage extension is present.
706 .PP
707 The extended key usage extension places additional restrictions on the
708 certificate uses. If this extension is present (whether critical or not)
709 the key can only be used for the purposes specified.
710 .PP
711 A complete description of each test is given below. The comments about
712 basicConstraints and keyUsage and V1 certificates above apply to \fBall\fR
713 CA certificates.
714 .Ip "\fB\s-1SSL\s0 Client\fR" 4
715 The extended key usage extension must be absent or include the \*(L"web client
716 authentication\*(R" \s-1OID\s0.  keyUsage must be absent or it must have the
717 digitalSignature bit set. Netscape certificate type must be absent or it must
718 have the \s-1SSL\s0 client bit set.
719 .Ip "\fB\s-1SSL\s0 Client \s-1CA\s0\fR" 4
720 The extended key usage extension must be absent or include the \*(L"web client
721 authentication\*(R" \s-1OID\s0. Netscape certificate type must be absent or it must have
722 the \s-1SSL\s0 \s-1CA\s0 bit set: this is used as a work around if the basicConstraints
723 extension is absent.
724 .Ip "\fB\s-1SSL\s0 Server\fR" 4
725 The extended key usage extension must be absent or include the \*(L"web server
726 authentication\*(R" and/or one of the \s-1SGC\s0 OIDs.  keyUsage must be absent or it
727 must have the digitalSignature, the keyEncipherment set or both bits set.
728 Netscape certificate type must be absent or have the \s-1SSL\s0 server bit set.
729 .Ip "\fB\s-1SSL\s0 Server \s-1CA\s0\fR" 4
730 The extended key usage extension must be absent or include the \*(L"web server
731 authentication\*(R" and/or one of the \s-1SGC\s0 OIDs.  Netscape certificate type must
732 be absent or the \s-1SSL\s0 \s-1CA\s0 bit must be set: this is used as a work around if the
733 basicConstraints extension is absent.
734 .Ip "\fBNetscape \s-1SSL\s0 Server\fR" 4
735 For Netscape \s-1SSL\s0 clients to connect to an \s-1SSL\s0 server it must have the
736 keyEncipherment bit set if the keyUsage extension is present. This isn't
737 always valid because some cipher suites use the key for digital signing.
738 Otherwise it is the same as a normal \s-1SSL\s0 server.
739 .Ip "\fBCommon S/\s-1MIME\s0 Client Tests\fR" 4
740 The extended key usage extension must be absent or include the \*(L"email
741 protection\*(R" \s-1OID\s0. Netscape certificate type must be absent or should have the
742 S/\s-1MIME\s0 bit set. If the S/\s-1MIME\s0 bit is not set in netscape certificate type
743 then the \s-1SSL\s0 client bit is tolerated as an alternative but a warning is shown:
744 this is because some Verisign certificates don't set the S/\s-1MIME\s0 bit.
745 .Ip "\fBS/\s-1MIME\s0 Signing\fR" 4
746 In addition to the common S/\s-1MIME\s0 client tests the digitalSignature bit must
747 be set if the keyUsage extension is present.
748 .Ip "\fBS/\s-1MIME\s0 Encryption\fR" 4
749 In addition to the common S/\s-1MIME\s0 tests the keyEncipherment bit must be set
750 if the keyUsage extension is present.
751 .Ip "\fBS/\s-1MIME\s0 \s-1CA\s0\fR" 4
752 The extended key usage extension must be absent or include the \*(L"email
753 protection\*(R" \s-1OID\s0. Netscape certificate type must be absent or must have the
754 S/\s-1MIME\s0 \s-1CA\s0 bit set: this is used as a work around if the basicConstraints
755 extension is absent. 
756 .Ip "\fB\s-1CRL\s0 Signing\fR" 4
757 The keyUsage extension must be absent or it must have the \s-1CRL\s0 signing bit
758 set.
759 .Ip "\fB\s-1CRL\s0 Signing \s-1CA\s0\fR" 4
760 The normal \s-1CA\s0 tests apply. Except in this case the basicConstraints extension
761 must be present.
762 .SH "BUGS"
763 Extensions in certificates are not transferred to certificate requests and
764 vice versa.
765 .PP
766 It is possible to produce invalid certificates or requests by specifying the
767 wrong private key or using inconsistent options in some cases: these should
768 be checked.
769 .PP
770 There should be options to explicitly set such things as start and end
771 dates rather than an offset from the current time.
772 .PP
773 The code to implement the verify behaviour described in the \fBTRUST SETTINGS\fR
774 is currently being developed. It thus describes the intended behaviour rather
775 than the current behaviour. It is hoped that it will represent reality in
776 OpenSSL 0.9.5 and later.
777 .SH "SEE ALSO"
778 req(1), ca(1), genrsa(1),
779 gendsa(1), verify(1)
780
781 .rn }` ''
782 .IX Title "X509 1"
783 .IX Name "x509 - Certificate display and signing utility"
784
785 .IX Header "NAME"
786
787 .IX Header "SYNOPSIS"
788
789 .IX Header "DESCRIPTION"
790
791 .IX Header "OPTIONS"
792
793 .IX Subsection "\s-1INPUT\s0, \s-1OUTPUT\s0 \s-1AND\s0 \s-1GENERAL\s0 \s-1PURPOSE\s0 \s-1OPTIONS\s0"
794
795 .IX Item "\fB\-inform \s-1DER\s0|\s-1PEM\s0|\s-1NET\s0\fR"
796
797 .IX Item "\fB\-outform \s-1DER\s0|\s-1PEM\s0|\s-1NET\s0\fR"
798
799 .IX Item "\fB\-in filename\fR"
800
801 .IX Item "\fB\-out filename\fR"
802
803 .IX Item "\fB\-md2|\-md5|\-sha1|\-mdc2\fR"
804
805 .IX Item "\fB\-engine id\fR"
806
807 .IX Subsection "\s-1DISPLAY\s0 \s-1OPTIONS\s0"
808
809 .IX Item "\fB\-text\fR"
810
811 .IX Item "\fB\-certopt option\fR"
812
813 .IX Item "\fB\-noout\fR"
814
815 .IX Item "\fB\-modulus\fR"
816
817 .IX Item "\fB\-serial\fR"
818
819 .IX Item "\fB\-hash\fR"
820
821 .IX Item "\fB\-subject\fR"
822
823 .IX Item "\fB\-issuer\fR"
824
825 .IX Item "\fB\-nameopt option\fR"
826
827 .IX Item "\fB\-email\fR"
828
829 .IX Item "\fB\-startdate\fR"
830
831 .IX Item "\fB\-enddate\fR"
832
833 .IX Item "\fB\-dates\fR"
834
835 .IX Item "\fB\-fingerprint\fR"
836
837 .IX Item "\fB\-C\fR"
838
839 .IX Subsection "\s-1TRUST\s0 \s-1SETTINGS\s0"
840
841 .IX Item "\fB\-trustout\fR"
842
843 .IX Item "\fB\-setalias arg\fR"
844
845 .IX Item "\fB\-alias\fR"
846
847 .IX Item "\fB\-clrtrust\fR"
848
849 .IX Item "\fB\-clrreject\fR"
850
851 .IX Item "\fB\-addtrust arg\fR"
852
853 .IX Item "\fB\-addreject arg\fR"
854
855 .IX Item "\fB\-purpose\fR"
856
857 .IX Subsection "\s-1SIGNING\s0 \s-1OPTIONS\s0"
858
859 .IX Item "\fB\-signkey filename\fR"
860
861 .IX Item "\fB\-clrext\fR"
862
863 .IX Item "\fB\-keyform \s-1PEM\s0|\s-1DER\s0\fR"
864
865 .IX Item "\fB\-days arg\fR"
866
867 .IX Item "\fB\-x509toreq\fR"
868
869 .IX Item "\fB\-req\fR"
870
871 .IX Item "\fB\-set_serial n\fR"
872
873 .IX Item "\fB\-\s-1CA\s0 filename\fR"
874
875 .IX Item "\fB\-CAkey filename\fR"
876
877 .IX Item "\fB\-CAserial filename\fR"
878
879 .IX Item "\fB\-CAcreateserial\fR"
880
881 .IX Item "\fB\-extfile filename\fR"
882
883 .IX Item "\fB\-extensions section\fR"
884
885 .IX Subsection "\s-1NAME\s0 \s-1OPTIONS\s0"
886
887 .IX Item "\fBcompat\fR"
888
889 .IX Item "\fB\s-1RFC2253\s0\fR"
890
891 .IX Item "\fBoneline\fR"
892
893 .IX Item "\fBmultiline\fR"
894
895 .IX Item "\fBesc_2253\fR"
896
897 .IX Item "\fBesc_ctrl\fR"
898
899 .IX Item "\fBesc_msb\fR"
900
901 .IX Item "\fBuse_quote\fR"
902
903 .IX Item "\fButf8\fR"
904
905 .IX Item "\fBno_type\fR"
906
907 .IX Item "\fBshow_type\fR"
908
909 .IX Item "\fBdump_der\fR"
910
911 .IX Item "\fBdump_nostr\fR"
912
913 .IX Item "\fBdump_all\fR"
914
915 .IX Item "\fBdump_unknown\fR"
916
917 .IX Item "\fBsep_comma_plus\fR, \fBsep_comma_plus_space\fR, \fBsep_semi_plus_space\fR, \fBsep_multiline\fR"
918
919 .IX Item "\fBdn_rev\fR"
920
921 .IX Item "\fBnofname\fR, \fBsname\fR, \fBlname\fR, \fBoid\fR"
922
923 .IX Item "\fBalign\fR"
924
925 .IX Item "\fBspc_eq\fR"
926
927 .IX Subsection "\s-1TEXT\s0 \s-1OPTIONS\s0"
928
929 .IX Item "\fBcompatible\fR"
930
931 .IX Item "\fBno_header\fR"
932
933 .IX Item "\fBno_version\fR"
934
935 .IX Item "\fBno_serial\fR"
936
937 .IX Item "\fBno_signame\fR"
938
939 .IX Item "\fBno_validity\fR"
940
941 .IX Item "\fBno_subject\fR"
942
943 .IX Item "\fBno_issuer\fR"
944
945 .IX Item "\fBno_pubkey\fR"
946
947 .IX Item "\fBno_sigdump\fR"
948
949 .IX Item "\fBno_aux\fR"
950
951 .IX Item "\fBno_extensions\fR"
952
953 .IX Item "\fBext_default\fR"
954
955 .IX Item "\fBext_error\fR"
956
957 .IX Item "\fBext_parse\fR"
958
959 .IX Item "\fBext_dump\fR"
960
961 .IX Item "\fBca_default\fR"
962
963 .IX Header "EXAMPLES"
964
965 .IX Header "NOTES"
966
967 .IX Header "CERTIFICATE EXTENSIONS"
968
969 .IX Item "\fB\s-1SSL\s0 Client\fR"
970
971 .IX Item "\fB\s-1SSL\s0 Client \s-1CA\s0\fR"
972
973 .IX Item "\fB\s-1SSL\s0 Server\fR"
974
975 .IX Item "\fB\s-1SSL\s0 Server \s-1CA\s0\fR"
976
977 .IX Item "\fBNetscape \s-1SSL\s0 Server\fR"
978
979 .IX Item "\fBCommon S/\s-1MIME\s0 Client Tests\fR"
980
981 .IX Item "\fBS/\s-1MIME\s0 Signing\fR"
982
983 .IX Item "\fBS/\s-1MIME\s0 Encryption\fR"
984
985 .IX Item "\fBS/\s-1MIME\s0 \s-1CA\s0\fR"
986
987 .IX Item "\fB\s-1CRL\s0 Signing\fR"
988
989 .IX Item "\fB\s-1CRL\s0 Signing \s-1CA\s0\fR"
990
991 .IX Header "BUGS"
992
993 .IX Header "SEE ALSO"
994