Second round of fixing the OpenSSL perl/ stuff. It now at least compiled fine
[openssl.git] / doc / ext-conf.txt
1 OpenSSL X509V3 extension configuration: preliminary documentation.
2
3 INTRODUCTION.
4
5 For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now
6 possible to add and print out common X509 V3 certificate and CRL extensions.
7
8 For more information about the meaning of extensions see:
9
10 http://www.imc.org/ietf-pkix/
11 http://home.netscape.com/eng/security/certs.html
12
13 PRINTING EXTENSIONS.
14
15 Extension values are automatically printed out for supported extensions.
16
17 openssl x509 -in cert.pem -text
18 openssl crl -in crl.pem -text
19
20 will give information in the extension printout, for example:
21
22
23         X509v3 extensions:
24             X509v3 Basic Constraints: 
25                 CA:TRUE
26             X509v3 Subject Key Identifier: 
27                 73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15
28             X509v3 Authority Key Identifier: 
29                 keyid:73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15, DirName:/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd/Email=email@1.address/Email=email@2.address, serial:00
30             X509v3 Key Usage: 
31                 Certificate Sign, CRL Sign
32             X509v3 Subject Alternative Name: 
33                 email:email@1.address, email:email@2.address
34
35 CONFIGURATION FILES.
36
37 The OpenSSL utilities 'ca' and 'req' can now have extension sections listing
38 which certificate extensions to include. In each case a line:
39
40 x509_extensions = extension_section
41
42 indicates which section contains the extensions. In the case of 'req' the
43 extension section is used when the -x509 option is present to create a
44 self signed root certificate.
45
46 You can also add extensions to CRLs: a line
47
48 crl_extensions = crl_extension_section
49
50 will include extensions when the -gencrl option is used with the 'ca' utility.
51 You can add any extension to a CRL but of the supported extensions only
52 issuerAltName and authorityKeyIdentifier make any real sense. Note: these are
53 CRL extensions NOT CRL *entry* extensions which cannot currently be generated.
54 CRL entry extensions can be displayed.
55
56 EXTENSION SYNTAX.
57
58 Extensions have the basic form:
59
60 extension_name=[critical,] extension_options
61
62 the use of the critical option makes the extension critical. Extreme caution
63 should be made when using the critical flag. If an extension is marked
64 as critical then any client that does not understand the extension should
65 reject it as invalid. Some broken software will reject certificates which
66 have *any* critical extensions (these violates PKIX but we have to live
67 with it).
68
69 There are three main types of extension, string extensions, multi valued
70 extensions, and raw extensions.
71
72 String extensions simply have a string which defines the value of the or how
73 it is obtained.
74
75 For example:
76
77 nsComment="This is a Comment"
78
79 Multi valued extensions have a short form and a long form. The short form
80 is a list of names and values:
81
82 basicConstraints=critical,CA:true,pathlen:1
83
84 The long form allows the values to be placed in a separate section:
85
86 basicConstraints=critical,@bs_section
87
88 [bs_section]
89
90 CA=true
91 pathlen=1
92
93 Both forms are equivalent. However it should be noted that in some cases the
94 same name can appear multiple times, for example,
95
96 subjectAltName=email:steve@here,email:steve@there
97
98 in this case an equivalent long form is:
99
100 subjectAltName=@alt_section
101
102 [alt_section]
103
104 email.1=steve@here
105 email.2=steve@there
106
107 This is because the configuration file code cannot handle the same name
108 occurring twice in the same extension.
109
110 Raw extensions allow arbitrary data to be placed in an extension. For
111 example
112
113 1.2.3.4=critical,RAW:01:02:03:04
114 1.2.3.4=RAW:01020304
115
116 The value following RAW is a hex dump of the extension contents. Any extension
117 can be placed in this form to override the default behaviour. For example:
118
119 basicConstraints=critical,RAW:00:01:02:03
120
121 WARNING: raw extensions should be used with caution. It is possible to create
122 totally invalid extensions unless care is taken.
123
124 CURRENTLY SUPPORTED EXTENSIONS.
125
126 Literal String extensions.
127
128 In each case the 'value' of the extension is placed directly in the extension.
129 Currently supported extensions in this category are: nsBaseUrl, nsRevocationUrl
130 nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, nsSslServerName and
131 nsComment.
132
133 For example:
134
135 nsComment="This is a test comment"
136
137 Bit Strings.
138
139 Bit string extensions just consist of a list of suppported bits, currently
140 two extensions are in this category: PKIX keyUsage and the Netscape specific
141 nsCertType.
142
143 nsCertType (netscape certificate type) takes the flags: client, server, email,
144 objsign, reserved, sslCA, emailCA, objCA.
145
146 keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation,
147 keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLCertSign,
148 encipherOnly, decipherOnly.
149
150 For example:
151
152 nsCertType=server
153
154 keyUsage=critical, digitalSignature, nonRepudiation
155
156
157 Basic Constraints.
158
159 Basic constraints is a multi valued extension that supports a CA and an
160 optional pathlen option. The CA option takes the values true and false and
161 pathlen takes an integer. Note if the CA option is false the pathlen option
162 should be omitted.
163
164 Examples:
165
166 basicConstraints=CA:TRUE
167 basicConstraints=critical,CA:TRUE, pathlen:10
168
169 NOTE: for a CA to be considered valid it must have the CA option set to
170 TRUE. An end user certificate MUST NOT have the CA value set to true.
171 According to PKIX recommendations it should exclude the extension entirely
172 however some software may require CA set to FALSE for end entity certificates.
173
174 Subject Key Identifier.
175
176 This is really a string extension and can take two possible values. Either
177 a hex string giving details of the extension value to include or the word
178 'hash' which then automatically follow PKIX guidelines in selecting and
179 appropriate key identifier. The use of the hex string is strongly discouraged.
180
181 Example: subjectKeyIdentifier=hash
182
183 Authority Key Identifier.
184
185 The authority key identifier extension permits two options. keyid and issuer:
186 both can take the optional value "always".
187
188 If the keyid option is present an attempt is made to copy the subject key
189 identifier from the parent certificate. If the value "always" is present
190 then an error is returned if the option fails.
191
192 The issuer option copies the issuer and serial number from the issuer
193 certificate. Normally this will only be done if the keyid option fails or
194 is not included: the "always" flag will always include the value.
195
196 Subject Alternative Name.
197
198 The subject alternative name extension allows various literal values to be
199 included in the configuration file. These include "email" (an email address)
200 "URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a
201 registered ID: OBJECT IDENTIFIER) and IP (and IP address).
202
203 Also the email option include a special 'copy' value. This will automatically
204 include and email addresses contained in the certificate subject name in
205 the extension.
206
207 Examples:
208
209 subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/
210 subjectAltName=email:my@other.address,RID:1.2.3.4
211
212 Issuer Alternative Name.
213
214 The issuer alternative name option supports all the literal options of
215 subject alternative name. It does *not* support the email:copy option because
216 that would not make sense. It does support and additional issuer:copy option
217 that will copy all the subject alternative name values from the issuer 
218 certificate (if possible).
219
220 Display only extensions.
221
222 Some extensions are only partially supported and currently are only displayed
223 but cannot be set. These include private key usage period, CRL number, and
224 CRL reason.