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