1 OpenSSL X509V3 extension configuration: preliminary documentation.
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.
8 For more information about the meaning of extensions see:
10 http://www.imc.org/ietf-pkix/
11 http://home.netscape.com/eng/security/certs.html
15 Extension values are automatically printed out for supported extensions.
17 x509 -in cert.pem -text
20 will give information in the extension printout, for example:
24 X509v3 Basic Constraints:
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
31 Certificate Sign, CRL Sign
32 X509v3 Subject Alternative Name:
33 email:email@1.address, email:email@2.address
37 The OpenSSL utilities 'ca' and 'req' can now have extension sections listing
38 which certificate extensions to include. In each case a line:
40 x509_extensions = extension_section
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.
48 Extensions have the basic form:
50 extension_name=[critical,] extension_options
52 the use of the critical option makes the extension critical. Extreme caution
53 should be made when using the critical flag. If an extension is marked
54 as critical then any client that does not understand the extension should
55 reject it as invalid. Some broken software will reject certificates which
56 have *any* critical extensions (these violates PKIX but we have to live
59 There are three main types of extension, string extensions, multi valued
60 extensions, and raw extensions.
62 String extensions simply have a string which defines the value of the or how
67 nsComment="This is a Comment"
69 Multi valued extensions have a short form and a long form. The short form
70 is a list of names and values:
72 basicConstraints=critical,CA:true,pathlen:1
74 The long form allows the values to be placed in a separate section:
76 basicConstraints=critical,@bs_section
83 Both forms are equivalent. However it should be noted that in some cases the
84 same name can appear multiple times, for example,
86 subjectAltName=email:steve@here,email:steve@there
88 in this case an equivalent long form is:
90 subjectAltName=@alt_section
97 This is because the configuration file code cannot handle the same name
98 occurring twice in the same extension.
100 Raw extensions allow arbitrary data to be placed in an extension. For
103 1.2.3.4=critical,RAW:01:02:03:04
106 The value following RAW is a hex dump of the extension contents. Any extension
107 can be placed in this form to override the default behaviour. For example:
109 basicConstraints=critical,RAW:00:01:02:03
111 WARNING: raw extensions should be used with caution. It is possible to create
112 totally invalid extensions unless care is taken.
114 CURRENTLY SUPPORTED EXTENSIONS.
116 Literal String extensions.
118 In each case the 'value' of the extension is placed directly in the extension.
119 Currently supported extensions in this category are: nsBaseUrl, nsRevocationUrl
120 nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, nsSslServerName and
125 nsComment="This is a test comment"
129 Bit string extensions just consist of a list of suppported bits, currently
130 two extensions are in this category: PKIX keyUsage and the Netscape specific
133 nsCertType (netscape certificate type) takes the flags: client, server, email,
134 objsign, reserved, sslCA, emailCA, objCA.
136 keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation,
137 keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLCertSign,
138 encipherOnly, decipherOnly.
144 keyUsage=critical, digitalSignature, nonRepudiation
149 Basic constraints is a multi valued extension that supports a CA and an
150 optional pathlen option. The CA option takes the values true and false and
151 pathlen takes an integer. Note if the CA option is false the pathlen option
156 basicConstraints=CA:TRUE
157 basicConstraints=critical,CA:TRUE, pathlen:10
159 NOTE: for a CA to be considered valid it must have the CA option set to
160 TRUE. An end user certificate MUST NOT have the CA value set to true.
161 According to PKIX recommendations it should exclude the extension entirely
162 however some software may require CA set to FALSE for end entity certificates.
164 Subject Key Identifier.
166 This is really a string extension and can take two possible values. Either
167 a hex string giving details of the extension value to include or the word
168 'hash' which then automatically follow PKIX guidelines in selecting and
169 appropriate key identifier. The use of the hex string is strongly discouraged.
171 Example: subjectKeyIdentifier=hash
173 Authority Key Identifier.
175 The authority key identifier extension permits two options. keyid and issuer:
176 both can take the optional value "always".
178 If the keyid option is present an attempt is made to copy the subject key
179 identifier from the parent certificate. If the value "always" is present
180 then an error is returned if the option fails.
182 The issuer option copies the issuer and serial number from the issuer
183 certificate. Normally this will only be done if the keyid option fails or
184 is not included: the "always" flag will always include the value.
186 Subject Alternative Name.
188 The subject alternative name extension allows various literal values to be
189 included in the configuration file. These include "email" (an email address)
190 "URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a
191 registered ID: OBJECT IDENTIFIER) and IP (and IP address).
193 Also the email option include a special 'copy' value. This will automatically
194 include and email addresses contained in the certificate subject name in
199 subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/
200 subjectAltName=email:my@other.address,RID:1.2.3.4
202 Issuer Alternative Name.
204 The issuer alternative name option supports all the literal options of
205 subject alternative name. It does *not* support the email:copy option because
206 that would not make sense. It does support and additional issuer:copy option
207 that will copy all the subject alternative name values from the issuer
208 certificate (if possible).
210 Display only extensions.
212 Some extensions are only partially supported and currently are only displayed
213 but cannot be set. These include private key usage period, CRL number, and