2 This is some preliminary documentation for OpenSSL.
4 ==============================================================================
6 ==============================================================================
8 [Note: I wrote this when I saw a Malloc version of strdup() in there which
9 I'd written myself anyway. I was so annoyed at not noticing this I decided to
10 document it :-) Steve.]
12 The buffer library handles simple character arrays. Buffers are used for various
13 purposes in the library, most notably memory BIOs.
15 The library uses the BUF_MEM structure defined in buffer.h:
17 typedef struct buf_mem_st
19 int length; /* current number of bytes */
21 int max; /* size of buffer */
24 'length' is the current size of the buffer in bytes, 'max' is the amount of
25 memory allocated to the buffer. There are three functions which handle these
26 and one "miscelanous" function.
28 BUF_MEM *BUF_MEM_new()
30 This allocates a new buffer of zero size. Returns the buffer or NULL on error.
32 void BUF_MEM_free(BUF_MEM *a)
34 This frees up an already existing buffer. The data is zeroed before freeing
35 up in case the buffer contains sensitive data.
37 int BUF_MEM_grow(BUF_MEM *str, int len)
39 This changes the size of an already existing buffer. It returns zero on error
40 or the new size (i.e. 'len'). Any data already in the buffer is preserved if
43 char * BUF_strdup(char *str)
45 This is the previously mentioned strdup function: like the standard library
46 strdup() it copies a null terminated string into a block of allocated memory
47 and returns a pointer to the allocated block.
49 Unlike the standard C library strdup() this function uses Malloc() and so
50 should be used in preference to the standard library strdup() because it can
51 be used for memory leak checking or replacing the malloc() function.
53 The memory allocated from BUF_strdup() should be freed up using the Free()
56 ==============================================================================
57 OpenSSL X509V3 extension configuration
58 ==============================================================================
60 OpenSSL X509V3 extension configuration: preliminary documentation.
64 For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now
65 possible to add and print out common X509 V3 certificate and CRL extensions.
67 For more information about the meaning of extensions see:
69 http://www.imc.org/ietf-pkix/
70 http://home.netscape.com/eng/security/certs.html
74 Extension values are automatically printed out for supported extensions.
76 openssl x509 -in cert.pem -text
77 openssl crl -in crl.pem -text
79 will give information in the extension printout, for example:
83 X509v3 Basic Constraints:
85 X509v3 Subject Key Identifier:
86 73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15
87 X509v3 Authority Key Identifier:
88 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
90 Certificate Sign, CRL Sign
91 X509v3 Subject Alternative Name:
92 email:email@1.address, email:email@2.address
96 The OpenSSL utilities 'ca' and 'req' can now have extension sections listing
97 which certificate extensions to include. In each case a line:
99 x509_extensions = extension_section
101 indicates which section contains the extensions. In the case of 'req' the
102 extension section is used when the -x509 option is present to create a
103 self signed root certificate.
105 You can also add extensions to CRLs: a line
107 crl_extensions = crl_extension_section
109 will include extensions when the -gencrl option is used with the 'ca' utility.
110 You can add any extension to a CRL but of the supported extensions only
111 issuerAltName and authorityKeyIdentifier make any real sense. Note: these are
112 CRL extensions NOT CRL *entry* extensions which cannot currently be generated.
113 CRL entry extensions can be displayed.
117 Extensions have the basic form:
119 extension_name=[critical,] extension_options
121 the use of the critical option makes the extension critical. Extreme caution
122 should be made when using the critical flag. If an extension is marked
123 as critical then any client that does not understand the extension should
124 reject it as invalid. Some broken software will reject certificates which
125 have *any* critical extensions (these violates PKIX but we have to live
128 There are three main types of extension, string extensions, multi valued
129 extensions, and raw extensions.
131 String extensions simply have a string which defines the value of the or how
136 nsComment="This is a Comment"
138 Multi valued extensions have a short form and a long form. The short form
139 is a list of names and values:
141 basicConstraints=critical,CA:true,pathlen:1
143 The long form allows the values to be placed in a separate section:
145 basicConstraints=critical,@bs_section
152 Both forms are equivalent. However it should be noted that in some cases the
153 same name can appear multiple times, for example,
155 subjectAltName=email:steve@here,email:steve@there
157 in this case an equivalent long form is:
159 subjectAltName=@alt_section
166 This is because the configuration file code cannot handle the same name
167 occurring twice in the same extension.
169 Raw extensions allow arbitrary data to be placed in an extension. For
172 1.2.3.4=critical,RAW:01:02:03:04
175 The value following RAW is a hex dump of the extension contents. Any extension
176 can be placed in this form to override the default behaviour. For example:
178 basicConstraints=critical,RAW:00:01:02:03
180 WARNING: raw extensions should be used with caution. It is possible to create
181 totally invalid extensions unless care is taken.
183 CURRENTLY SUPPORTED EXTENSIONS.
185 Literal String extensions.
187 In each case the 'value' of the extension is placed directly in the extension.
188 Currently supported extensions in this category are: nsBaseUrl, nsRevocationUrl
189 nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, nsSslServerName and
194 nsComment="This is a test comment"
198 Bit string extensions just consist of a list of suppported bits, currently
199 two extensions are in this category: PKIX keyUsage and the Netscape specific
202 nsCertType (netscape certificate type) takes the flags: client, server, email,
203 objsign, reserved, sslCA, emailCA, objCA.
205 keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation,
206 keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLCertSign,
207 encipherOnly, decipherOnly.
213 keyUsage=critical, digitalSignature, nonRepudiation
218 Basic constraints is a multi valued extension that supports a CA and an
219 optional pathlen option. The CA option takes the values true and false and
220 pathlen takes an integer. Note if the CA option is false the pathlen option
225 basicConstraints=CA:TRUE
226 basicConstraints=critical,CA:TRUE, pathlen:10
228 NOTE: for a CA to be considered valid it must have the CA option set to
229 TRUE. An end user certificate MUST NOT have the CA value set to true.
230 According to PKIX recommendations it should exclude the extension entirely
231 however some software may require CA set to FALSE for end entity certificates.
233 Subject Key Identifier.
235 This is really a string extension and can take two possible values. Either
236 a hex string giving details of the extension value to include or the word
237 'hash' which then automatically follow PKIX guidelines in selecting and
238 appropriate key identifier. The use of the hex string is strongly discouraged.
240 Example: subjectKeyIdentifier=hash
242 Authority Key Identifier.
244 The authority key identifier extension permits two options. keyid and issuer:
245 both can take the optional value "always".
247 If the keyid option is present an attempt is made to copy the subject key
248 identifier from the parent certificate. If the value "always" is present
249 then an error is returned if the option fails.
251 The issuer option copies the issuer and serial number from the issuer
252 certificate. Normally this will only be done if the keyid option fails or
253 is not included: the "always" flag will always include the value.
255 Subject Alternative Name.
257 The subject alternative name extension allows various literal values to be
258 included in the configuration file. These include "email" (an email address)
259 "URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a
260 registered ID: OBJECT IDENTIFIER) and IP (and IP address).
262 Also the email option include a special 'copy' value. This will automatically
263 include and email addresses contained in the certificate subject name in
268 subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/
269 subjectAltName=email:my@other.address,RID:1.2.3.4
271 Issuer Alternative Name.
273 The issuer alternative name option supports all the literal options of
274 subject alternative name. It does *not* support the email:copy option because
275 that would not make sense. It does support and additional issuer:copy option
276 that will copy all the subject alternative name values from the issuer
277 certificate (if possible).
279 Display only extensions.
281 Some extensions are only partially supported and currently are only displayed
282 but cannot be set. These include private key usage period, CRL number, and