]>
Commit | Line | Data |
---|---|---|
f5904406 RE |
1 | |
2 | This is some preliminary documentation for OpenSSL. | |
3 | ||
4 | ============================================================================== | |
5 | BUFFER Library | |
6 | ============================================================================== | |
7 | ||
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.] | |
11 | ||
12 | The buffer library handles simple character arrays. Buffers are used for various | |
13 | purposes in the library, most notably memory BIOs. | |
14 | ||
15 | The library uses the BUF_MEM structure defined in buffer.h: | |
16 | ||
17 | typedef struct buf_mem_st | |
18 | { | |
19 | int length; /* current number of bytes */ | |
20 | char *data; | |
21 | int max; /* size of buffer */ | |
22 | } BUF_MEM; | |
23 | ||
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. | |
27 | ||
28 | BUF_MEM *BUF_MEM_new() | |
29 | ||
30 | This allocates a new buffer of zero size. Returns the buffer or NULL on error. | |
31 | ||
32 | void BUF_MEM_free(BUF_MEM *a) | |
33 | ||
34 | This frees up an already existing buffer. The data is zeroed before freeing | |
35 | up in case the buffer contains sensitive data. | |
36 | ||
37 | int BUF_MEM_grow(BUF_MEM *str, int len) | |
38 | ||
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 | |
41 | it increases in size. | |
42 | ||
43 | char * BUF_strdup(char *str) | |
44 | ||
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. | |
48 | ||
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. | |
52 | ||
53 | The memory allocated from BUF_strdup() should be freed up using the Free() | |
54 | function. | |
55 | ||
56 | ============================================================================== | |
57 | OpenSSL X509V3 extension configuration | |
58 | ============================================================================== | |
59 | ||
deff75b6 DSH |
60 | OpenSSL X509V3 extension configuration: preliminary documentation. |
61 | ||
62 | INTRODUCTION. | |
63 | ||
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. | |
66 | ||
67 | For more information about the meaning of extensions see: | |
68 | ||
69 | http://www.imc.org/ietf-pkix/ | |
70 | http://home.netscape.com/eng/security/certs.html | |
71 | ||
72 | PRINTING EXTENSIONS. | |
73 | ||
74 | Extension values are automatically printed out for supported extensions. | |
75 | ||
1756d405 DSH |
76 | openssl x509 -in cert.pem -text |
77 | openssl crl -in crl.pem -text | |
deff75b6 DSH |
78 | |
79 | will give information in the extension printout, for example: | |
80 | ||
81 | ||
82 | X509v3 extensions: | |
83 | X509v3 Basic Constraints: | |
84 | CA:TRUE | |
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 | |
89 | X509v3 Key Usage: | |
90 | Certificate Sign, CRL Sign | |
91 | X509v3 Subject Alternative Name: | |
92 | email:email@1.address, email:email@2.address | |
93 | ||
94 | CONFIGURATION FILES. | |
95 | ||
96 | The OpenSSL utilities 'ca' and 'req' can now have extension sections listing | |
97 | which certificate extensions to include. In each case a line: | |
98 | ||
99 | x509_extensions = extension_section | |
100 | ||
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. | |
104 | ||
1756d405 DSH |
105 | You can also add extensions to CRLs: a line |
106 | ||
107 | crl_extensions = crl_extension_section | |
108 | ||
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. | |
114 | ||
deff75b6 DSH |
115 | EXTENSION SYNTAX. |
116 | ||
117 | Extensions have the basic form: | |
118 | ||
119 | extension_name=[critical,] extension_options | |
120 | ||
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 | |
126 | with it). | |
127 | ||
128 | There are three main types of extension, string extensions, multi valued | |
129 | extensions, and raw extensions. | |
130 | ||
131 | String extensions simply have a string which defines the value of the or how | |
132 | it is obtained. | |
133 | ||
134 | For example: | |
135 | ||
136 | nsComment="This is a Comment" | |
137 | ||
138 | Multi valued extensions have a short form and a long form. The short form | |
139 | is a list of names and values: | |
140 | ||
141 | basicConstraints=critical,CA:true,pathlen:1 | |
142 | ||
143 | The long form allows the values to be placed in a separate section: | |
144 | ||
145 | basicConstraints=critical,@bs_section | |
146 | ||
147 | [bs_section] | |
148 | ||
149 | CA=true | |
150 | pathlen=1 | |
151 | ||
152 | Both forms are equivalent. However it should be noted that in some cases the | |
153 | same name can appear multiple times, for example, | |
154 | ||
155 | subjectAltName=email:steve@here,email:steve@there | |
156 | ||
157 | in this case an equivalent long form is: | |
158 | ||
159 | subjectAltName=@alt_section | |
160 | ||
161 | [alt_section] | |
162 | ||
163 | email.1=steve@here | |
164 | email.2=steve@there | |
165 | ||
166 | This is because the configuration file code cannot handle the same name | |
167 | occurring twice in the same extension. | |
168 | ||
169 | Raw extensions allow arbitrary data to be placed in an extension. For | |
170 | example | |
171 | ||
172 | 1.2.3.4=critical,RAW:01:02:03:04 | |
173 | 1.2.3.4=RAW:01020304 | |
174 | ||
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: | |
177 | ||
178 | basicConstraints=critical,RAW:00:01:02:03 | |
179 | ||
180 | WARNING: raw extensions should be used with caution. It is possible to create | |
181 | totally invalid extensions unless care is taken. | |
182 | ||
183 | CURRENTLY SUPPORTED EXTENSIONS. | |
184 | ||
185 | Literal String extensions. | |
186 | ||
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 | |
190 | nsComment. | |
191 | ||
192 | For example: | |
193 | ||
194 | nsComment="This is a test comment" | |
195 | ||
196 | Bit Strings. | |
197 | ||
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 | |
200 | nsCertType. | |
201 | ||
202 | nsCertType (netscape certificate type) takes the flags: client, server, email, | |
203 | objsign, reserved, sslCA, emailCA, objCA. | |
204 | ||
205 | keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation, | |
94c95d04 | 206 | keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, |
deff75b6 DSH |
207 | encipherOnly, decipherOnly. |
208 | ||
209 | For example: | |
210 | ||
211 | nsCertType=server | |
212 | ||
213 | keyUsage=critical, digitalSignature, nonRepudiation | |
214 | ||
215 | ||
216 | Basic Constraints. | |
217 | ||
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 | |
221 | should be omitted. | |
222 | ||
223 | Examples: | |
224 | ||
225 | basicConstraints=CA:TRUE | |
226 | basicConstraints=critical,CA:TRUE, pathlen:10 | |
227 | ||
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. | |
232 | ||
233 | Subject Key Identifier. | |
234 | ||
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. | |
239 | ||
240 | Example: subjectKeyIdentifier=hash | |
241 | ||
242 | Authority Key Identifier. | |
243 | ||
244 | The authority key identifier extension permits two options. keyid and issuer: | |
245 | both can take the optional value "always". | |
246 | ||
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. | |
250 | ||
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. | |
254 | ||
255 | Subject Alternative Name. | |
256 | ||
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). | |
261 | ||
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 | |
264 | the extension. | |
265 | ||
266 | Examples: | |
267 | ||
268 | subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/ | |
269 | subjectAltName=email:my@other.address,RID:1.2.3.4 | |
270 | ||
271 | Issuer Alternative Name. | |
272 | ||
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 | |
d943e372 | 275 | that would not make sense. It does support an additional issuer:copy option |
deff75b6 DSH |
276 | that will copy all the subject alternative name values from the issuer |
277 | certificate (if possible). | |
278 | ||
d943e372 DSH |
279 | CRL distribution points. |
280 | ||
281 | This is a multivalued extension that supports all the literal options of | |
282 | subject alternative name. Of the few software packages that currently interpret | |
283 | this extension most only interpret the URI option. | |
284 | ||
285 | Currently each option will set a new DistributionPoint with the fullName | |
286 | field set to the given value. | |
287 | ||
288 | Other fields like cRLissuer and reasons cannot currently be set or displayed: | |
289 | at this time no examples were available that used these fields. | |
290 | ||
291 | If you see this extension with <UNSUPPORTED> when you attempt to print it out | |
292 | or it doesn't appear to display correctly then let me know, including the | |
293 | certificate (mail me at steve@openssl.org) . | |
294 | ||
295 | Examples: | |
296 | ||
297 | crlDistributionPoints=URI:http://www.myhost.com/myca.crl | |
298 | crlDistributionPoints=URI:http://www.my.com/my.crl,URI:http://www.oth.com/my.crl | |
299 | ||
300 | Certificate Policies. | |
301 | ||
302 | This is a RAW extension. It attempts to display the contents of this extension: | |
303 | unfortuntately this extension is often improperly encoded. | |
304 | ||
305 | The certificate policies extension will rarely be used in practice: few | |
306 | software packages interpret it correctly or at all. | |
307 | ||
308 | All the fields of this extension can be set by using the appropriate syntax. | |
309 | ||
310 | If you follow the PKIX recommendations of not including any qualifiers and just | |
311 | using only one OID then you just include the value of that OID. Multiple OIDs | |
312 | can be set separated by commas, for example: | |
313 | ||
314 | certificatePolicies= 1.2.4.5, 1.1.3.4 | |
315 | ||
316 | If you wish to include qualifiers then the policy OID and qualifiers need to | |
317 | be specified in a separate section: this is done by using the @section syntax | |
318 | instead of a literal OID value. | |
319 | ||
320 | The section referred to must include the policy OID using the name | |
321 | policyIdentifier, cPSuri qualifiers can be included using the syntax: | |
322 | ||
323 | CPS.nnn=value | |
324 | ||
325 | userNotice qualifiers can be set using the syntax: | |
326 | ||
327 | userNotice.nnn=@notice | |
328 | ||
329 | The value of the userNotice qualifier is specified in the relevant section. This | |
330 | section can include explicitText, organization and noticeNumbers options. | |
331 | explicitText and organization are text strings, noticeNumbers is a comma | |
332 | separated list of numbers. The organization and noticeNumbers options (if | |
333 | included) must BOTH be present. | |
334 | ||
335 | Example: | |
336 | ||
337 | certificatePolicies=1.2.3.4,1.5.6.7.8,@polsect | |
338 | ||
339 | [polsect] | |
340 | ||
341 | policyIdentifier = 1.3.5.8 | |
342 | CPS.1="http://my.host.name/" | |
343 | CPS.2="http://my.your.name/" | |
344 | userNotice.1=@notice | |
345 | ||
346 | [notice] | |
347 | ||
348 | explicitText="Explicit Text Here" | |
349 | organization="Organisation Name" | |
350 | noticeNumbers=1,2,3,4 | |
351 | ||
deff75b6 DSH |
352 | Display only extensions. |
353 | ||
354 | Some extensions are only partially supported and currently are only displayed | |
355 | but cannot be set. These include private key usage period, CRL number, and | |
356 | CRL reason. | |
f5904406 | 357 |