The certificate manipulation API is a C++ interface. C++ must be used to retrieve the certificates into trust lists and manipulate them there.
The contents of the
/usr/include/dce/asn.h
and
/usr/include/dce/x509.h
header files define some of the basic types used by the low-level certificate manipulation routines, including the actual structure of certificates. Following is a list of the low-level certificate routines defined in the
/usr/include/dce/pkc_certs.h
file:
· pkc_add_trusted_key(3sec)
· pkc_lookup_keys_in_trustlist(3sec)
· pkc_lookup_key_in_trustlist(3sec)
· pkc_lookup_element_in_trustlist(3sec)
· pkc_check_cert_against_trustlist(3sec)
· pkc_revoke_certificate(3sec)
· pkc_revoke_certificates(3sec)
· pkc_delete_trustlist(3sec)
· pkc_copy_trustlist(3sec)
· pkc_display_trustlist(3sec)
Implementation of a policy module consists essentially of writing a retrieve_key( ) routine that will return public keys found in certificates. The module will find certificates for principal names according to the rules set out for that module, verify their signatures, and return the public keys found in them to the original callers.
Certificate Revocation Lists (CRLs)
Certificate revocation lists are lists of certificates whose contents are no longer to be believed. Use of CRLs is policy-specific. pkc_certs provides objects for parsing and manipulating CRLs, and for using them to invalidate portions of a trust list.
Accessing a Registered Policy Module
Policy modules are registered in the form of pkc_policy_t structures, which contain the entry points for the following developer-written routines:
open( )
opens the module
close( )
closes the module
retrieve_keyinfo( )
returns the public key for a specified principal name
name( )
returns the policy module name
establish_trustbase( )
establishes a trust base
delete_trustbase( )
deletes a trust base
delete_keyinfo( )
deletes a keyinfo handle
get_key_count( )
returns the number of keys a keyinfo handle contains
get_key_data( )
retrieves an individual key
get_key_trust( )
returns the type of trust established for a specific key
get_key_certifier_count( )
returns the number of certifiers in the trust path that certified a key
get_key_certifier_info( )
returns information about a specific certifier of a key
The pkc_policy_t structure also contains the following data fields:
· a certificate version number
· an object identifier (OID) identifying the policy module
Policy modules, similarly to signature algorithms (cryptographic modules), are identified by object identifiers (the character string returned by name( ) is intended for use in diagnostic or auditing messages).
Also similarly to cryptographic modules, there are two ways in which cryptographic modules can be accessed: either by a single call to which the identifying OID is passed (this is the recommended method); or by calling pkc_plcy_lookup_policy(3sec) and then (for example) the module's (*retrieve_key)( ) routine to obtain the public key (a list of the OIDs of all currently registered policy modules can be obtained by calling pkc_plcy_get_registered_policies( )).
You must implement the following routines in any policy module:
name( )
Returns the name of the policy.
establish_trustbase( )
Creates a trust base, which is a policy-specific data structure based on the initial set of trusted keys.
retrieve_keyinfo( )
Given a trust base, returns a handle to keys for a specific principal.
delete_trustbase( )
Deletes a trust base.
delete_keyinfo( )
Deletes a keyinfo handle.
get_key_count( )
Given a keyinfo handle, returns the number of keys it contains.
get_key_data( )
Retrieves an individual key from a keyinfo handle
get_key_trust( )
Returns the type of trust established for a specific key, and the purpose(s) for which that trust applies.
The following policy routines are optional:
open( )
close( )
These routines perform any initialization and/or finalization tasks required by the module.
get_key_certifier_count( )
This routine is required only for policies that return CERTIFIED_TRUST keys; it returns the number of certifiers in the trust path that
certified a key.
get_key_certifier_info( )
This routine is required if the module implements get_key_certifier_count( ). It returns information about a specific certifier with the
certification path of a specific key. Certifier 0 is the immediate certifier of the key; certifier 1 is the CA that certified certifier 0, and so on.
Once you have implemented all necessary routines for you module, you must create a pkc_policy_t structure containing their entrypoints. Unimplemented routines' entrypoints should be specified as NULL.
The module is registered by calling the registration function and passing it a pkc_policy_t structure, which contains the entry points for the module routines described above:
pkc_plcy_register_policy( )