NAME

pkc_plcy_retrieve_keyinfo — Retrieves keys for specified principal

Synopsis

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

policySpecifies the policy being interrogated. 

trust_base_handle
Expresses the caller’s initial trust.

subjectName
Specifies the desired subject name (principal name).

dateSpecifies 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 consists of a bit mask, formed by AND-ing together one or more of the constants:

PKC_KEY_USAGE_AUTHENTICATION
Specifies keys that can be used to authenticate a user

PKC_KEY_USAGE_INTEGRITY
Specifies keys that can be used to provide integrity protection

PKC_KEY_USAGE_KEY_ENCIPHERMENT
Specifies keys that can be used to encrypt user keys

PKC_KEY_USAGE_DATA_ENCIPHERMENT
Specifies keys that can be used to encrypt user data

PKC_KEY_USAGE_KEY_AGREEMENT
Specifies keys that can be used for key-exchange

PKC_KEY_USAGE_NONREPUDIATION
Specifies keys that can be used for non-repudiation

PKC_CAKEY_USAGE_KEY_CERT_SIGN
Specifies keys that can be used to sign key certificates

PKC_CAKEY_USAGE_OFFLINE_CRL_SIGN
Specifies keys that can be used to sign CRLs

PKC_CAKEY_USAGE_TRANSACTION_SIGN
Specifies keys that 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
Operation 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_retrieve_key(3sec), pkc_register_policy(3sec).