NAME

pkc_get_key_trust_info — Returns information about key trust

Synopsis

unsigned32 pkc_get_key_trust_info(
keyinfo_t  ∗ keyinfobase,
unsigned key_index,
certification_flags_t ∗ flags,
uuid_t ∗ key_domain,
unsigned long ∗ key_usages);

Parameters

Input

keyinfobaseKey information, returned by pkc_retrieve_keyinfo(3sec). 

key_indexIndex of the key, ranging from 0 to keycount - 1. 

Output

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

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

key_usagesIndicates usage key is intended for. 

Description

pkc_get_key_trust_info(3sec) returns a set of flags describing the trust that can be placed in the key. 

The desired information is extracted by the routine from the keyinfo_t structure, which must first be obtained by the caller by a call to the pkc_retrieve_keyinfo(3sec) routine. 

The returned certification_flags_t structure describes the trust that can be placed in a returned 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 key_domain and key_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 key_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 key_usages value of NULL (or a value with all bits set) means that the key is suitable for any usage. 

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_registered_policies(3sec), pkc_init_trustbase(3sec), pkc_init_trustlist(3sec), pkc_retrieve_keyinfo(3sec), pkc_retrieve_keylist(3sec).