Name

dced_keytab_initialize_cursor - Obtains a list of keys from a key table and sets a cursor at the beginning of the list

Synopsis

#include <dce/dced.h> void dced_keytab_initialize_cursor(
dced_binding_handle_t dced_bh,
uuid_t ∗keytab_uuid,
dced_keytab_cursor_t ∗cursor,
error_status_t ∗status);

Parameters

Input

dced_bhSpecifies the dced binding handle for the keytab service on a specific host. 

keytab_uuidSpecifies the keytab entry dced associates with a key table. 

Output

cursorReturns the cursor that is used to traverse the list of keys. 

statusReturns the status code from this routine.  This status code indicates whether the routine completed successfully or, if not, why not. 

Description

The dced_keytab_initialize_cursor() routine obtains the complete list of keys from a remote key table and sets a cursor at the beginning of the cached list keys.  In order to minimize the security risks of keys exposed to the network, the entire set of keys are encrypted and transferred in one remote procedure call rather than individually or in chunks.  The cursor is then used in subsequent calls to dced_keytab_get_next_key() to obtain individual keys.  When the application is finished traversing the key list, it should call dced_keytab_release_cursor() to release the resources previously allocated. 

Management applications use dced_keytab_initialize_cursor() and its associated routines to remotely access server keys.  Servers use sec_key_mgmt_initialize_cursor() and its associated routines to manage their own keys locally. 

Prior to calling the dced_keytab_initialize_cursor() routine, the application must have established a valid dced binding handle to the keytab service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. 

Errors

The following describes a partial list of errors that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

error_status_ok

dced_s_bad_binding

dced_s_need_privacy

dced_s_no_memory

dced_s_no_support

sec_acl_invalid_permission

sec_key_mgmt_e_authn_invalid

sec_key_mgmt_e_unauthorized

Related Information

Functions: dced_binding_create(3dce), dced_binding_from_rpc_binding(3dce), dced_keytab_get_next_key(3dce), dced_keytab_release_cursor(3dce), sec_key_mgmt_initialize_cursor(3sec). 

Books: OSF DCE Application Development Guide.