policy_intro(3sec)

Description

This reference page describes the data types used by the policy module registration and service API.

The routines documented here are intended for the use of policy implementors. Regular users invoke a policy via the high-level API (e.g., pkc_retrieve_keyinfo(3sec), pkc_get_key_count(3sec), pkc_get_key_data(3sec), etc.) which calls the routines documented below internally.

Accessing Policy Modules

Policy modules are identified by OIDs (object identifiers). A policy module is accessed by passing its identifying OID to pkc_plcy_lookup_policy(3sec).

There are two ways of retrieving a key: either by looking up the desired policy module and then explicitly calling its (retrieve_keyinfo)( ) routine; or by simply calling the pkc_plcy_retrieve_keyinfo(3sec) routine, identifying the desired policy by means of an OID passed directly to the call. The latter method, in which the operation is performed in one step, is the recommended one.

Policy Flags Data Type

The pkc_plcy_flags_t data type is used to record various information about a policy module. It is defined as follows:

typedef struct {

char threadsafe;

char multi_session;

} pkc_plcy_flags_t;

The structure contains two fields which have the following meanings:

threadsafe
Has a non-zero (TRUE) value if the policy's retrieve_keyinfo( ) function may be safely called simultaneously (within a single policy session) by multiple threads.

multi_session
Has a non-zero (TRUE) value if the policy implementation supports multiple simultaneous policy sessions.

Policy Module Data Type

The pkc_policy_t data type is used to register a new policy module with the certification API. It fully describes a policy module's functionality, and provides entry points to its key retrieval functions. It is defined as follows:

typedef struct {

OM_uint32 version;

gss_OID_desc policy_id;

pkc_plcy_flags_t flags;

char reserved[32 - sizeof(pkc_plcy_flags_t)];

char * (* name) (void);

unsigned32 (*open) (void** context);

unsigned32 (*close) (void** context);

unsigned32 (*establish_trustbase) (void ** context,

const pkc_trust_list_t & initial_trust,

const utc_t * date,

pkc_usage_t desired_usage,

char initial_explicit_policy_required,

pkc_trust_list_t & out_trust);

unsigned32 (*retrieve_keyinfo) (void ** context,

const pkc_trust_list_t &trust,

const x500name &subjectName,

const utc_t * date,

const uuid_t & domain,

pkc_key_usage_t desired_usage,

char initial_explicit_policy_required,

pkc_key_information_t &key);

unsigned32 (*delete_trustbase) (void ** context,

void ** trust_base_handle);

unsigned32 (*delete_keyinfo) (void ** context,

void ** keys_handle);

unsigned32 (*get_key_count) (void ** context,

void * keys_handle,

size_t * key_count);

unsigned32 (*get_key_data) (void ** context,

void * keys_handle,

unsigned key_index,

unsigned char ** key_data,

size_t * key_length);

unsigned32 (*get_key_trust) (void ** context,

void * keys_handle,

unsigned key_index,

certification_flags_t * flags,

uuid_t * domain,

pkc_generic_key_usage_t * usages);

unsigned32 (*get_key_certifier_count) (void ** context,

void * keys_handle,

unsigned key_index,

size_t * ca_count);

unsigned32 (*get_key_certifier_info) (void ** context,

void * keys_handle,

unsigned key_index,

unsigned ca_index,

char**ca_name,

utc_t * certification_start,

utc_t * certification_expiration,

char * is_crl_valid,

utc_t * last_crl_seen,

utc_t * next_crl_expected);

} pkc_policy_t;

The (name)( ), (open)( ), (close)( ), (establish_trustbase( ), (*get_key_count)( ), (*get_key_data)( ), (*get_key_trust)( ), (*get_key_certifier_count)(~), (*get_key_certifier_info)( ), and (retrieve_keyinfo)( ) routines must be implemented by the application implementing the module and registered using the pkc_register_policy(3sec) routine. Note, however, that only (retrieve_keyinfo)( ), (*get_key_count)( ), (*get_key_certifier_count)( ) and (*get_key_data)( ) are required. Explanations of all the fields in pkc_policy_t are contained in the following subsections.

Policy Module Data Fields

The structure contains the following data fields:

version
Identifies the version of the certification API for which the module is implemented. The value of this field is always pkc_V1 for DCE 1.2.

policy_id
An object identifier that identifies the policy.

flags
Describes whether the module's key retrieval function is threadsafe, and whether the module supports simultaneous policy sessions.

The version and alg_id fields are required for all versions of this data structure. Other fields may be version dependent.

Policy Module Functions

NULL may be supplied as the address of the (name)( ), (open)( ), (establish_trustbase)( ) or (close)( ) routines, if the policy module does not provide or require the corresponding feature; the presence of these functions in a policy module is optional. However, all policy modules must provide a (retrieve_keyinfo)( ) function.

Name

(name)( )
Returns the policy name as a string, suitable for use in diagnostic or auditing messages
This routine is optional.

Synopsis

char * (* name) (void);

Description

The name should be returned in storage allocated using the pkc_malloc( ) function defined in pkc_common.h. The caller of this routine is expected to invoke pkc_free(3sec) to release the storage once the name is no longer required.

Note that this is the only policy module routine that may be called without first calling the (open)( ) routine.

Name

(open)( )
Opens and initializes the policy module

(close)( )
Closes the policy module
Both these routines are optional.

Synopsis

unsigned32 (*open) (void** context

unsigned32 (*close) (void** context);

Parameters

Output

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

Description

Before invoking any policy routines (e.g., (retrieve_keyinfo)( )), the certification API will invoke the module's (open)( ) function. Once the module's (close)( ) routine has been invoked, the certification facility will invoke (open)( ) again before making any further calls to the module.

Both the (open)( ) and the (close)( ) routines require only one argument, context. If the policy module requires state information to be maintained between calls, it may use the context parameter to do this. The information is initialized by the (open)( ) routine and returned as an opaque object to the caller, who then passes the parameter to subsequent (retrieve_keyinfo)( ), (establish_trustbase)( ), or (close)( ) calls.

Note that if the (open)( ) routine stores any state in the context parameter, the (close)( ) routine should free this storage.

Name

(establish_trustbase)( )
Initializes a trust base

Synopsis

unsigned32 (*establish_trustbase) (void ** context

const pkc_trust_list_t & initial_trust,

const utc_t * date,

char initial_explicit_policy_required,

pkc_trust_list_t & out_trust);

Parameters

Input

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

initial_trust
Specifies the caller's initial trust.

date
Specifies time for which information is to be returned.

initial_explicit_policy_required
Specifies whether the initial certificate must explicitly contain the active policy in its policies field.

Output

out_trust
An extended trust list.

Description

This is a one-time call made by an application to initialize a trust base. It returns the out_trust parameter, which contains an extended trust list. After this call is made, the application can call (retrieve_keyinfo)( ) to obtain the public keys of any particular principal. If the trust base does not change, (retrieve_keyinfo)( ) can be used to look up another principal's public key without incurring the cost of another call to (establish_trustbase)( ). A trust base will not change unless the initial_trust list changes.

Name

(*delete_trustbase)( )
Frees storage allocated for a trust base
This routine is optional.

Synopsis

unsigned32 (*delete_trustbase) (void ** context

void ** trust_base_handle);

Parameters

Input

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

keys_handle
A policy specific structure, contained in the keyinfo_t structure passed by the original caller.

Name

(*delete_keyinfo)( )
Frees storage allocated for key information
This routine is optional.

Synopsis

unsigned32 (*delete_keyinfo) (void ** context

void ** keys_handle);

Parameters

Input

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

keys_handle
A policy specific structure, contained in the keyinfo_t structure passed by the original caller.

Description

(*delete_keyinfo)( ) frees storage that was allocated for key information.

Name

(*get_key_count)( )
Returns number of keys
This routine is optional.

Synopsis

unsigned32 (*get_key_count) (void ** context

void * keys_handle,

size_t * key_count);

Parameters

Input

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

keys_handle
A policy specific structure, contained in the keyinfo_t structure passed by the original caller.

Output

key_count
Number of keys for the principal.

Description

(*get_key_count)( ) returns the number of keys for the principal. This value is determined by reference to the policy-specific structure pointed to by keys_handle, a field in the keyinfo_t structure passed by the original caller.

Name

(*get_key_data)( )
Returns a public key
This routine is optional.

Synopsis

unsigned32 (*get_key_data) (void ** context

void * keys_handle,

unsigned key_index,

unsigned char ** key_data,

size_t * key_length);

Parameters

Input

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

keys_handle
A policy specific structure, contained in the keyinfo_t structure passed by the original caller (see pkc_intro(3sec)).

key_index
Index (ranging from 0 to key_count - 1) of the key desired.

Output

key_data
The encoded public key.

key_length
Length of the key data returned.

Description

(*get_key_data)( ) returns the public key specified by index. The key_data returned is extracted from the policy-specific structure pointed to by keys_handle, a field in the keyinfo_t structure passed by the original caller.

key_data should be returned in storage allocated using the pkc_malloc( ) function defined in pkc_common.h.

Name

(*get_key_trust)( )
Returns information about key trust
This routine is optional.

Synopsis

unsigned32 (*get_key_trust) (void ** context

void * keys_handle,

unsigned key_index,

certification_flags_t * flags,

uuid_t * domain,

pkc_generic_key_usage_t * usages);

Parameters

Input

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

keys_handle
A policy specific structure, contained in the keyinfo_t structure passed by the original caller (see pkc_intro(3sec)).

key_index
Index (ranging from 0 to key_count - 1) of the key desired.

Output

flags
Information about the trust that can be placed in the key (see below).

domain
Indicates domain of retrieved key. A value of sec_pk_domain_unspecified or NULL means that the policy does not distinguish keys by domain.

usages
Indicates usage key is intended for.

Description

(*get_key_trust)( ) returns information about the trust reposed in the key specified by index. This information is determined by reference to the policy-specific structure pointed to by keys_handle, a field in the keyinfo_t structure passed by the original caller.

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

· trust_type
A trust_type_t value, which will be one of the following:

- 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.

· 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).

If domain and usages are passed as non-NULL pointers, upon successful return these parameters will describe the domain and permitted usage(s) of the specified key. Policies that do not distinguish keys according to domain will indicate a domain of sec_pk_domain_unspecified; policies that do not distinguish keys according to usage will indicate all usages are permitted.

The returned usages is a bit mask which describes the usage(s), if any, which the key is restricted to. The value is formed by AND-ing together one or more of the following constants:

PKC_KEY_USAGE_AUTHENTICATION
The key can be used to authenticate a user

PKC_KEY_USAGE_INTEGRITY
The key can be used to provide integrity protection

PKC_KEY_USAGE_KEY_ENCIPHERMENT
The key can be used to encrypt user keys

PKC_KEY_USAGE_DATA_ENCIPHERMENT
The key can be used to encrypt user data

PKC_KEY_USAGE_KEY_AGREEMENT
The key can be used for key-exchange

PKC_KEY_USAGE_NONREPUDIATION
The key can be used for non-repudiation

PKC_CAKEY_USAGE_KEY_CERT_SIGN
The key can be used to sign key certificates

PKC_CAKEY_USAGE_OFFLINE_CRL_SIGN
The key can be used to sign CRLs

PKC_CAKEY_USAGE_TRANSACTION_SIGN
The key can be used to sign transactions

A returned usages value of NULL (or a value with all bits set) means that the key is suitable for any usage.

Name

(*get_key_certifier_count)( )
Returns number of key's certifying authorities
This routine is optional.

Synopsis

unsigned32 (*get_key_certifier_count) (void ** context

void * keys_handle,

unsigned key_index,

size_t *ca_count);

Parameters

Input

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

keys_handle
A policy specific structure, contained in the keyinfo_t structure passed by the original caller (see pkc_intro(3sec)).

key_index
Index (ranging from 0 to key_count - 1) of the key desired.

Output

ca_count
Number of certifying authorities for the key.

Description

(*get_key_certifier_count)( ) returns the number of certifying authorities for the key specified by index. This information is determined from the policy-specific structure pointed to by keys_handle, a field in the keyinfo_t structure passed by the original caller.

Name

(*get_key_certifier_info)( )
Returns information about a certifying authority
This routine is optional.

Synopsis

unsigned32 (*get_key_certifier_info) (void ** context

void * keys_handle,

unsigned key_index,

unsigned ca_index,

char ** ca_name,

utc_t * certification_start,

utc_t * certification_expiration,

char * is_crl_valid,

utc_t * last_crl_seen,

utc_t * next_crl_expected);

Parameters

Input

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

keys_handle
A policy specific structure, contained in the keyinfo_t structure passed by the original caller (see pkc_intro(3sec)).

key_index
Index (ranging from 0 to key_count - 1) of the key desired.

ca_index
Index of the certifier about whom information is desired.

Output

ca_name
The name of the certifier.

certification_start
Time at which certification by this certifier starts.

certification_expiration
Time at which certification by this certifier ends.

is_crl_valid
If TRUE, there is a certificate revocation list for this certifier.

last_crl_seen
Time at which certificate revocation list was last seen.

next_crl_expected
Time at which next certificate revocation list is expected.

Description

(*get_key_certifier_info)( ) returns information about the certifying authority specified by ca_index for the key specified by key_index.

The desired information is extracted by the routine from the policy-specific structure pointed to by keys_handle, a field in the keyinfo_t structure passed by the original caller.

Note that any of the return parameters may be passed as NULL if the corresponding information is not required.

The certifier_name parameter should be returned in storage allocated using the pkc_malloc( ) function defined in pkc_common.h.

Name

(retrieve_keyinfo)( )
Returns the public key for the specified principal

Synopsis

unsigned32 (*retrieve_keyinfo) (void ** context

const void * trust_base_handle,

const x500name & subjectName,

const utc_t * date,

const uuid_t & domain,

pkc_key_usage_t desired_usage,

char initial_explicit_policy_required,

void ** keys_handle);

Parameters

Input

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

trust_base_handle
Specifies trust base.

subjectName
Specifies the desired subject name.

date
Specifies time for which information is to be returned.

domain
Specifies the particular domain to which the key-search operation should be restricted. Specify sec_pk_domain_unspecified or NULL to indicate that keys for any domain should be retrieved.

desired_usage
Specifies the one or more specific usages to which the key-search operation should be restricted.

initial_explicit_policy_required
Specifies whether the initial certificate must explicitly contain the active policy in its policies field.

Output

keys_handle
The handle to the public key for the specified target principal.

Description

The (retrieve_keyinfo)( ) routine reads the certificate for the specified principal name, verifies it, and (if the verification is successful) extracts the public key stored in it and returns it to the caller.

The returned key information handle can be interrogated by various pkc_cert_ routines to extract the actual key and determine the degree of trust that can be placed in the returned key.

If domain and desired_usage are passed as non-NULL pointers, upon successful return these parameters will describe the domain and permitted usage(s) of the specified key. Policies that do not distinguish keys according to domain will indicate a domain of sec_pk_domain_unspecified; policies that do not distinguish keys according to usage will indicate all usages are permitted.

The desired_usage parameter consists of a bit mask, formed by AND-ing together one or more of the following constants:

PKC_KEY_USAGE_AUTHENTICATION
The key can be used to authenticate a user

PKC_KEY_USAGE_INTEGRITY
The key can be used to provide integrity protection

PKC_KEY_USAGE_KEY_ENCIPHERMENT
The key can be used to encrypt user keys

PKC_KEY_USAGE_DATA_ENCIPHERMENT
The key can be used to encrypt user data

.PKC_KEY_USAGE_KEY_AGREEMENT
The key can be used for key-exchange

PKC_KEY_USAGE_NONREPUDIATION
The key can be used for non-repudiation

PKC_CAKEY_USAGE_KEY_CERT_SIGN
The key can be used to sign key certificates

PKC_CAKEY_USAGE_OFFLINE_CRL_SIGN
The key can be used to sign CRLs

PKC_CAKEY_USAGE_TRANSACTION_SIGN
The key can be used to sign transactions

A NULL can be specified for desired_usage to indicate that keys for any usage should be retrieved.

Note that some of the routine's parameters relate to X.509 version 3 certificates, support for which is not committed for DCE 1.2. The API has been designed with the intent that it be capable of supporting all currently defined versions of X.509, so that it need not change when version 3 support is added. For version 1 or version 2 policies and certificates, the desired_usage parameter will be ignored, and the initial_explicit_policy_required parameter must be zero (specifying, that is, that the policy need not explicitly appear in the first certificate).

Related Information

Functions:
pkc_plcy_delete_keyinfo(3sec)
pkc_plcy_delete_trustbase(3sec)
pkc_plcy_establish_trustbase(3sec)
pkc_plcy_get_key_certifier_count(3sec)
pkc_plcy_get_key_certifier_info(3sec)
pkc_plcy_get_key_count(3sec)
pkc_plcy_get_key_data(3sec)
pkc_plcy_get_key_trust(3sec)
pkc_plcy_get_registered_policies(3sec)
pkc_plcy_lookup_policy(3sec)
pkc_retrieve_keyinfo(3sec)
pkc_plcy_retrieve_keyinfo(3sec)
pkc_plcy_register_policy(3sec)