0208cef45792af1c759b7bcde1422243fd99e3e9
[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 "miscellaneous" 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 included 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 contains either the value itself
148 or how 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 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.
189
190 In addition it is also possible to use the word DER to include arbitrary
191 data in any extension.
192
193 1.2.3.4=critical,DER:01:02:03:04
194 1.2.3.4=DER:01020304
195
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
201
202 WARNING: DER should be used with caution. It is possible to create totally
203 invalid extensions unless care is taken.
204
205 CURRENTLY SUPPORTED EXTENSIONS.
206
207 Literal String extensions.
208
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.
213
214 For example:
215
216 nsComment="This is a test comment"
217
218 Bit Strings.
219
220 Bit string extensions just consist of a list of supported bits, currently
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,
228 keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign,
229 encipherOnly, decipherOnly.
230
231 For example:
232
233 nsCertType=server
234
235 keyUsage=critical, digitalSignature, nonRepudiation
236
237
238 Basic Constraints.
239
240 Basic constraints is a multi-valued extension that supports a CA and an
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.
252 According to PKIX recommendations it should exclude the extension entirely,
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
297 that would not make sense. It does support an additional issuer:copy option
298 that will copy all the subject alternative name values from the issuer 
299 certificate (if possible).
300
301 CRL distribution points.
302
303 This is a multi-valued extension that supports all the literal options of
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:
325 unfortunately this extension is often improperly encoded.
326
327 The certificate policies extension will rarely be used in practice: few
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.
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
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.
361
362 Example:
363
364 certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
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
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
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.
388
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
413 add all algorithms (you should at least add SHA1 though) then you can manually
414 initialise the PKCS#12 library with:
415
416 PKCS12_PBE_add();
417
418 The memory allocated by the PKCS#12 library is freed up when EVP_cleanup() is
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
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.
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
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.
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
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.
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
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().
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
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.
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
714 Which you use depends on the implementation you are exporting to. "Export
715 grade" (i.e. cryptographically challenged) products cannot support all
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.
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