]>
Commit | Line | Data |
---|---|---|
f5904406 RE |
1 | |
2 | This is some preliminary documentation for OpenSSL. | |
3 | ||
c1ce32f1 UM |
4 | Contents: |
5 | ||
6 | OpenSSL X509V3 extension configuration | |
7 | X509V3 Extension code: programmers guide | |
8 | PKCS#12 Library | |
9 | ||
10 | ||
f5904406 RE |
11 | ============================================================================== |
12 | OpenSSL X509V3 extension configuration | |
13 | ============================================================================== | |
14 | ||
deff75b6 DSH |
15 | OpenSSL X509V3 extension configuration: preliminary documentation. |
16 | ||
17 | INTRODUCTION. | |
18 | ||
19 | For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now | |
20 | possible to add and print out common X509 V3 certificate and CRL extensions. | |
21 | ||
257e206d DSH |
22 | BEGINNERS NOTE |
23 | ||
24 | For most simple applications you don't need to know too much about extensions: | |
25 | the default openssl.cnf values will usually do sensible things. | |
26 | ||
27 | If you want to know more you can initially quickly look through the sections | |
28 | describing how the standard OpenSSL utilities display and add extensions and | |
29 | then the list of supported extensions. | |
30 | ||
31 | For more technical information about the meaning of extensions see: | |
deff75b6 DSH |
32 | |
33 | http://www.imc.org/ietf-pkix/ | |
34 | http://home.netscape.com/eng/security/certs.html | |
35 | ||
36 | PRINTING EXTENSIONS. | |
37 | ||
38 | Extension values are automatically printed out for supported extensions. | |
39 | ||
1756d405 DSH |
40 | openssl x509 -in cert.pem -text |
41 | openssl crl -in crl.pem -text | |
deff75b6 DSH |
42 | |
43 | will give information in the extension printout, for example: | |
44 | ||
deff75b6 DSH |
45 | X509v3 extensions: |
46 | X509v3 Basic Constraints: | |
47 | CA:TRUE | |
48 | X509v3 Subject Key Identifier: | |
49 | 73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15 | |
50 | X509v3 Authority Key Identifier: | |
51 | 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 | |
52 | X509v3 Key Usage: | |
53 | Certificate Sign, CRL Sign | |
54 | X509v3 Subject Alternative Name: | |
55 | email:email@1.address, email:email@2.address | |
56 | ||
57 | CONFIGURATION FILES. | |
58 | ||
59 | The OpenSSL utilities 'ca' and 'req' can now have extension sections listing | |
60 | which certificate extensions to include. In each case a line: | |
61 | ||
62 | x509_extensions = extension_section | |
63 | ||
64 | indicates which section contains the extensions. In the case of 'req' the | |
65 | extension section is used when the -x509 option is present to create a | |
66 | self signed root certificate. | |
67 | ||
e40b7abe | 68 | The 'x509' utility also supports extensions when it signs a certificate. |
3f45ed82 | 69 | The -extfile option is used to set the configuration file containing the |
e40b7abe DSH |
70 | extensions. In this case a line with: |
71 | ||
72 | extensions = extension_section | |
73 | ||
703126f0 | 74 | in the nameless (default) section is used. If no such line is included then |
e40b7abe DSH |
75 | it uses the default section. |
76 | ||
1756d405 DSH |
77 | You can also add extensions to CRLs: a line |
78 | ||
79 | crl_extensions = crl_extension_section | |
80 | ||
81 | will include extensions when the -gencrl option is used with the 'ca' utility. | |
82 | You can add any extension to a CRL but of the supported extensions only | |
83 | issuerAltName and authorityKeyIdentifier make any real sense. Note: these are | |
84 | CRL extensions NOT CRL *entry* extensions which cannot currently be generated. | |
85 | CRL entry extensions can be displayed. | |
86 | ||
e40b7abe | 87 | NB. At this time Netscape Communicator rejects V2 CRLs: to get an old V1 CRL |
257e206d | 88 | you should not include a crl_extensions line in the configuration file. |
e40b7abe DSH |
89 | |
90 | As with all configuration files you can use the inbuilt environment expansion | |
91 | to allow the values to be passed in the environment. Therefore if you have | |
92 | several extension sections used for different purposes you can have a line: | |
93 | ||
94 | x509_extensions = $ENV::ENV_EXT | |
95 | ||
96 | and set the ENV_EXT environment variable before calling the relevant utility. | |
97 | ||
deff75b6 DSH |
98 | EXTENSION SYNTAX. |
99 | ||
100 | Extensions have the basic form: | |
101 | ||
102 | extension_name=[critical,] extension_options | |
103 | ||
104 | the use of the critical option makes the extension critical. Extreme caution | |
105 | should be made when using the critical flag. If an extension is marked | |
106 | as critical then any client that does not understand the extension should | |
107 | reject it as invalid. Some broken software will reject certificates which | |
108 | have *any* critical extensions (these violates PKIX but we have to live | |
109 | with it). | |
110 | ||
33d50ef6 | 111 | There are three main types of extension: string extensions, multi-valued |
deff75b6 DSH |
112 | extensions, and raw extensions. |
113 | ||
703126f0 DSH |
114 | String extensions simply have a string which contains either the value itself |
115 | or how it is obtained. | |
deff75b6 DSH |
116 | |
117 | For example: | |
118 | ||
119 | nsComment="This is a Comment" | |
120 | ||
33d50ef6 | 121 | Multi-valued extensions have a short form and a long form. The short form |
deff75b6 DSH |
122 | is a list of names and values: |
123 | ||
124 | basicConstraints=critical,CA:true,pathlen:1 | |
125 | ||
126 | The long form allows the values to be placed in a separate section: | |
127 | ||
128 | basicConstraints=critical,@bs_section | |
129 | ||
130 | [bs_section] | |
131 | ||
132 | CA=true | |
133 | pathlen=1 | |
134 | ||
135 | Both forms are equivalent. However it should be noted that in some cases the | |
136 | same name can appear multiple times, for example, | |
137 | ||
138 | subjectAltName=email:steve@here,email:steve@there | |
139 | ||
140 | in this case an equivalent long form is: | |
141 | ||
142 | subjectAltName=@alt_section | |
143 | ||
144 | [alt_section] | |
145 | ||
146 | email.1=steve@here | |
147 | email.2=steve@there | |
148 | ||
149 | This is because the configuration file code cannot handle the same name | |
87c49f62 | 150 | occurring twice in the same section. |
deff75b6 | 151 | |
703126f0 DSH |
152 | The syntax of raw extensions is governed by the extension code: it can |
153 | for example contain data in multiple sections. The correct syntax to | |
154 | use is defined by the extension code itself: check out the certificate | |
155 | policies extension for an example. | |
deff75b6 | 156 | |
04f0a6ba DSH |
157 | There are two ways to encode arbitrary extensions. |
158 | ||
159 | The first way is to use the word ASN1 followed by the extension content | |
160 | using the same syntax as ASN1_generate_nconf(). For example: | |
161 | ||
162 | 1.2.3.4=critical,ASN1:UTF8String:Some random data | |
163 | ||
164 | 1.2.3.4=ASN1:SEQUENCE:seq_sect | |
165 | ||
166 | [seq_sect] | |
167 | ||
168 | field1 = UTF8:field1 | |
169 | field2 = UTF8:field2 | |
170 | ||
171 | It is also possible to use the word DER to include arbitrary data in any | |
172 | extension. | |
deff75b6 | 173 | |
703126f0 DSH |
174 | 1.2.3.4=critical,DER:01:02:03:04 |
175 | 1.2.3.4=DER:01020304 | |
deff75b6 | 176 | |
703126f0 DSH |
177 | The value following DER is a hex dump of the DER encoding of the extension |
178 | Any extension can be placed in this form to override the default behaviour. | |
179 | For example: | |
180 | ||
181 | basicConstraints=critical,DER:00:01:02:03 | |
deff75b6 | 182 | |
703126f0 DSH |
183 | WARNING: DER should be used with caution. It is possible to create totally |
184 | invalid extensions unless care is taken. | |
deff75b6 DSH |
185 | |
186 | CURRENTLY SUPPORTED EXTENSIONS. | |
187 | ||
257e206d DSH |
188 | If you aren't sure about extensions then they can be largely ignored: its only |
189 | when you want to do things like restrict certificate usage when you need to | |
190 | worry about them. | |
191 | ||
192 | The only extension that a beginner might want to look at is Basic Constraints. | |
193 | If in addition you want to try Netscape object signing the you should also | |
194 | look at Netscape Certificate Type. | |
195 | ||
deff75b6 DSH |
196 | Literal String extensions. |
197 | ||
b975f15d BM |
198 | In each case the 'value' of the extension is placed directly in the |
199 | extension. Currently supported extensions in this category are: nsBaseUrl, | |
200 | nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, | |
201 | nsSslServerName and nsComment. | |
deff75b6 DSH |
202 | |
203 | For example: | |
204 | ||
205 | nsComment="This is a test comment" | |
206 | ||
207 | Bit Strings. | |
208 | ||
33d50ef6 | 209 | Bit string extensions just consist of a list of supported bits, currently |
deff75b6 DSH |
210 | two extensions are in this category: PKIX keyUsage and the Netscape specific |
211 | nsCertType. | |
212 | ||
213 | nsCertType (netscape certificate type) takes the flags: client, server, email, | |
214 | objsign, reserved, sslCA, emailCA, objCA. | |
215 | ||
216 | keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation, | |
94c95d04 | 217 | keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, |
deff75b6 DSH |
218 | encipherOnly, decipherOnly. |
219 | ||
220 | For example: | |
221 | ||
222 | nsCertType=server | |
223 | ||
257e206d DSH |
224 | keyUsage=digitalSignature, nonRepudiation |
225 | ||
226 | Hints on Netscape Certificate Type. | |
227 | ||
228 | Other than Basic Constraints this is the only extension a beginner might | |
229 | want to use, if you want to try Netscape object signing, otherwise it can | |
230 | be ignored. | |
231 | ||
232 | If you want a certificate that can be used just for object signing then: | |
233 | ||
234 | nsCertType=objsign | |
235 | ||
236 | will do the job. If you want to use it as a normal end user and server | |
237 | certificate as well then | |
238 | ||
239 | nsCertType=objsign,email,server | |
deff75b6 | 240 | |
257e206d DSH |
241 | is more appropriate. You cannot use a self signed certificate for object |
242 | signing (well Netscape signtool can but it cheats!) so you need to create | |
243 | a CA certificate and sign an end user certificate with it. | |
244 | ||
245 | Side note: If you want to conform to the Netscape specifications then you | |
246 | should really also set: | |
247 | ||
248 | nsCertType=objCA | |
249 | ||
250 | in the *CA* certificate for just an object signing CA and | |
251 | ||
252 | nsCertType=objCA,emailCA,sslCA | |
253 | ||
254 | for everything. Current Netscape software doesn't enforce this so it can | |
255 | be omitted. | |
deff75b6 DSH |
256 | |
257 | Basic Constraints. | |
258 | ||
257e206d DSH |
259 | This is generally the only extension you need to worry about for simple |
260 | applications. If you want your certificate to be usable as a CA certificate | |
261 | (in addition to an end user certificate) then you set this to: | |
262 | ||
263 | basicConstraints=CA:TRUE | |
264 | ||
265 | if you want to be certain the certificate cannot be used as a CA then do: | |
266 | ||
267 | basicConstraints=CA:FALSE | |
268 | ||
269 | The rest of this section describes more advanced usage. | |
270 | ||
33d50ef6 | 271 | Basic constraints is a multi-valued extension that supports a CA and an |
deff75b6 DSH |
272 | optional pathlen option. The CA option takes the values true and false and |
273 | pathlen takes an integer. Note if the CA option is false the pathlen option | |
257e206d DSH |
274 | should be omitted. |
275 | ||
276 | The pathlen parameter indicates the maximum number of CAs that can appear | |
277 | below this one in a chain. So if you have a CA with a pathlen of zero it can | |
278 | only be used to sign end user certificates and not further CAs. This all | |
279 | assumes that the software correctly interprets this extension of course. | |
deff75b6 DSH |
280 | |
281 | Examples: | |
282 | ||
283 | basicConstraints=CA:TRUE | |
257e206d | 284 | basicConstraints=critical,CA:TRUE, pathlen:0 |
deff75b6 DSH |
285 | |
286 | NOTE: for a CA to be considered valid it must have the CA option set to | |
287 | TRUE. An end user certificate MUST NOT have the CA value set to true. | |
b64f8256 | 288 | According to PKIX recommendations it should exclude the extension entirely, |
deff75b6 DSH |
289 | however some software may require CA set to FALSE for end entity certificates. |
290 | ||
87c49f62 DSH |
291 | Extended Key Usage. |
292 | ||
293 | This extensions consists of a list of usages. | |
294 | ||
295 | These can either be object short names of the dotted numerical form of OIDs. | |
1f2f9224 | 296 | While any OID can be used only certain values make sense. In particular the |
87c49f62 DSH |
297 | following PKIX, NS and MS values are meaningful: |
298 | ||
299 | Value Meaning | |
300 | ----- ------- | |
301 | serverAuth SSL/TLS Web Server Authentication. | |
302 | clientAuth SSL/TLS Web Client Authentication. | |
303 | codeSigning Code signing. | |
304 | emailProtection E-mail Protection (S/MIME). | |
305 | timeStamping Trusted Timestamping | |
306 | msCodeInd Microsoft Individual Code Signing (authenticode) | |
307 | msCodeCom Microsoft Commercial Code Signing (authenticode) | |
308 | msCTLSign Microsoft Trust List Signing | |
309 | msSGC Microsoft Server Gated Crypto | |
310 | msEFS Microsoft Encrypted File System | |
311 | nsSGC Netscape Server Gated Crypto | |
312 | ||
313 | For example, under IE5 a CA can be used for any purpose: by including a list | |
314 | of the above usages the CA can be restricted to only authorised uses. | |
315 | ||
316 | Note: software packages may place additional interpretations on certificate | |
317 | use, in particular some usages may only work for selected CAs. Don't for example | |
318 | expect just including msSGC or nsSGC will automatically mean that a certificate | |
319 | can be used for SGC ("step up" encryption) otherwise anyone could use it. | |
320 | ||
f769ce3e DSH |
321 | Examples: |
322 | ||
323 | extendedKeyUsage=critical,codeSigning,1.2.3.4 | |
324 | extendedKeyUsage=nsSGC,msSGC | |
325 | ||
deff75b6 DSH |
326 | Subject Key Identifier. |
327 | ||
328 | This is really a string extension and can take two possible values. Either | |
329 | a hex string giving details of the extension value to include or the word | |
330 | 'hash' which then automatically follow PKIX guidelines in selecting and | |
331 | appropriate key identifier. The use of the hex string is strongly discouraged. | |
332 | ||
333 | Example: subjectKeyIdentifier=hash | |
334 | ||
335 | Authority Key Identifier. | |
336 | ||
337 | The authority key identifier extension permits two options. keyid and issuer: | |
338 | both can take the optional value "always". | |
339 | ||
340 | If the keyid option is present an attempt is made to copy the subject key | |
341 | identifier from the parent certificate. If the value "always" is present | |
342 | then an error is returned if the option fails. | |
343 | ||
344 | The issuer option copies the issuer and serial number from the issuer | |
345 | certificate. Normally this will only be done if the keyid option fails or | |
346 | is not included: the "always" flag will always include the value. | |
347 | ||
348 | Subject Alternative Name. | |
349 | ||
350 | The subject alternative name extension allows various literal values to be | |
351 | included in the configuration file. These include "email" (an email address) | |
352 | "URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a | |
04f0a6ba | 353 | registered ID: OBJECT IDENTIFIER), IP (and IP address) and otherName. |
deff75b6 DSH |
354 | |
355 | Also the email option include a special 'copy' value. This will automatically | |
356 | include and email addresses contained in the certificate subject name in | |
357 | the extension. | |
358 | ||
04f0a6ba DSH |
359 | otherName can include arbitrary data associated with an OID: the value |
360 | should be the OID followed by a semicolon and the content in standard | |
361 | ASN1_generate_nconf() format. | |
362 | ||
deff75b6 DSH |
363 | Examples: |
364 | ||
3403caf3 | 365 | subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/ |
deff75b6 | 366 | subjectAltName=email:my@other.address,RID:1.2.3.4 |
04f0a6ba | 367 | subjectAltName=otherName:1.2.3.4;UTF8:some other identifier |
deff75b6 DSH |
368 | |
369 | Issuer Alternative Name. | |
370 | ||
371 | The issuer alternative name option supports all the literal options of | |
372 | subject alternative name. It does *not* support the email:copy option because | |
d943e372 | 373 | that would not make sense. It does support an additional issuer:copy option |
deff75b6 DSH |
374 | that will copy all the subject alternative name values from the issuer |
375 | certificate (if possible). | |
376 | ||
c5a3b7e7 DSH |
377 | Example: |
378 | ||
379 | issuserAltName = issuer:copy | |
380 | ||
381 | Authority Info Access. | |
382 | ||
383 | The authority information access extension gives details about how to access | |
384 | certain information relating to the CA. Its syntax is accessOID;location | |
385 | where 'location' has the same syntax as subject alternative name (except | |
386 | that email:copy is not supported). accessOID can be any valid OID but only | |
387 | certain values are meaningful for example OCSP and caIssuers. OCSP gives the | |
388 | location of an OCSP responder: this is used by Netscape PSM and other software. | |
389 | ||
390 | Example: | |
391 | ||
392 | authorityInfoAccess = OCSP;URI:http://ocsp.my.host/ | |
393 | authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html | |
394 | ||
d943e372 DSH |
395 | CRL distribution points. |
396 | ||
33d50ef6 | 397 | This is a multi-valued extension that supports all the literal options of |
d943e372 DSH |
398 | subject alternative name. Of the few software packages that currently interpret |
399 | this extension most only interpret the URI option. | |
400 | ||
401 | Currently each option will set a new DistributionPoint with the fullName | |
402 | field set to the given value. | |
403 | ||
404 | Other fields like cRLissuer and reasons cannot currently be set or displayed: | |
405 | at this time no examples were available that used these fields. | |
406 | ||
407 | If you see this extension with <UNSUPPORTED> when you attempt to print it out | |
408 | or it doesn't appear to display correctly then let me know, including the | |
409 | certificate (mail me at steve@openssl.org) . | |
410 | ||
411 | Examples: | |
412 | ||
413 | crlDistributionPoints=URI:http://www.myhost.com/myca.crl | |
414 | crlDistributionPoints=URI:http://www.my.com/my.crl,URI:http://www.oth.com/my.crl | |
415 | ||
416 | Certificate Policies. | |
417 | ||
418 | This is a RAW extension. It attempts to display the contents of this extension: | |
33d50ef6 | 419 | unfortunately this extension is often improperly encoded. |
d943e372 DSH |
420 | |
421 | The certificate policies extension will rarely be used in practice: few | |
e40b7abe DSH |
422 | software packages interpret it correctly or at all. IE5 does partially |
423 | support this extension: but it needs the 'ia5org' option because it will | |
424 | only correctly support a broken encoding. Of the options below only the | |
425 | policy OID, explicitText and CPS options are displayed with IE5. | |
d943e372 DSH |
426 | |
427 | All the fields of this extension can be set by using the appropriate syntax. | |
428 | ||
429 | If you follow the PKIX recommendations of not including any qualifiers and just | |
430 | using only one OID then you just include the value of that OID. Multiple OIDs | |
431 | can be set separated by commas, for example: | |
432 | ||
433 | certificatePolicies= 1.2.4.5, 1.1.3.4 | |
434 | ||
435 | If you wish to include qualifiers then the policy OID and qualifiers need to | |
436 | be specified in a separate section: this is done by using the @section syntax | |
437 | instead of a literal OID value. | |
438 | ||
439 | The section referred to must include the policy OID using the name | |
440 | policyIdentifier, cPSuri qualifiers can be included using the syntax: | |
441 | ||
442 | CPS.nnn=value | |
443 | ||
444 | userNotice qualifiers can be set using the syntax: | |
445 | ||
446 | userNotice.nnn=@notice | |
447 | ||
b975f15d BM |
448 | The value of the userNotice qualifier is specified in the relevant section. |
449 | This section can include explicitText, organization and noticeNumbers | |
450 | options. explicitText and organization are text strings, noticeNumbers is a | |
451 | comma separated list of numbers. The organization and noticeNumbers options | |
452 | (if included) must BOTH be present. If you use the userNotice option with IE5 | |
453 | then you need the 'ia5org' option at the top level to modify the encoding: | |
454 | otherwise it will not be interpreted properly. | |
d943e372 DSH |
455 | |
456 | Example: | |
457 | ||
e40b7abe | 458 | certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect |
d943e372 DSH |
459 | |
460 | [polsect] | |
461 | ||
462 | policyIdentifier = 1.3.5.8 | |
463 | CPS.1="http://my.host.name/" | |
464 | CPS.2="http://my.your.name/" | |
465 | userNotice.1=@notice | |
466 | ||
467 | [notice] | |
468 | ||
469 | explicitText="Explicit Text Here" | |
470 | organization="Organisation Name" | |
471 | noticeNumbers=1,2,3,4 | |
472 | ||
e40b7abe DSH |
473 | TECHNICAL NOTE: the ia5org option changes the type of the 'organization' field, |
474 | according to PKIX it should be of type DisplayText but Verisign uses an | |
475 | IA5STRING and IE5 needs this too. | |
476 | ||
deff75b6 DSH |
477 | Display only extensions. |
478 | ||
479 | Some extensions are only partially supported and currently are only displayed | |
480 | but cannot be set. These include private key usage period, CRL number, and | |
481 | CRL reason. | |
f5904406 | 482 | |
565d1065 DSH |
483 | ============================================================================== |
484 | X509V3 Extension code: programmers guide | |
485 | ============================================================================== | |
486 | ||
487 | The purpose of the extension code is twofold. It allows an extension to be | |
488 | created from a string or structure describing its contents and it prints out an | |
489 | extension in a human or machine readable form. | |
490 | ||
491 | 1. Initialisation and cleanup. | |
492 | ||
21131f00 DSH |
493 | No special initialisation is needed before calling the extension functions. |
494 | You used to have to call X509V3_add_standard_extensions(); but this is no longer | |
495 | required and this function no longer does anything. | |
565d1065 DSH |
496 | |
497 | void X509V3_EXT_cleanup(void); | |
498 | ||
21131f00 DSH |
499 | This function should be called to cleanup the extension code if any custom |
500 | extensions have been added. If no custom extensions have been added then this | |
501 | call does nothing. After this call all custom extension code is freed up but | |
502 | you can still use the standard extensions. | |
565d1065 DSH |
503 | |
504 | 2. Printing and parsing extensions. | |
505 | ||
506 | The simplest way to print out extensions is via the standard X509 printing | |
507 | routines: if you use the standard X509_print() function, the supported | |
508 | extensions will be printed out automatically. | |
509 | ||
510 | The following functions allow finer control over extension display: | |
511 | ||
512 | int X509V3_EXT_print(BIO *out, X509_EXTENSION *ext, int flag, int indent); | |
513 | int X509V3_EXT_print_fp(FILE *out, X509_EXTENSION *ext, int flag, int indent); | |
514 | ||
515 | These two functions print out an individual extension to a BIO or FILE pointer. | |
516 | Currently the flag argument is unused and should be set to 0. The 'indent' | |
517 | argument is the number of spaces to indent each line. | |
518 | ||
519 | void *X509V3_EXT_d2i(X509_EXTENSION *ext); | |
520 | ||
521 | This function parses an extension and returns its internal structure. The | |
522 | precise structure you get back depends on the extension being parsed. If the | |
523 | extension if basicConstraints you will get back a pointer to a | |
524 | BASIC_CONSTRAINTS structure. Check out the source in crypto/x509v3 for more | |
525 | details about the structures returned. The returned structure should be freed | |
526 | after use using the relevant free function, BASIC_CONSTRAINTS_free() for | |
527 | example. | |
528 | ||
4e87e05b DSH |
529 | void * X509_get_ext_d2i(X509 *x, int nid, int *crit, int *idx); |
530 | void * X509_CRL_get_ext_d2i(X509_CRL *x, int nid, int *crit, int *idx); | |
531 | void * X509_REVOKED_get_ext_d2i(X509_REVOKED *x, int nid, int *crit, int *idx); | |
532 | void * X509V3_get_d2i(STACK_OF(X509_EXTENSION) *x, int nid, int *crit, int *idx); | |
533 | ||
534 | These functions combine the operations of searching for extensions and | |
535 | parsing them. They search a certificate, a CRL a CRL entry or a stack | |
536 | of extensions respectively for extension whose NID is 'nid' and return | |
537 | the parsed result of NULL if an error occurred. For example: | |
538 | ||
539 | BASIC_CONSTRAINTS *bs; | |
540 | bs = X509_get_ext_d2i(cert, NID_basic_constraints, NULL, NULL); | |
541 | ||
542 | This will search for the basicConstraints extension and either return | |
543 | it value or NULL. NULL can mean either the extension was not found, it | |
544 | occurred more than once or it could not be parsed. | |
545 | ||
546 | If 'idx' is NULL then an extension is only parsed if it occurs precisely | |
547 | once. This is standard behaviour because extensions normally cannot occur | |
548 | more than once. If however more than one extension of the same type can | |
549 | occur it can be used to parse successive extensions for example: | |
550 | ||
551 | int i; | |
552 | void *ext; | |
553 | ||
554 | i = -1; | |
555 | for(;;) { | |
556 | ext = X509_get_ext_d2i(x, nid, crit, &idx); | |
557 | if(ext == NULL) break; | |
558 | /* Do something with ext */ | |
559 | } | |
560 | ||
561 | If 'crit' is not NULL and the extension was found then the int it points to | |
562 | is set to 1 for critical extensions and 0 for non critical. Therefore if the | |
563 | function returns NULL but 'crit' is set to 0 or 1 then the extension was | |
564 | found but it could not be parsed. | |
565 | ||
566 | The int pointed to by crit will be set to -1 if the extension was not found | |
567 | and -2 if the extension occurred more than once (this will only happen if | |
568 | idx is NULL). In both cases the function will return NULL. | |
569 | ||
565d1065 DSH |
570 | 3. Generating extensions. |
571 | ||
572 | An extension will typically be generated from a configuration file, or some | |
573 | other kind of configuration database. | |
574 | ||
575 | int X509V3_EXT_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section, | |
576 | X509 *cert); | |
577 | int X509V3_EXT_CRL_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section, | |
578 | X509_CRL *crl); | |
579 | ||
580 | These functions add all the extensions in the given section to the given | |
581 | certificate or CRL. They will normally be called just before the certificate | |
582 | or CRL is due to be signed. Both return 0 on error on non zero for success. | |
583 | ||
584 | In each case 'conf' is the LHASH pointer of the configuration file to use | |
585 | and 'section' is the section containing the extension details. | |
586 | ||
1f2f9224 | 587 | See the 'context functions' section for a description of the ctx parameter. |
565d1065 DSH |
588 | |
589 | ||
590 | X509_EXTENSION *X509V3_EXT_conf(LHASH *conf, X509V3_CTX *ctx, char *name, | |
591 | char *value); | |
592 | ||
593 | This function returns an extension based on a name and value pair, if the | |
594 | pair will not need to access other sections in a config file (or there is no | |
595 | config file) then the 'conf' parameter can be set to NULL. | |
596 | ||
597 | X509_EXTENSION *X509V3_EXT_conf_nid(char *conf, X509V3_CTX *ctx, int nid, | |
598 | char *value); | |
599 | ||
600 | This function creates an extension in the same way as X509V3_EXT_conf() but | |
601 | takes the NID of the extension rather than its name. | |
602 | ||
603 | For example to produce basicConstraints with the CA flag and a path length of | |
604 | 10: | |
605 | ||
fd520577 | 606 | x = X509V3_EXT_conf_nid(NULL, NULL, NID_basic_constraints,"CA:TRUE,pathlen:10"); |
565d1065 DSH |
607 | |
608 | ||
609 | X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc); | |
610 | ||
611 | This function sets up an extension from its internal structure. The ext_nid | |
612 | parameter is the NID of the extension and 'crit' is the critical flag. | |
613 | ||
614 | 4. Context functions. | |
615 | ||
616 | The following functions set and manipulate an extension context structure. | |
617 | The purpose of the extension context is to allow the extension code to | |
618 | access various structures relating to the "environment" of the certificate: | |
619 | for example the issuers certificate or the certificate request. | |
620 | ||
621 | void X509V3_set_ctx(X509V3_CTX *ctx, X509 *issuer, X509 *subject, | |
622 | X509_REQ *req, X509_CRL *crl, int flags); | |
623 | ||
624 | This function sets up an X509V3_CTX structure with details of the certificate | |
625 | environment: specifically the issuers certificate, the subject certificate, | |
626 | the certificate request and the CRL: if these are not relevant or not | |
627 | available then they can be set to NULL. The 'flags' parameter should be set | |
628 | to zero. | |
629 | ||
630 | X509V3_set_ctx_test(ctx) | |
631 | ||
632 | This macro is used to set the 'ctx' structure to a 'test' value: this is to | |
633 | allow the syntax of an extension (or configuration file) to be tested. | |
634 | ||
635 | X509V3_set_ctx_nodb(ctx) | |
636 | ||
637 | This macro is used when no configuration database is present. | |
638 | ||
639 | void X509V3_set_conf_lhash(X509V3_CTX *ctx, LHASH *lhash); | |
640 | ||
641 | This function is used to set the configuration database when it is an LHASH | |
642 | structure: typically a configuration file. | |
643 | ||
644 | The following functions are used to access a configuration database: they | |
645 | should only be used in RAW extensions. | |
646 | ||
647 | char * X509V3_get_string(X509V3_CTX *ctx, char *name, char *section); | |
648 | ||
649 | This function returns the value of the parameter "name" in "section", or NULL | |
650 | if there has been an error. | |
651 | ||
652 | void X509V3_string_free(X509V3_CTX *ctx, char *str); | |
653 | ||
654 | This function frees up the string returned by the above function. | |
655 | ||
66ab08b1 | 656 | STACK_OF(CONF_VALUE) * X509V3_get_section(X509V3_CTX *ctx, char *section); |
565d1065 | 657 | |
66ab08b1 | 658 | This function returns a whole section as a STACK_OF(CONF_VALUE) . |
565d1065 | 659 | |
66ab08b1 | 660 | void X509V3_section_free( X509V3_CTX *ctx, STACK_OF(CONF_VALUE) *section); |
565d1065 DSH |
661 | |
662 | This function frees up the STACK returned by the above function. | |
663 | ||
664 | Note: it is possible to use the extension code with a custom configuration | |
665 | database. To do this the "db_meth" element of the X509V3_CTX structure should | |
666 | be set to an X509V3_CTX_METHOD structure. This structure contains the following | |
667 | function pointers: | |
668 | ||
669 | char * (*get_string)(void *db, char *section, char *value); | |
66ab08b1 | 670 | STACK_OF(CONF_VALUE) * (*get_section)(void *db, char *section); |
565d1065 | 671 | void (*free_string)(void *db, char * string); |
66ab08b1 | 672 | void (*free_section)(void *db, STACK_OF(CONF_VALUE) *section); |
565d1065 DSH |
673 | |
674 | these will be called and passed the 'db' element in the X509V3_CTX structure | |
675 | to access the database. If a given function is not implemented or not required | |
676 | it can be set to NULL. | |
677 | ||
678 | 5. String helper functions. | |
679 | ||
680 | There are several "i2s" and "s2i" functions that convert structures to and | |
681 | from ASCII strings. In all the "i2s" cases the returned string should be | |
682 | freed using Free() after use. Since some of these are part of other extension | |
683 | code they may take a 'method' parameter. Unless otherwise stated it can be | |
684 | safely set to NULL. | |
685 | ||
686 | char *i2s_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, ASN1_OCTET_STRING *oct); | |
687 | ||
688 | This returns a hex string from an ASN1_OCTET_STRING. | |
689 | ||
690 | char * i2s_ASN1_INTEGER(X509V3_EXT_METHOD *meth, ASN1_INTEGER *aint); | |
691 | char * i2s_ASN1_ENUMERATED(X509V3_EXT_METHOD *meth, ASN1_ENUMERATED *aint); | |
692 | ||
693 | These return a string decimal representations of an ASN1_INTEGER and an | |
694 | ASN1_ENUMERATED type, respectively. | |
695 | ||
696 | ASN1_OCTET_STRING *s2i_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, | |
697 | X509V3_CTX *ctx, char *str); | |
698 | ||
699 | This converts an ASCII hex string to an ASN1_OCTET_STRING. | |
700 | ||
701 | ASN1_INTEGER * s2i_ASN1_INTEGER(X509V3_EXT_METHOD *meth, char *value); | |
702 | ||
703 | This converts a decimal ASCII string into an ASN1_INTEGER. | |
704 | ||
705 | 6. Multi valued extension helper functions. | |
706 | ||
707 | The following functions can be used to manipulate STACKs of CONF_VALUE | |
708 | structures, as used by multi valued extensions. | |
709 | ||
710 | int X509V3_get_value_bool(CONF_VALUE *value, int *asn1_bool); | |
711 | ||
712 | This function expects a boolean value in 'value' and sets 'asn1_bool' to | |
713 | it. That is it sets it to 0 for FALSE or 0xff for TRUE. The following | |
714 | strings are acceptable: "TRUE", "true", "Y", "y", "YES", "yes", "FALSE" | |
715 | "false", "N", "n", "NO" or "no". | |
716 | ||
717 | int X509V3_get_value_int(CONF_VALUE *value, ASN1_INTEGER **aint); | |
718 | ||
719 | This accepts a decimal integer of arbitrary length and sets an ASN1_INTEGER. | |
720 | ||
66ab08b1 DSH |
721 | int X509V3_add_value(const char *name, const char *value, |
722 | STACK_OF(CONF_VALUE) **extlist); | |
565d1065 DSH |
723 | |
724 | This simply adds a string name and value pair. | |
725 | ||
726 | int X509V3_add_value_uchar(const char *name, const unsigned char *value, | |
66ab08b1 | 727 | STACK_OF(CONF_VALUE) **extlist); |
565d1065 DSH |
728 | |
729 | The same as above but for an unsigned character value. | |
730 | ||
66ab08b1 DSH |
731 | int X509V3_add_value_bool(const char *name, int asn1_bool, |
732 | STACK_OF(CONF_VALUE) **extlist); | |
565d1065 | 733 | |
1f2f9224 | 734 | This adds either "TRUE" or "FALSE" depending on the value of 'asn1_bool' |
565d1065 | 735 | |
66ab08b1 DSH |
736 | int X509V3_add_value_bool_nf(char *name, int asn1_bool, |
737 | STACK_OF(CONF_VALUE) **extlist); | |
565d1065 DSH |
738 | |
739 | This is the same as above except it adds nothing if asn1_bool is FALSE. | |
740 | ||
66ab08b1 DSH |
741 | int X509V3_add_value_int(const char *name, ASN1_INTEGER *aint, |
742 | STACK_OF(CONF_VALUE) **extlist); | |
565d1065 DSH |
743 | |
744 | This function adds the value of the ASN1_INTEGER in decimal form. | |
745 | ||
746 | 7. Other helper functions. | |
747 | ||
748 | <to be added> | |
749 | ||
750 | ADDING CUSTOM EXTENSIONS. | |
751 | ||
752 | Currently there are three types of supported extensions. | |
753 | ||
754 | String extensions are simple strings where the value is placed directly in the | |
755 | extensions, and the string returned is printed out. | |
756 | ||
66ab08b1 DSH |
757 | Multi value extensions are passed a STACK_OF(CONF_VALUE) name and value pairs |
758 | or return a STACK_OF(CONF_VALUE). | |
565d1065 DSH |
759 | |
760 | Raw extensions are just passed a BIO or a value and it is the extensions | |
1f2f9224 | 761 | responsibility to handle all the necessary printing. |
565d1065 DSH |
762 | |
763 | There are two ways to add an extension. One is simply as an alias to an already | |
764 | existing extension. An alias is an extension that is identical in ASN1 structure | |
765 | to an existing extension but has a different OBJECT IDENTIFIER. This can be | |
766 | done by calling: | |
767 | ||
768 | int X509V3_EXT_add_alias(int nid_to, int nid_from); | |
769 | ||
770 | 'nid_to' is the new extension NID and 'nid_from' is the already existing | |
771 | extension NID. | |
772 | ||
773 | Alternatively an extension can be written from scratch. This involves writing | |
774 | the ASN1 code to encode and decode the extension and functions to print out and | |
775 | generate the extension from strings. The relevant functions are then placed in | |
776 | a X509V3_EXT_METHOD structure and int X509V3_EXT_add(X509V3_EXT_METHOD *ext); | |
777 | called. | |
778 | ||
779 | The X509V3_EXT_METHOD structure is described below. | |
780 | ||
90076b96 | 781 | struct { |
565d1065 DSH |
782 | int ext_nid; |
783 | int ext_flags; | |
784 | X509V3_EXT_NEW ext_new; | |
785 | X509V3_EXT_FREE ext_free; | |
786 | X509V3_EXT_D2I d2i; | |
787 | X509V3_EXT_I2D i2d; | |
788 | X509V3_EXT_I2S i2s; | |
789 | X509V3_EXT_S2I s2i; | |
790 | X509V3_EXT_I2V i2v; | |
791 | X509V3_EXT_V2I v2i; | |
792 | X509V3_EXT_R2I r2i; | |
793 | X509V3_EXT_I2R i2r; | |
794 | ||
795 | void *usr_data; | |
796 | }; | |
797 | ||
798 | The elements have the following meanings. | |
799 | ||
800 | ext_nid is the NID of the object identifier of the extension. | |
801 | ||
802 | ext_flags is set of flags. Currently the only external flag is | |
803 | X509V3_EXT_MULTILINE which means a multi valued extensions | |
804 | should be printed on separate lines. | |
805 | ||
806 | usr_data is an extension specific pointer to any relevant data. This | |
807 | allows extensions to share identical code but have different | |
808 | uses. An example of this is the bit string extension which uses | |
809 | usr_data to contain a list of the bit names. | |
810 | ||
811 | All the remaining elements are function pointers. | |
812 | ||
813 | ext_new is a pointer to a function that allocates memory for the | |
814 | extension ASN1 structure: for example ASN1_OBJECT_new(). | |
815 | ||
816 | ext_free is a pointer to a function that free up memory of the extension | |
817 | ASN1 structure: for example ASN1_OBJECT_free(). | |
818 | ||
819 | d2i is the standard ASN1 function that converts a DER buffer into | |
820 | the internal ASN1 structure: for example d2i_ASN1_IA5STRING(). | |
821 | ||
822 | i2d is the standard ASN1 function that converts the internal | |
823 | structure into the DER representation: for example | |
824 | i2d_ASN1_IA5STRING(). | |
825 | ||
826 | The remaining functions are depend on the type of extension. One i2X and | |
827 | one X2i should be set and the rest set to NULL. The types set do not need | |
828 | to match up, for example the extension could be set using the multi valued | |
829 | v2i function and printed out using the raw i2r. | |
830 | ||
831 | All functions have the X509V3_EXT_METHOD passed to them in the 'method' | |
832 | parameter and an X509V3_CTX structure. Extension code can then access the | |
833 | parent structure via the 'method' parameter to for example make use of the value | |
834 | of usr_data. If the code needs to use detail relating to the request it can | |
835 | use the 'ctx' parameter. | |
836 | ||
837 | A note should be given here about the 'flags' member of the 'ctx' parameter. | |
838 | If it has the value CTX_TEST then the configuration syntax is being checked | |
839 | and no actual certificate or CRL exists. Therefore any attempt in the config | |
840 | file to access such information should silently succeed. If the syntax is OK | |
841 | then it should simply return a (possibly bogus) extension, otherwise it | |
842 | should return NULL. | |
843 | ||
844 | char *i2s(struct v3_ext_method *method, void *ext); | |
845 | ||
846 | This function takes the internal structure in the ext parameter and returns | |
847 | a Malloc'ed string representing its value. | |
848 | ||
849 | void * s2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str); | |
850 | ||
851 | This function takes the string representation in the ext parameter and returns | |
852 | an allocated internal structure: ext_free() will be used on this internal | |
853 | structure after use. | |
854 | ||
66ab08b1 | 855 | i2v and v2i handle a STACK_OF(CONF_VALUE): |
565d1065 DSH |
856 | |
857 | typedef struct | |
858 | { | |
859 | char *section; | |
860 | char *name; | |
861 | char *value; | |
862 | } CONF_VALUE; | |
863 | ||
864 | Only the name and value members are currently used. | |
865 | ||
66ab08b1 | 866 | STACK_OF(CONF_VALUE) * i2v(struct v3_ext_method *method, void *ext); |
565d1065 DSH |
867 | |
868 | This function is passed the internal structure in the ext parameter and | |
869 | returns a STACK of CONF_VALUE structures. The values of name, value, | |
870 | section and the structure itself will be freed up with Free after use. | |
871 | Several helper functions are available to add values to this STACK. | |
872 | ||
66ab08b1 DSH |
873 | void * v2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, |
874 | STACK_OF(CONF_VALUE) *values); | |
565d1065 | 875 | |
66ab08b1 | 876 | This function takes a STACK_OF(CONF_VALUE) structures and should set the |
565d1065 DSH |
877 | values of the external structure. This typically uses the name element to |
878 | determine which structure element to set and the value element to determine | |
879 | what to set it to. Several helper functions are available for this | |
880 | purpose (see above). | |
881 | ||
882 | int i2r(struct v3_ext_method *method, void *ext, BIO *out, int indent); | |
883 | ||
884 | This function is passed the internal extension structure in the ext parameter | |
885 | and sends out a human readable version of the extension to out. The 'indent' | |
1f2f9224 | 886 | parameter should be noted to determine the necessary amount of indentation |
565d1065 DSH |
887 | needed on the output. |
888 | ||
889 | void * r2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str); | |
890 | ||
891 | This is just passed the string representation of the extension. It is intended | |
892 | to be used for more elaborate extensions where the standard single and multi | |
893 | valued options are insufficient. They can use the 'ctx' parameter to parse the | |
894 | configuration database themselves. See the context functions section for details | |
895 | of how to do this. | |
896 | ||
897 | Note: although this type takes the same parameters as the "r2s" function there | |
898 | is a subtle difference. Whereas an "r2i" function can access a configuration | |
899 | database an "s2i" function MUST NOT. This is so the internal code can safely | |
900 | assume that an "s2i" function will work without a configuration database. | |
901 | ||
b64f8256 DSH |
902 | ============================================================================== |
903 | PKCS#12 Library | |
904 | ============================================================================== | |
905 | ||
906 | This section describes the internal PKCS#12 support. There are very few | |
907 | differences between the old external library and the new internal code at | |
908 | present. This may well change because the external library will not be updated | |
909 | much in future. | |
910 | ||
911 | This version now includes a couple of high level PKCS#12 functions which | |
912 | generally "do the right thing" and should make it much easier to handle PKCS#12 | |
913 | structures. | |
914 | ||
915 | HIGH LEVEL FUNCTIONS. | |
916 | ||
917 | For most applications you only need concern yourself with the high level | |
918 | functions. They can parse and generate simple PKCS#12 files as produced by | |
919 | Netscape and MSIE or indeed any compliant PKCS#12 file containing a single | |
920 | private key and certificate pair. | |
921 | ||
922 | 1. Initialisation and cleanup. | |
923 | ||
924 | No special initialisation is needed for the internal PKCS#12 library: the | |
925 | standard SSLeay_add_all_algorithms() is sufficient. If you do not wish to | |
e40b7abe DSH |
926 | add all algorithms (you should at least add SHA1 though) then you can manually |
927 | initialise the PKCS#12 library with: | |
b64f8256 | 928 | |
33d50ef6 | 929 | PKCS12_PBE_add(); |
b64f8256 | 930 | |
33d50ef6 | 931 | The memory allocated by the PKCS#12 library is freed up when EVP_cleanup() is |
b64f8256 DSH |
932 | called or it can be directly freed with: |
933 | ||
934 | EVP_PBE_cleanup(); | |
935 | ||
936 | after this call (or EVP_cleanup() ) no more PKCS#12 library functions should | |
937 | be called. | |
938 | ||
939 | 2. I/O functions. | |
940 | ||
941 | i2d_PKCS12_bio(bp, p12) | |
942 | ||
943 | This writes out a PKCS12 structure to a BIO. | |
944 | ||
945 | i2d_PKCS12_fp(fp, p12) | |
946 | ||
947 | This is the same but for a FILE pointer. | |
948 | ||
949 | d2i_PKCS12_bio(bp, p12) | |
950 | ||
951 | This reads in a PKCS12 structure from a BIO. | |
952 | ||
953 | d2i_PKCS12_fp(fp, p12) | |
954 | ||
955 | This is the same but for a FILE pointer. | |
956 | ||
21131f00 | 957 | 3. High level functions. |
b64f8256 DSH |
958 | |
959 | 3.1 Parsing with PKCS12_parse(). | |
960 | ||
961 | int PKCS12_parse(PKCS12 *p12, char *pass, EVP_PKEY **pkey, X509 **cert, | |
962 | STACK **ca); | |
963 | ||
964 | This function takes a PKCS12 structure and a password (ASCII, null terminated) | |
965 | and returns the private key, the corresponding certificate and any CA | |
966 | certificates. If any of these is not required it can be passed as a NULL. | |
967 | The 'ca' parameter should be either NULL, a pointer to NULL or a valid STACK | |
968 | structure. Typically to read in a PKCS#12 file you might do: | |
969 | ||
970 | p12 = d2i_PKCS12_fp(fp, NULL); | |
971 | PKCS12_parse(p12, password, &pkey, &cert, NULL); /* CAs not wanted */ | |
972 | PKCS12_free(p12); | |
973 | ||
974 | 3.2 PKCS#12 creation with PKCS12_create(). | |
975 | ||
976 | PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert, | |
977 | STACK *ca, int nid_key, int nid_cert, int iter, | |
978 | int mac_iter, int keytype); | |
979 | ||
980 | This function will create a PKCS12 structure from a given password, name, | |
981 | private key, certificate and optional STACK of CA certificates. The remaining | |
982 | 5 parameters can be set to 0 and sensible defaults will be used. | |
983 | ||
984 | The parameters nid_key and nid_cert are the key and certificate encryption | |
985 | algorithms, iter is the encryption iteration count, mac_iter is the MAC | |
986 | iteration count and keytype is the type of private key. If you really want | |
987 | to know what these last 5 parameters do then read the low level section. | |
988 | ||
989 | Typically to create a PKCS#12 file the following could be used: | |
990 | ||
991 | p12 = PKCS12_create(pass, "My Certificate", pkey, cert, NULL, 0,0,0,0,0); | |
992 | i2d_PKCS12_fp(fp, p12); | |
993 | PKCS12_free(p12); | |
994 | ||
21131f00 DSH |
995 | 3.3 Changing a PKCS#12 structure password. |
996 | ||
997 | int PKCS12_newpass(PKCS12 *p12, char *oldpass, char *newpass); | |
998 | ||
999 | This changes the password of an already existing PKCS#12 structure. oldpass | |
1000 | is the old password and newpass is the new one. An error occurs if the old | |
1001 | password is incorrect. | |
1002 | ||
b64f8256 DSH |
1003 | LOW LEVEL FUNCTIONS. |
1004 | ||
1005 | In some cases the high level functions do not provide the necessary | |
b975f15d BM |
1006 | functionality. For example if you want to generate or parse more complex |
1007 | PKCS#12 files. The sample pkcs12 application uses the low level functions | |
1008 | to display details about the internal structure of a PKCS#12 file. | |
b64f8256 DSH |
1009 | |
1010 | Introduction. | |
1011 | ||
1012 | This is a brief description of how a PKCS#12 file is represented internally: | |
1013 | some knowledge of PKCS#12 is assumed. | |
1014 | ||
1015 | A PKCS#12 object contains several levels. | |
1016 | ||
1017 | At the lowest level is a PKCS12_SAFEBAG. This can contain a certificate, a | |
1018 | CRL, a private key, encrypted or unencrypted, a set of safebags (so the | |
1019 | structure can be nested) or other secrets (not documented at present). | |
1020 | A safebag can optionally have attributes, currently these are: a unicode | |
1021 | friendlyName (a Unicode string) or a localKeyID (a string of bytes). | |
1022 | ||
1023 | At the next level is an authSafe which is a set of safebags collected into | |
1024 | a PKCS#7 ContentInfo. This can be just plain data, or encrypted itself. | |
1025 | ||
1026 | At the top level is the PKCS12 structure itself which contains a set of | |
1027 | authSafes in an embedded PKCS#7 Contentinfo of type data. In addition it | |
1028 | contains a MAC which is a kind of password protected digest to preserve | |
1029 | integrity (so any unencrypted stuff below can't be tampered with). | |
1030 | ||
1031 | The reason for these levels is so various objects can be encrypted in various | |
1032 | ways. For example you might want to encrypt a set of private keys with | |
b975f15d BM |
1033 | triple-DES and then include the related certificates either unencrypted or |
1034 | with lower encryption. Yes it's the dreaded crypto laws at work again which | |
1035 | allow strong encryption on private keys and only weak encryption on other | |
1036 | stuff. | |
b64f8256 DSH |
1037 | |
1038 | To build one of these things you turn all certificates and keys into safebags | |
1039 | (with optional attributes). You collect the safebags into (one or more) STACKS | |
b975f15d BM |
1040 | and convert these into authsafes (encrypted or unencrypted). The authsafes |
1041 | are collected into a STACK and added to a PKCS12 structure. Finally a MAC | |
1042 | inserted. | |
b64f8256 DSH |
1043 | |
1044 | Pulling one apart is basically the reverse process. The MAC is verified against | |
1045 | the given password. The authsafes are extracted and each authsafe split into | |
1046 | a set of safebags (possibly involving decryption). Finally the safebags are | |
1047 | decomposed into the original keys and certificates and the attributes used to | |
1048 | match up private key and certificate pairs. | |
1049 | ||
1050 | Anyway here are the functions that do the dirty work. | |
1051 | ||
1052 | 1. Construction functions. | |
1053 | ||
1054 | 1.1 Safebag functions. | |
1055 | ||
1056 | M_PKCS12_x5092certbag(x509) | |
1057 | ||
1058 | This macro takes an X509 structure and returns a certificate bag. The | |
1059 | X509 structure can be freed up after calling this function. | |
1060 | ||
1061 | M_PKCS12_x509crl2certbag(crl) | |
1062 | ||
1063 | As above but for a CRL. | |
1064 | ||
1065 | PKCS8_PRIV_KEY_INFO *PKEY2PKCS8(EVP_PKEY *pkey) | |
1066 | ||
1067 | Take a private key and convert it into a PKCS#8 PrivateKeyInfo structure. | |
1068 | Works for both RSA and DSA private keys. NB since the PKCS#8 PrivateKeyInfo | |
b975f15d BM |
1069 | structure contains a private key data in plain text form it should be free'd |
1070 | up as soon as it has been encrypted for security reasons (freeing up the | |
1071 | structure zeros out the sensitive data). This can be done with | |
1072 | PKCS8_PRIV_KEY_INFO_free(). | |
b64f8256 DSH |
1073 | |
1074 | PKCS8_add_keyusage(PKCS8_PRIV_KEY_INFO *p8, int usage) | |
1075 | ||
1076 | This sets the key type when a key is imported into MSIE or Outlook 98. Two | |
1077 | values are currently supported: KEY_EX and KEY_SIG. KEY_EX is an exchange type | |
1078 | key that can also be used for signing but its size is limited in the export | |
1079 | versions of MS software to 512 bits, it is also the default. KEY_SIG is a | |
1080 | signing only key but the keysize is unlimited (well 16K is supposed to work). | |
1081 | If you are using the domestic version of MSIE then you can ignore this because | |
1082 | KEY_EX is not limited and can be used for both. | |
1083 | ||
1084 | PKCS12_SAFEBAG *PKCS12_MAKE_KEYBAG(PKCS8_PRIV_KEY_INFO *p8) | |
1085 | ||
b975f15d BM |
1086 | Convert a PKCS8 private key structure into a keybag. This routine embeds the |
1087 | p8 structure in the keybag so p8 should not be freed up or used after it is | |
1088 | called. The p8 structure will be freed up when the safebag is freed. | |
b64f8256 DSH |
1089 | |
1090 | PKCS12_SAFEBAG *PKCS12_MAKE_SHKEYBAG(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8) | |
1091 | ||
1092 | Convert a PKCS#8 structure into a shrouded key bag (encrypted). p8 is not | |
1093 | embedded and can be freed up after use. | |
1094 | ||
1095 | int PKCS12_add_localkeyid(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen) | |
1096 | int PKCS12_add_friendlyname(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen) | |
1097 | ||
1098 | Add a local key id or a friendlyname to a safebag. | |
1099 | ||
1100 | 1.2 Authsafe functions. | |
1101 | ||
1102 | PKCS7 *PKCS12_pack_p7data(STACK *sk) | |
1103 | Take a stack of safebags and convert them into an unencrypted authsafe. The | |
1104 | stack of safebags can be freed up after calling this function. | |
1105 | ||
1106 | PKCS7 *PKCS12_pack_p7encdata(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, STACK *bags); | |
1107 | ||
1108 | As above but encrypted. | |
1109 | ||
1110 | 1.3 PKCS12 functions. | |
1111 | ||
1112 | PKCS12 *PKCS12_init(int mode) | |
1113 | ||
1114 | Initialise a PKCS12 structure (currently mode should be NID_pkcs7_data). | |
1115 | ||
1116 | M_PKCS12_pack_authsafes(p12, safes) | |
1117 | ||
1118 | This macro takes a STACK of authsafes and adds them to a PKCS#12 structure. | |
1119 | ||
1120 | int PKCS12_set_mac(PKCS12 *p12, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, EVP_MD *md_type); | |
1121 | ||
1122 | Add a MAC to a PKCS12 structure. If EVP_MD is NULL use SHA-1, the spec suggests | |
1123 | that SHA-1 should be used. | |
1124 | ||
1125 | 2. Extraction Functions. | |
1126 | ||
1127 | 2.1 Safebags. | |
1128 | ||
1129 | M_PKCS12_bag_type(bag) | |
1130 | ||
1131 | Return the type of "bag". Returns one of the following | |
1132 | ||
1133 | NID_keyBag | |
1134 | NID_pkcs8ShroudedKeyBag 7 | |
1135 | NID_certBag 8 | |
1136 | NID_crlBag 9 | |
1137 | NID_secretBag 10 | |
1138 | NID_safeContentsBag 11 | |
1139 | ||
1140 | M_PKCS12_cert_bag_type(bag) | |
1141 | ||
1142 | Returns type of certificate bag, following are understood. | |
1143 | ||
1144 | NID_x509Certificate 14 | |
1145 | NID_sdsiCertificate 15 | |
1146 | ||
1147 | M_PKCS12_crl_bag_type(bag) | |
1148 | ||
1149 | Returns crl bag type, currently only NID_crlBag is recognised. | |
1150 | ||
1151 | M_PKCS12_certbag2x509(bag) | |
1152 | ||
1153 | This macro extracts an X509 certificate from a certificate bag. | |
1154 | ||
1155 | M_PKCS12_certbag2x509crl(bag) | |
1156 | ||
1157 | As above but for a CRL. | |
1158 | ||
1159 | EVP_PKEY * PKCS82PKEY(PKCS8_PRIV_KEY_INFO *p8) | |
1160 | ||
1161 | Extract a private key from a PKCS8 private key info structure. | |
1162 | ||
1163 | M_PKCS12_decrypt_skey(bag, pass, passlen) | |
1164 | ||
1165 | Decrypt a shrouded key bag and return a PKCS8 private key info structure. | |
1166 | Works with both RSA and DSA keys | |
1167 | ||
1168 | char *PKCS12_get_friendlyname(bag) | |
1169 | ||
1170 | Returns the friendlyName of a bag if present or NULL if none. The returned | |
1171 | string is a null terminated ASCII string allocated with Malloc(). It should | |
1172 | thus be freed up with Free() after use. | |
1173 | ||
1174 | 2.2 AuthSafe functions. | |
1175 | ||
1176 | M_PKCS12_unpack_p7data(p7) | |
1177 | ||
1178 | Extract a STACK of safe bags from a PKCS#7 data ContentInfo. | |
1179 | ||
1180 | #define M_PKCS12_unpack_p7encdata(p7, pass, passlen) | |
1181 | ||
1182 | As above but for an encrypted content info. | |
1183 | ||
1184 | 2.3 PKCS12 functions. | |
1185 | ||
1186 | M_PKCS12_unpack_authsafes(p12) | |
1187 | ||
1188 | Extract a STACK of authsafes from a PKCS12 structure. | |
1189 | ||
1190 | M_PKCS12_mac_present(p12) | |
1191 | ||
1192 | Check to see if a MAC is present. | |
1193 | ||
1194 | int PKCS12_verify_mac(PKCS12 *p12, unsigned char *pass, int passlen) | |
1195 | ||
1196 | Verify a MAC on a PKCS12 structure. Returns an error if MAC not present. | |
1197 | ||
1198 | ||
1199 | Notes. | |
1200 | ||
1201 | 1. All the function return 0 or NULL on error. | |
1202 | 2. Encryption based functions take a common set of parameters. These are | |
1203 | described below. | |
1204 | ||
1205 | pass, passlen | |
1206 | ASCII password and length. The password on the MAC is called the "integrity | |
1207 | password" the encryption password is called the "privacy password" in the | |
1208 | PKCS#12 documentation. The passwords do not have to be the same. If -1 is | |
1209 | passed for the length it is worked out by the function itself (currently | |
1210 | this is sometimes done whatever is passed as the length but that may change). | |
1211 | ||
1212 | salt, saltlen | |
1213 | A 'salt' if salt is NULL a random salt is used. If saltlen is also zero a | |
1214 | default length is used. | |
1215 | ||
1216 | iter | |
1217 | Iteration count. This is a measure of how many times an internal function is | |
1218 | called to encrypt the data. The larger this value is the longer it takes, it | |
1219 | makes dictionary attacks on passwords harder. NOTE: Some implementations do | |
1220 | not support an iteration count on the MAC. If the password for the MAC and | |
1221 | encryption is the same then there is no point in having a high iteration | |
1222 | count for encryption if the MAC has no count. The MAC could be attacked | |
1223 | and the password used for the main decryption. | |
1224 | ||
1225 | pbe_nid | |
1226 | This is the NID of the password based encryption method used. The following are | |
1227 | supported. | |
1228 | NID_pbe_WithSHA1And128BitRC4 | |
1229 | NID_pbe_WithSHA1And40BitRC4 | |
1230 | NID_pbe_WithSHA1And3_Key_TripleDES_CBC | |
1231 | NID_pbe_WithSHA1And2_Key_TripleDES_CBC | |
1232 | NID_pbe_WithSHA1And128BitRC2_CBC | |
1233 | NID_pbe_WithSHA1And40BitRC2_CBC | |
1234 | ||
b975f15d | 1235 | Which you use depends on the implementation you are exporting to. "Export |
33d50ef6 | 1236 | grade" (i.e. cryptographically challenged) products cannot support all |
b975f15d BM |
1237 | algorithms. Typically you may be able to use any encryption on shrouded key |
1238 | bags but they must then be placed in an unencrypted authsafe. Other authsafes | |
1239 | may only support 40bit encryption. Of course if you are using SSLeay | |
1240 | throughout you can strongly encrypt everything and have high iteration counts | |
1241 | on everything. | |
b64f8256 DSH |
1242 | |
1243 | 3. For decryption routines only the password and length are needed. | |
1244 | ||
1245 | 4. Unlike the external version the nid's of objects are the values of the | |
1246 | constants: that is NID_certBag is the real nid, therefore there is no | |
1247 | PKCS12_obj_offset() function. Note the object constants are not the same as | |
1248 | those of the external version. If you use these constants then you will need | |
1249 | to recompile your code. | |
1250 | ||
1251 | 5. With the exception of PKCS12_MAKE_KEYBAG(), after calling any function or | |
1252 | macro of the form PKCS12_MAKE_SOMETHING(other) the "other" structure can be | |
1253 | reused or freed up safely. | |
1254 |