### High Level Certification API

The following certification API routines are intended for general DCE application use:

· pkc_get_registered_policies(3sec)

· pkc_init_trustlist(3sec)

· pkc_append_to_trustlist(3sec)

· pkc_init_trustbase(3sec)

· pkc_retrieve_keyinfo(3sec)

· pkc_get_key_count(3sec)

· pkc_get_key_data(3sec)

· pkc_get_key_trust_info(3sec)

· pkc_get_key_certifier_count(3sec)

· pkc_get_key_certifier_info(3sec)

· pkc_free_trustlist(3sec)

· pkc_free_trustbase(3sec)

· pkc_free_keyinfo(3sec)

· pkc_free(3sec)

Key retrieval consists basically of two operations:

1. Generating an "initial trust base'' - a starting point for future certification paths, consisting of a list of principals and their keys. An application would normally generate its initial trust base on startup.

2. Using the trust base to retrieve key(s) for a specified principal.

In outline, a typical pattern for an application's use of the high-level API might proceed according to the following series of calls:

1. pkc_get_registered_policies(3sec)
Called once for the lifetime of the application. It returns a set of OIDs, which point to all currently installed policies.

2. pkc_init_trustlist(3sec)
The caller creates an empty "trust list'' to hold the set of certificates it initially trusts.

3. pkc_append_to_trustlist(3sec)
Called one or more times, to add certificates or keys which the caller trusts to its list of trusted keys. (Steps 2 and 3 together build up the initial trust list.)

4. pkc_init_trustbase(3sec)
Computes a trust base, given the initial trust list. The caller uses one of the OIDs returned in Step 1, together with the list of trust items constructed in Steps 2 and 3, to access a policy and initialize a "trust base'' containing all the certificates initially trusted under the specified policy, given the initial list of trusted keys.

5. pkc_retrieve_keylist(3sec)
Called one or more times, for each individual's public key that needs to be looked up.

6. pkc_free_trustlist(3sec)
Frees storage allocated for the trust list.

7. pkc_free_trustbase(3sec)
Frees storage allocated for the trust base.

###