pkc_intro(3sec)

Description

This reference page describes the data types used by the trust list facility.

Overview of the Facility

Retrieving keys using this API is a three step process. The first step involves creating a pkc structure called a trust list, which reflects the caller's initial trust. A trust list is a list of {name, key} pairs or certificates that are trusted apriori.

An empty trust list is created through a call to the routine pkc_init_trustlist(3sec), and entries are inserted into a trust list by a call to pkc_append_to_trustlist(3sec).

Once the trust list is complete, the application should next call pkc_init_trustbase(3sec). This routine takes the trust list and processes it to produce a structure called a trust base, which reflects any transitive trust, independent of the name of any desired target.

Creation of the trust base (and the prerequisite trust list) is expected to be performed at application startup, although it can be done any time prior to key retrieval. All processing up to this point is independent of the name(s) of principals whose keys are to be retrieved, and the trust base may be used for multiple key retrieval operations.

Once a trust base has been obtained, it may be used for key retrieval. Keys are retrieved for a given target principal using the pkc_retrieve_keys(3sec) routine, which takes a trust base and a name and returns an array of keys.

Data Structures

The following data structures are used by the trust list facilities.

· The trust_type_t type consists of an enumeration of the different possible varieties of trust:

- UNTRUSTED
No trust (e.g., unauthenticated).

- DIRECT_TRUST
Direct trust via third party (e.g., authenticated registry).

- CERTIFIED_TRUST
Trust certified by caller's trust base.

· The certification_flags_t structure describes the trust that can be placed in a returned key. It contains the following fields:

- trust_type
A trust_type_t value expressing the style of trust.

- missing_crls
A char; its value is TRUE (not 0) if one or more CRLs are missing.

- revoked
A char whose value is TRUE (not 0) if any certificate has been revoked (even if it was still valid at the retrieval time).

· The cert_t structure contains the following fields:

- version
An int whose value must be 0.

- cert
A pointer to an unsigned char representing the ASN.1 encoding of a certificate.

- size
A size_t which represents the size of the encoding.

· The trusted_key_t structure contains the following fields:

- version
An int whose value must be 0.

- ca
A pointer to an unsigned char (x500 char) string which represents the name of the Certification Authority whose key this is. For example, /.../foo_cell/ca or /.../C=US/O=dec/CN=foo_cell/ca.

- key
A pointer to an unsigned char representing the Certification Authority's ASN.1 key.

- size
A size_t representing the size of the CA's ASN.1 key.

- startDate
A utc_t representing the time at which the key begins to be valid.

- endDate
A utc_t representing the time at which the key ceases to be valid.

· The trustitem_t structure holds either a key, or a certificate. It has the following fields:

- type
An int whose value specifies either that the structure holds a key (IS_KEY) or a certificate (IS_CERT).

- Depending on the value of type, the structure additionally contains a trusted_key_t (if IS_KEY) or a cert_t (if IS_CERT).

· The selection_t structure is defined for future enhancements that will enable users to specify usages for the key being retrieved. However, its contents are currently ignored.

Related Information

Functions:
pkc_append_to_trustlist(3sec)
pkc_free(3sec)
pkc_free_keyinfo(3sec)
pkc_free_trustbase(3sec)
pkc_free_trustlist(3sec)
pkc_get_key_certifier_count(3sec)
pkc_get_key_certifier_info(3sec)
pkc_get_key_count(3sec)
pkc_get_key_data(3sec)
pkc_get_key_trust_info(3sec)
pkc_get_registered_policies(3sec)
pkc_init_trustbase(3sec)
pkc_init_trustlist(3sec)
pkc_retrieve_keyinfo(3sec)
pkc_retrieve_keylist(3sec)