NAME

pkc_retrieve_keyinfo — Returns information about a key

Synopsis

unsigned32 pkc_retrieve_keyinfo(
trustbase_t ∗ base,
char ∗ name,
utc_t ∗ key_date,
uuid_t ∗ key_domain,
unsigned long ∗ key_usages,
selection_t ∗ sel,
keyinfo_t ∗∗ keyinfobase);

Parameters

Input

baseThe trust base, returned by pkc_init_trustbase(3sec). 

namePrincipal name. 

key_dateSpecifies time for which information is to be returned. 

key_domain
Allows the user to restrict the key-search operation to keys for a particular domain. Specify sec_pk_domain_unspecified or NULL to indicate that keys for any domain should be retrieved. 

key_usagesAllows the user to restrict the key-search operation to keys intended for one or more specific usages. 

selMust be 0 (currently ignored). 

Output

keyinfobaseThe returned key information. 

Description

pkc_retrieve_keyinfo(3sec) returns a keyinfo_t structure describing the set of trusted keys that are valid for the specified principal at the specified date, under any additional constraints specified in sel. 

The key_usages parameter consists of a bit mask, formed by AND-ing together one or more of the 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 key_usages to indicate that keys for any usage should be retrieved. 

This routine must be called before any of the following routines can be called:

   •pkc_get_key_count(3sec)

   •pkc_get_key_data(3sec)

   •pkc_get_key_trust_info(3sec)

   •pkc_get_key_certifier_count(3sec)

   •pkc_get_key_certifier_info(3sec)

Upon successful return, keyinfobase will contain a keyinfo_t structure which must be passed in calls to the above routines, which then extract and return the requested information. 

The keyinfo_t structure must be released by a call to pkc_free_keyinfo(3sec) when the application has finished with it. 

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_intro(3sec), 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_keylist(3sec).