pkc_plcy_get_key_trust(3sec)

Synopsis

#include <pkc_plcy.h>

unsigned32 pkc_plcy_get_key_trust(

gss_OID policy,

void * keys_handle,

unsigned key_index,

certification_flags_t * flags,

uuid_t * key_domain,

unsigned long * key_usages);

Parameters

Input

policy
Specifies policy.

keys_handle
A policy specific structure, obtained from a call to pkc_plcy_retrieve_keyinfo(3sec).

key_index
Specifies key about which trust information is requested.

Output

flags
Information 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_usages
Indicates usage key is intended for.

Description

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

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.

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_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_registered_policies(3sec)
pkc_plcy_lookup_policy(3sec)
pkc_plcy_register_policy(3sec)
pkc_plcy_retrieve_keyinfo(3sec)