pkc_plcy_retrieve_keyinfo(3sec)

Synopsis

#include <pkc_certs.h>

unsigned32 pkc_plcy_retrieve_keyinfo(

gss_OID policy,

const void * trust_base_handle,

const x500name & subjectName,

const utc_t * date,

const uuid_t & desired_domain,

pkc_key_usage_t desired_usage,

char initial_explicit_policy_required,

void ** keys_handle);

Parameters

Input

policy
Specifies the policy being interrogated

trust_base_handle
Expresses the caller's initial trust.

subjectName
Specifies the desired subject name (principal name).

date
Specifies time for which information is to be returned.

desired_domain
Specifies 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
Allows the user to restrict the key-search operation to keys intended for one or more specific usages.

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

Output

keys_handle
The returned key information.

Description

pkc_plcy_retrieve_keyinfo(3sec) searches the list of registered policies for implementations of the specified policy. If found, the implementation is opened, if necessary, and its (retrieve_key_info)( ) function is invoked. Necessary mutex protection around non-thread safe policy implementations is provided.

The desired_usage parameter is 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.

Return Values

pkc_s_success

peration successfully completed.

Errors

Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.

Related Information

Functions:
pkc_plcy_intro(3sec)
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_plcy_register_policy(3sec)