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