]>
Commit | Line | Data |
---|---|---|
f5904406 RE |
1 | |
2 | This is some preliminary documentation for OpenSSL. | |
3 | ||
4 | ============================================================================== | |
5 | BUFFER Library | |
6 | ============================================================================== | |
7 | ||
b975f15d BM |
8 | The buffer library handles simple character arrays. Buffers are used for |
9 | various purposes in the library, most notably memory BIOs. | |
f5904406 RE |
10 | |
11 | The library uses the BUF_MEM structure defined in buffer.h: | |
12 | ||
13 | typedef struct buf_mem_st | |
b64f8256 | 14 | { |
f5904406 RE |
15 | int length; /* current number of bytes */ |
16 | char *data; | |
17 | int max; /* size of buffer */ | |
b64f8256 | 18 | } BUF_MEM; |
f5904406 RE |
19 | |
20 | 'length' is the current size of the buffer in bytes, 'max' is the amount of | |
21 | memory allocated to the buffer. There are three functions which handle these | |
33d50ef6 | 22 | and one "miscellaneous" function. |
f5904406 RE |
23 | |
24 | BUF_MEM *BUF_MEM_new() | |
25 | ||
26 | This allocates a new buffer of zero size. Returns the buffer or NULL on error. | |
27 | ||
28 | void BUF_MEM_free(BUF_MEM *a) | |
29 | ||
30 | This frees up an already existing buffer. The data is zeroed before freeing | |
31 | up in case the buffer contains sensitive data. | |
32 | ||
33 | int BUF_MEM_grow(BUF_MEM *str, int len) | |
34 | ||
35 | This changes the size of an already existing buffer. It returns zero on error | |
36 | or the new size (i.e. 'len'). Any data already in the buffer is preserved if | |
37 | it increases in size. | |
38 | ||
39 | char * BUF_strdup(char *str) | |
40 | ||
41 | This is the previously mentioned strdup function: like the standard library | |
42 | strdup() it copies a null terminated string into a block of allocated memory | |
43 | and returns a pointer to the allocated block. | |
44 | ||
45 | Unlike the standard C library strdup() this function uses Malloc() and so | |
46 | should be used in preference to the standard library strdup() because it can | |
47 | be used for memory leak checking or replacing the malloc() function. | |
48 | ||
49 | The memory allocated from BUF_strdup() should be freed up using the Free() | |
50 | function. | |
51 | ||
52 | ============================================================================== | |
53 | OpenSSL X509V3 extension configuration | |
54 | ============================================================================== | |
55 | ||
deff75b6 DSH |
56 | OpenSSL X509V3 extension configuration: preliminary documentation. |
57 | ||
58 | INTRODUCTION. | |
59 | ||
60 | For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now | |
61 | possible to add and print out common X509 V3 certificate and CRL extensions. | |
62 | ||
63 | For more information about the meaning of extensions see: | |
64 | ||
65 | http://www.imc.org/ietf-pkix/ | |
66 | http://home.netscape.com/eng/security/certs.html | |
67 | ||
68 | PRINTING EXTENSIONS. | |
69 | ||
70 | Extension values are automatically printed out for supported extensions. | |
71 | ||
1756d405 DSH |
72 | openssl x509 -in cert.pem -text |
73 | openssl crl -in crl.pem -text | |
deff75b6 DSH |
74 | |
75 | will give information in the extension printout, for example: | |
76 | ||
77 | ||
78 | X509v3 extensions: | |
79 | X509v3 Basic Constraints: | |
80 | CA:TRUE | |
81 | X509v3 Subject Key Identifier: | |
82 | 73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15 | |
83 | X509v3 Authority Key Identifier: | |
84 | 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 | |
85 | X509v3 Key Usage: | |
86 | Certificate Sign, CRL Sign | |
87 | X509v3 Subject Alternative Name: | |
88 | email:email@1.address, email:email@2.address | |
89 | ||
90 | CONFIGURATION FILES. | |
91 | ||
92 | The OpenSSL utilities 'ca' and 'req' can now have extension sections listing | |
93 | which certificate extensions to include. In each case a line: | |
94 | ||
95 | x509_extensions = extension_section | |
96 | ||
97 | indicates which section contains the extensions. In the case of 'req' the | |
98 | extension section is used when the -x509 option is present to create a | |
99 | self signed root certificate. | |
100 | ||
e40b7abe | 101 | The 'x509' utility also supports extensions when it signs a certificate. |
3f45ed82 | 102 | The -extfile option is used to set the configuration file containing the |
e40b7abe DSH |
103 | extensions. In this case a line with: |
104 | ||
105 | extensions = extension_section | |
106 | ||
703126f0 | 107 | in the nameless (default) section is used. If no such line is included then |
e40b7abe DSH |
108 | it uses the default section. |
109 | ||
1756d405 DSH |
110 | You can also add extensions to CRLs: a line |
111 | ||
112 | crl_extensions = crl_extension_section | |
113 | ||
114 | will include extensions when the -gencrl option is used with the 'ca' utility. | |
115 | You can add any extension to a CRL but of the supported extensions only | |
116 | issuerAltName and authorityKeyIdentifier make any real sense. Note: these are | |
117 | CRL extensions NOT CRL *entry* extensions which cannot currently be generated. | |
118 | CRL entry extensions can be displayed. | |
119 | ||
e40b7abe DSH |
120 | NB. At this time Netscape Communicator rejects V2 CRLs: to get an old V1 CRL |
121 | you should comment out the crl_extensions line in the configuration file. | |
122 | ||
123 | As with all configuration files you can use the inbuilt environment expansion | |
124 | to allow the values to be passed in the environment. Therefore if you have | |
125 | several extension sections used for different purposes you can have a line: | |
126 | ||
127 | x509_extensions = $ENV::ENV_EXT | |
128 | ||
129 | and set the ENV_EXT environment variable before calling the relevant utility. | |
130 | ||
deff75b6 DSH |
131 | EXTENSION SYNTAX. |
132 | ||
133 | Extensions have the basic form: | |
134 | ||
135 | extension_name=[critical,] extension_options | |
136 | ||
137 | the use of the critical option makes the extension critical. Extreme caution | |
138 | should be made when using the critical flag. If an extension is marked | |
139 | as critical then any client that does not understand the extension should | |
140 | reject it as invalid. Some broken software will reject certificates which | |
141 | have *any* critical extensions (these violates PKIX but we have to live | |
142 | with it). | |
143 | ||
33d50ef6 | 144 | There are three main types of extension: string extensions, multi-valued |
deff75b6 DSH |
145 | extensions, and raw extensions. |
146 | ||
703126f0 DSH |
147 | String extensions simply have a string which contains either the value itself |
148 | or how it is obtained. | |
deff75b6 DSH |
149 | |
150 | For example: | |
151 | ||
152 | nsComment="This is a Comment" | |
153 | ||
33d50ef6 | 154 | Multi-valued extensions have a short form and a long form. The short form |
deff75b6 DSH |
155 | is a list of names and values: |
156 | ||
157 | basicConstraints=critical,CA:true,pathlen:1 | |
158 | ||
159 | The long form allows the values to be placed in a separate section: | |
160 | ||
161 | basicConstraints=critical,@bs_section | |
162 | ||
163 | [bs_section] | |
164 | ||
165 | CA=true | |
166 | pathlen=1 | |
167 | ||
168 | Both forms are equivalent. However it should be noted that in some cases the | |
169 | same name can appear multiple times, for example, | |
170 | ||
171 | subjectAltName=email:steve@here,email:steve@there | |
172 | ||
173 | in this case an equivalent long form is: | |
174 | ||
175 | subjectAltName=@alt_section | |
176 | ||
177 | [alt_section] | |
178 | ||
179 | email.1=steve@here | |
180 | email.2=steve@there | |
181 | ||
182 | This is because the configuration file code cannot handle the same name | |
183 | occurring twice in the same extension. | |
184 | ||
703126f0 DSH |
185 | The syntax of raw extensions is governed by the extension code: it can |
186 | for example contain data in multiple sections. The correct syntax to | |
187 | use is defined by the extension code itself: check out the certificate | |
188 | policies extension for an example. | |
deff75b6 | 189 | |
703126f0 DSH |
190 | In addition it is also possible to use the word DER to include arbitrary |
191 | data in any extension. | |
deff75b6 | 192 | |
703126f0 DSH |
193 | 1.2.3.4=critical,DER:01:02:03:04 |
194 | 1.2.3.4=DER:01020304 | |
deff75b6 | 195 | |
703126f0 DSH |
196 | The value following DER is a hex dump of the DER encoding of the extension |
197 | Any extension can be placed in this form to override the default behaviour. | |
198 | For example: | |
199 | ||
200 | basicConstraints=critical,DER:00:01:02:03 | |
deff75b6 | 201 | |
703126f0 DSH |
202 | WARNING: DER should be used with caution. It is possible to create totally |
203 | invalid extensions unless care is taken. | |
deff75b6 DSH |
204 | |
205 | CURRENTLY SUPPORTED EXTENSIONS. | |
206 | ||
207 | Literal String extensions. | |
208 | ||
b975f15d BM |
209 | In each case the 'value' of the extension is placed directly in the |
210 | extension. Currently supported extensions in this category are: nsBaseUrl, | |
211 | nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, | |
212 | nsSslServerName and nsComment. | |
deff75b6 DSH |
213 | |
214 | For example: | |
215 | ||
216 | nsComment="This is a test comment" | |
217 | ||
218 | Bit Strings. | |
219 | ||
33d50ef6 | 220 | Bit string extensions just consist of a list of supported bits, currently |
deff75b6 DSH |
221 | two extensions are in this category: PKIX keyUsage and the Netscape specific |
222 | nsCertType. | |
223 | ||
224 | nsCertType (netscape certificate type) takes the flags: client, server, email, | |
225 | objsign, reserved, sslCA, emailCA, objCA. | |
226 | ||
227 | keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation, | |
94c95d04 | 228 | keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, |
deff75b6 DSH |
229 | encipherOnly, decipherOnly. |
230 | ||
231 | For example: | |
232 | ||
233 | nsCertType=server | |
234 | ||
235 | keyUsage=critical, digitalSignature, nonRepudiation | |
236 | ||
237 | ||
238 | Basic Constraints. | |
239 | ||
33d50ef6 | 240 | Basic constraints is a multi-valued extension that supports a CA and an |
deff75b6 DSH |
241 | optional pathlen option. The CA option takes the values true and false and |
242 | pathlen takes an integer. Note if the CA option is false the pathlen option | |
243 | should be omitted. | |
244 | ||
245 | Examples: | |
246 | ||
247 | basicConstraints=CA:TRUE | |
248 | basicConstraints=critical,CA:TRUE, pathlen:10 | |
249 | ||
250 | NOTE: for a CA to be considered valid it must have the CA option set to | |
251 | TRUE. An end user certificate MUST NOT have the CA value set to true. | |
b64f8256 | 252 | According to PKIX recommendations it should exclude the extension entirely, |
deff75b6 DSH |
253 | however some software may require CA set to FALSE for end entity certificates. |
254 | ||
255 | Subject Key Identifier. | |
256 | ||
257 | This is really a string extension and can take two possible values. Either | |
258 | a hex string giving details of the extension value to include or the word | |
259 | 'hash' which then automatically follow PKIX guidelines in selecting and | |
260 | appropriate key identifier. The use of the hex string is strongly discouraged. | |
261 | ||
262 | Example: subjectKeyIdentifier=hash | |
263 | ||
264 | Authority Key Identifier. | |
265 | ||
266 | The authority key identifier extension permits two options. keyid and issuer: | |
267 | both can take the optional value "always". | |
268 | ||
269 | If the keyid option is present an attempt is made to copy the subject key | |
270 | identifier from the parent certificate. If the value "always" is present | |
271 | then an error is returned if the option fails. | |
272 | ||
273 | The issuer option copies the issuer and serial number from the issuer | |
274 | certificate. Normally this will only be done if the keyid option fails or | |
275 | is not included: the "always" flag will always include the value. | |
276 | ||
277 | Subject Alternative Name. | |
278 | ||
279 | The subject alternative name extension allows various literal values to be | |
280 | included in the configuration file. These include "email" (an email address) | |
281 | "URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a | |
282 | registered ID: OBJECT IDENTIFIER) and IP (and IP address). | |
283 | ||
284 | Also the email option include a special 'copy' value. This will automatically | |
285 | include and email addresses contained in the certificate subject name in | |
286 | the extension. | |
287 | ||
288 | Examples: | |
289 | ||
290 | subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/ | |
291 | subjectAltName=email:my@other.address,RID:1.2.3.4 | |
292 | ||
293 | Issuer Alternative Name. | |
294 | ||
295 | The issuer alternative name option supports all the literal options of | |
296 | subject alternative name. It does *not* support the email:copy option because | |
d943e372 | 297 | that would not make sense. It does support an additional issuer:copy option |
deff75b6 DSH |
298 | that will copy all the subject alternative name values from the issuer |
299 | certificate (if possible). | |
300 | ||
d943e372 DSH |
301 | CRL distribution points. |
302 | ||
33d50ef6 | 303 | This is a multi-valued extension that supports all the literal options of |
d943e372 DSH |
304 | subject alternative name. Of the few software packages that currently interpret |
305 | this extension most only interpret the URI option. | |
306 | ||
307 | Currently each option will set a new DistributionPoint with the fullName | |
308 | field set to the given value. | |
309 | ||
310 | Other fields like cRLissuer and reasons cannot currently be set or displayed: | |
311 | at this time no examples were available that used these fields. | |
312 | ||
313 | If you see this extension with <UNSUPPORTED> when you attempt to print it out | |
314 | or it doesn't appear to display correctly then let me know, including the | |
315 | certificate (mail me at steve@openssl.org) . | |
316 | ||
317 | Examples: | |
318 | ||
319 | crlDistributionPoints=URI:http://www.myhost.com/myca.crl | |
320 | crlDistributionPoints=URI:http://www.my.com/my.crl,URI:http://www.oth.com/my.crl | |
321 | ||
322 | Certificate Policies. | |
323 | ||
324 | This is a RAW extension. It attempts to display the contents of this extension: | |
33d50ef6 | 325 | unfortunately this extension is often improperly encoded. |
d943e372 DSH |
326 | |
327 | The certificate policies extension will rarely be used in practice: few | |
e40b7abe DSH |
328 | software packages interpret it correctly or at all. IE5 does partially |
329 | support this extension: but it needs the 'ia5org' option because it will | |
330 | only correctly support a broken encoding. Of the options below only the | |
331 | policy OID, explicitText and CPS options are displayed with IE5. | |
d943e372 DSH |
332 | |
333 | All the fields of this extension can be set by using the appropriate syntax. | |
334 | ||
335 | If you follow the PKIX recommendations of not including any qualifiers and just | |
336 | using only one OID then you just include the value of that OID. Multiple OIDs | |
337 | can be set separated by commas, for example: | |
338 | ||
339 | certificatePolicies= 1.2.4.5, 1.1.3.4 | |
340 | ||
341 | If you wish to include qualifiers then the policy OID and qualifiers need to | |
342 | be specified in a separate section: this is done by using the @section syntax | |
343 | instead of a literal OID value. | |
344 | ||
345 | The section referred to must include the policy OID using the name | |
346 | policyIdentifier, cPSuri qualifiers can be included using the syntax: | |
347 | ||
348 | CPS.nnn=value | |
349 | ||
350 | userNotice qualifiers can be set using the syntax: | |
351 | ||
352 | userNotice.nnn=@notice | |
353 | ||
b975f15d BM |
354 | The value of the userNotice qualifier is specified in the relevant section. |
355 | This section can include explicitText, organization and noticeNumbers | |
356 | options. explicitText and organization are text strings, noticeNumbers is a | |
357 | comma separated list of numbers. The organization and noticeNumbers options | |
358 | (if included) must BOTH be present. If you use the userNotice option with IE5 | |
359 | then you need the 'ia5org' option at the top level to modify the encoding: | |
360 | otherwise it will not be interpreted properly. | |
d943e372 DSH |
361 | |
362 | Example: | |
363 | ||
e40b7abe | 364 | certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect |
d943e372 DSH |
365 | |
366 | [polsect] | |
367 | ||
368 | policyIdentifier = 1.3.5.8 | |
369 | CPS.1="http://my.host.name/" | |
370 | CPS.2="http://my.your.name/" | |
371 | userNotice.1=@notice | |
372 | ||
373 | [notice] | |
374 | ||
375 | explicitText="Explicit Text Here" | |
376 | organization="Organisation Name" | |
377 | noticeNumbers=1,2,3,4 | |
378 | ||
e40b7abe DSH |
379 | TECHNICAL NOTE: the ia5org option changes the type of the 'organization' field, |
380 | according to PKIX it should be of type DisplayText but Verisign uses an | |
381 | IA5STRING and IE5 needs this too. | |
382 | ||
deff75b6 DSH |
383 | Display only extensions. |
384 | ||
385 | Some extensions are only partially supported and currently are only displayed | |
386 | but cannot be set. These include private key usage period, CRL number, and | |
387 | CRL reason. | |
f5904406 | 388 | |
b64f8256 DSH |
389 | ============================================================================== |
390 | PKCS#12 Library | |
391 | ============================================================================== | |
392 | ||
393 | This section describes the internal PKCS#12 support. There are very few | |
394 | differences between the old external library and the new internal code at | |
395 | present. This may well change because the external library will not be updated | |
396 | much in future. | |
397 | ||
398 | This version now includes a couple of high level PKCS#12 functions which | |
399 | generally "do the right thing" and should make it much easier to handle PKCS#12 | |
400 | structures. | |
401 | ||
402 | HIGH LEVEL FUNCTIONS. | |
403 | ||
404 | For most applications you only need concern yourself with the high level | |
405 | functions. They can parse and generate simple PKCS#12 files as produced by | |
406 | Netscape and MSIE or indeed any compliant PKCS#12 file containing a single | |
407 | private key and certificate pair. | |
408 | ||
409 | 1. Initialisation and cleanup. | |
410 | ||
411 | No special initialisation is needed for the internal PKCS#12 library: the | |
412 | standard SSLeay_add_all_algorithms() is sufficient. If you do not wish to | |
e40b7abe DSH |
413 | add all algorithms (you should at least add SHA1 though) then you can manually |
414 | initialise the PKCS#12 library with: | |
b64f8256 | 415 | |
33d50ef6 | 416 | PKCS12_PBE_add(); |
b64f8256 | 417 | |
33d50ef6 | 418 | The memory allocated by the PKCS#12 library is freed up when EVP_cleanup() is |
b64f8256 DSH |
419 | called or it can be directly freed with: |
420 | ||
421 | EVP_PBE_cleanup(); | |
422 | ||
423 | after this call (or EVP_cleanup() ) no more PKCS#12 library functions should | |
424 | be called. | |
425 | ||
426 | 2. I/O functions. | |
427 | ||
428 | i2d_PKCS12_bio(bp, p12) | |
429 | ||
430 | This writes out a PKCS12 structure to a BIO. | |
431 | ||
432 | i2d_PKCS12_fp(fp, p12) | |
433 | ||
434 | This is the same but for a FILE pointer. | |
435 | ||
436 | d2i_PKCS12_bio(bp, p12) | |
437 | ||
438 | This reads in a PKCS12 structure from a BIO. | |
439 | ||
440 | d2i_PKCS12_fp(fp, p12) | |
441 | ||
442 | This is the same but for a FILE pointer. | |
443 | ||
444 | 3. Parsing and creation functions. | |
445 | ||
446 | 3.1 Parsing with PKCS12_parse(). | |
447 | ||
448 | int PKCS12_parse(PKCS12 *p12, char *pass, EVP_PKEY **pkey, X509 **cert, | |
449 | STACK **ca); | |
450 | ||
451 | This function takes a PKCS12 structure and a password (ASCII, null terminated) | |
452 | and returns the private key, the corresponding certificate and any CA | |
453 | certificates. If any of these is not required it can be passed as a NULL. | |
454 | The 'ca' parameter should be either NULL, a pointer to NULL or a valid STACK | |
455 | structure. Typically to read in a PKCS#12 file you might do: | |
456 | ||
457 | p12 = d2i_PKCS12_fp(fp, NULL); | |
458 | PKCS12_parse(p12, password, &pkey, &cert, NULL); /* CAs not wanted */ | |
459 | PKCS12_free(p12); | |
460 | ||
461 | 3.2 PKCS#12 creation with PKCS12_create(). | |
462 | ||
463 | PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert, | |
464 | STACK *ca, int nid_key, int nid_cert, int iter, | |
465 | int mac_iter, int keytype); | |
466 | ||
467 | This function will create a PKCS12 structure from a given password, name, | |
468 | private key, certificate and optional STACK of CA certificates. The remaining | |
469 | 5 parameters can be set to 0 and sensible defaults will be used. | |
470 | ||
471 | The parameters nid_key and nid_cert are the key and certificate encryption | |
472 | algorithms, iter is the encryption iteration count, mac_iter is the MAC | |
473 | iteration count and keytype is the type of private key. If you really want | |
474 | to know what these last 5 parameters do then read the low level section. | |
475 | ||
476 | Typically to create a PKCS#12 file the following could be used: | |
477 | ||
478 | p12 = PKCS12_create(pass, "My Certificate", pkey, cert, NULL, 0,0,0,0,0); | |
479 | i2d_PKCS12_fp(fp, p12); | |
480 | PKCS12_free(p12); | |
481 | ||
482 | LOW LEVEL FUNCTIONS. | |
483 | ||
484 | In some cases the high level functions do not provide the necessary | |
b975f15d BM |
485 | functionality. For example if you want to generate or parse more complex |
486 | PKCS#12 files. The sample pkcs12 application uses the low level functions | |
487 | to display details about the internal structure of a PKCS#12 file. | |
b64f8256 DSH |
488 | |
489 | Introduction. | |
490 | ||
491 | This is a brief description of how a PKCS#12 file is represented internally: | |
492 | some knowledge of PKCS#12 is assumed. | |
493 | ||
494 | A PKCS#12 object contains several levels. | |
495 | ||
496 | At the lowest level is a PKCS12_SAFEBAG. This can contain a certificate, a | |
497 | CRL, a private key, encrypted or unencrypted, a set of safebags (so the | |
498 | structure can be nested) or other secrets (not documented at present). | |
499 | A safebag can optionally have attributes, currently these are: a unicode | |
500 | friendlyName (a Unicode string) or a localKeyID (a string of bytes). | |
501 | ||
502 | At the next level is an authSafe which is a set of safebags collected into | |
503 | a PKCS#7 ContentInfo. This can be just plain data, or encrypted itself. | |
504 | ||
505 | At the top level is the PKCS12 structure itself which contains a set of | |
506 | authSafes in an embedded PKCS#7 Contentinfo of type data. In addition it | |
507 | contains a MAC which is a kind of password protected digest to preserve | |
508 | integrity (so any unencrypted stuff below can't be tampered with). | |
509 | ||
510 | The reason for these levels is so various objects can be encrypted in various | |
511 | ways. For example you might want to encrypt a set of private keys with | |
b975f15d BM |
512 | triple-DES and then include the related certificates either unencrypted or |
513 | with lower encryption. Yes it's the dreaded crypto laws at work again which | |
514 | allow strong encryption on private keys and only weak encryption on other | |
515 | stuff. | |
b64f8256 DSH |
516 | |
517 | To build one of these things you turn all certificates and keys into safebags | |
518 | (with optional attributes). You collect the safebags into (one or more) STACKS | |
b975f15d BM |
519 | and convert these into authsafes (encrypted or unencrypted). The authsafes |
520 | are collected into a STACK and added to a PKCS12 structure. Finally a MAC | |
521 | inserted. | |
b64f8256 DSH |
522 | |
523 | Pulling one apart is basically the reverse process. The MAC is verified against | |
524 | the given password. The authsafes are extracted and each authsafe split into | |
525 | a set of safebags (possibly involving decryption). Finally the safebags are | |
526 | decomposed into the original keys and certificates and the attributes used to | |
527 | match up private key and certificate pairs. | |
528 | ||
529 | Anyway here are the functions that do the dirty work. | |
530 | ||
531 | 1. Construction functions. | |
532 | ||
533 | 1.1 Safebag functions. | |
534 | ||
535 | M_PKCS12_x5092certbag(x509) | |
536 | ||
537 | This macro takes an X509 structure and returns a certificate bag. The | |
538 | X509 structure can be freed up after calling this function. | |
539 | ||
540 | M_PKCS12_x509crl2certbag(crl) | |
541 | ||
542 | As above but for a CRL. | |
543 | ||
544 | PKCS8_PRIV_KEY_INFO *PKEY2PKCS8(EVP_PKEY *pkey) | |
545 | ||
546 | Take a private key and convert it into a PKCS#8 PrivateKeyInfo structure. | |
547 | Works for both RSA and DSA private keys. NB since the PKCS#8 PrivateKeyInfo | |
b975f15d BM |
548 | structure contains a private key data in plain text form it should be free'd |
549 | up as soon as it has been encrypted for security reasons (freeing up the | |
550 | structure zeros out the sensitive data). This can be done with | |
551 | PKCS8_PRIV_KEY_INFO_free(). | |
b64f8256 DSH |
552 | |
553 | PKCS8_add_keyusage(PKCS8_PRIV_KEY_INFO *p8, int usage) | |
554 | ||
555 | This sets the key type when a key is imported into MSIE or Outlook 98. Two | |
556 | values are currently supported: KEY_EX and KEY_SIG. KEY_EX is an exchange type | |
557 | key that can also be used for signing but its size is limited in the export | |
558 | versions of MS software to 512 bits, it is also the default. KEY_SIG is a | |
559 | signing only key but the keysize is unlimited (well 16K is supposed to work). | |
560 | If you are using the domestic version of MSIE then you can ignore this because | |
561 | KEY_EX is not limited and can be used for both. | |
562 | ||
563 | PKCS12_SAFEBAG *PKCS12_MAKE_KEYBAG(PKCS8_PRIV_KEY_INFO *p8) | |
564 | ||
b975f15d BM |
565 | Convert a PKCS8 private key structure into a keybag. This routine embeds the |
566 | p8 structure in the keybag so p8 should not be freed up or used after it is | |
567 | called. The p8 structure will be freed up when the safebag is freed. | |
b64f8256 DSH |
568 | |
569 | 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) | |
570 | ||
571 | Convert a PKCS#8 structure into a shrouded key bag (encrypted). p8 is not | |
572 | embedded and can be freed up after use. | |
573 | ||
574 | int PKCS12_add_localkeyid(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen) | |
575 | int PKCS12_add_friendlyname(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen) | |
576 | ||
577 | Add a local key id or a friendlyname to a safebag. | |
578 | ||
579 | 1.2 Authsafe functions. | |
580 | ||
581 | PKCS7 *PKCS12_pack_p7data(STACK *sk) | |
582 | Take a stack of safebags and convert them into an unencrypted authsafe. The | |
583 | stack of safebags can be freed up after calling this function. | |
584 | ||
585 | PKCS7 *PKCS12_pack_p7encdata(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, STACK *bags); | |
586 | ||
587 | As above but encrypted. | |
588 | ||
589 | 1.3 PKCS12 functions. | |
590 | ||
591 | PKCS12 *PKCS12_init(int mode) | |
592 | ||
593 | Initialise a PKCS12 structure (currently mode should be NID_pkcs7_data). | |
594 | ||
595 | M_PKCS12_pack_authsafes(p12, safes) | |
596 | ||
597 | This macro takes a STACK of authsafes and adds them to a PKCS#12 structure. | |
598 | ||
599 | int PKCS12_set_mac(PKCS12 *p12, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, EVP_MD *md_type); | |
600 | ||
601 | Add a MAC to a PKCS12 structure. If EVP_MD is NULL use SHA-1, the spec suggests | |
602 | that SHA-1 should be used. | |
603 | ||
604 | 2. Extraction Functions. | |
605 | ||
606 | 2.1 Safebags. | |
607 | ||
608 | M_PKCS12_bag_type(bag) | |
609 | ||
610 | Return the type of "bag". Returns one of the following | |
611 | ||
612 | NID_keyBag | |
613 | NID_pkcs8ShroudedKeyBag 7 | |
614 | NID_certBag 8 | |
615 | NID_crlBag 9 | |
616 | NID_secretBag 10 | |
617 | NID_safeContentsBag 11 | |
618 | ||
619 | M_PKCS12_cert_bag_type(bag) | |
620 | ||
621 | Returns type of certificate bag, following are understood. | |
622 | ||
623 | NID_x509Certificate 14 | |
624 | NID_sdsiCertificate 15 | |
625 | ||
626 | M_PKCS12_crl_bag_type(bag) | |
627 | ||
628 | Returns crl bag type, currently only NID_crlBag is recognised. | |
629 | ||
630 | M_PKCS12_certbag2x509(bag) | |
631 | ||
632 | This macro extracts an X509 certificate from a certificate bag. | |
633 | ||
634 | M_PKCS12_certbag2x509crl(bag) | |
635 | ||
636 | As above but for a CRL. | |
637 | ||
638 | EVP_PKEY * PKCS82PKEY(PKCS8_PRIV_KEY_INFO *p8) | |
639 | ||
640 | Extract a private key from a PKCS8 private key info structure. | |
641 | ||
642 | M_PKCS12_decrypt_skey(bag, pass, passlen) | |
643 | ||
644 | Decrypt a shrouded key bag and return a PKCS8 private key info structure. | |
645 | Works with both RSA and DSA keys | |
646 | ||
647 | char *PKCS12_get_friendlyname(bag) | |
648 | ||
649 | Returns the friendlyName of a bag if present or NULL if none. The returned | |
650 | string is a null terminated ASCII string allocated with Malloc(). It should | |
651 | thus be freed up with Free() after use. | |
652 | ||
653 | 2.2 AuthSafe functions. | |
654 | ||
655 | M_PKCS12_unpack_p7data(p7) | |
656 | ||
657 | Extract a STACK of safe bags from a PKCS#7 data ContentInfo. | |
658 | ||
659 | #define M_PKCS12_unpack_p7encdata(p7, pass, passlen) | |
660 | ||
661 | As above but for an encrypted content info. | |
662 | ||
663 | 2.3 PKCS12 functions. | |
664 | ||
665 | M_PKCS12_unpack_authsafes(p12) | |
666 | ||
667 | Extract a STACK of authsafes from a PKCS12 structure. | |
668 | ||
669 | M_PKCS12_mac_present(p12) | |
670 | ||
671 | Check to see if a MAC is present. | |
672 | ||
673 | int PKCS12_verify_mac(PKCS12 *p12, unsigned char *pass, int passlen) | |
674 | ||
675 | Verify a MAC on a PKCS12 structure. Returns an error if MAC not present. | |
676 | ||
677 | ||
678 | Notes. | |
679 | ||
680 | 1. All the function return 0 or NULL on error. | |
681 | 2. Encryption based functions take a common set of parameters. These are | |
682 | described below. | |
683 | ||
684 | pass, passlen | |
685 | ASCII password and length. The password on the MAC is called the "integrity | |
686 | password" the encryption password is called the "privacy password" in the | |
687 | PKCS#12 documentation. The passwords do not have to be the same. If -1 is | |
688 | passed for the length it is worked out by the function itself (currently | |
689 | this is sometimes done whatever is passed as the length but that may change). | |
690 | ||
691 | salt, saltlen | |
692 | A 'salt' if salt is NULL a random salt is used. If saltlen is also zero a | |
693 | default length is used. | |
694 | ||
695 | iter | |
696 | Iteration count. This is a measure of how many times an internal function is | |
697 | called to encrypt the data. The larger this value is the longer it takes, it | |
698 | makes dictionary attacks on passwords harder. NOTE: Some implementations do | |
699 | not support an iteration count on the MAC. If the password for the MAC and | |
700 | encryption is the same then there is no point in having a high iteration | |
701 | count for encryption if the MAC has no count. The MAC could be attacked | |
702 | and the password used for the main decryption. | |
703 | ||
704 | pbe_nid | |
705 | This is the NID of the password based encryption method used. The following are | |
706 | supported. | |
707 | NID_pbe_WithSHA1And128BitRC4 | |
708 | NID_pbe_WithSHA1And40BitRC4 | |
709 | NID_pbe_WithSHA1And3_Key_TripleDES_CBC | |
710 | NID_pbe_WithSHA1And2_Key_TripleDES_CBC | |
711 | NID_pbe_WithSHA1And128BitRC2_CBC | |
712 | NID_pbe_WithSHA1And40BitRC2_CBC | |
713 | ||
b975f15d | 714 | Which you use depends on the implementation you are exporting to. "Export |
33d50ef6 | 715 | grade" (i.e. cryptographically challenged) products cannot support all |
b975f15d BM |
716 | algorithms. Typically you may be able to use any encryption on shrouded key |
717 | bags but they must then be placed in an unencrypted authsafe. Other authsafes | |
718 | may only support 40bit encryption. Of course if you are using SSLeay | |
719 | throughout you can strongly encrypt everything and have high iteration counts | |
720 | on everything. | |
b64f8256 DSH |
721 | |
722 | 3. For decryption routines only the password and length are needed. | |
723 | ||
724 | 4. Unlike the external version the nid's of objects are the values of the | |
725 | constants: that is NID_certBag is the real nid, therefore there is no | |
726 | PKCS12_obj_offset() function. Note the object constants are not the same as | |
727 | those of the external version. If you use these constants then you will need | |
728 | to recompile your code. | |
729 | ||
730 | 5. With the exception of PKCS12_MAKE_KEYBAG(), after calling any function or | |
731 | macro of the form PKCS12_MAKE_SOMETHING(other) the "other" structure can be | |
732 | reused or freed up safely. | |
733 | ||
33d50ef6 | 734 | LocalWords: PKIX keyUsage |