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_bh
       Specifies the dced binding handle for the keytab service on
       a specific host.

   keytab_uuid
       Specifies the keytab entry dced associates with a key table.

   Output

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

   status
       Returns the status code from this routine.  This status code
       indicates whether the routine completed successfully or, if
       not, why not.  The possible status codes are:

            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

 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.

 RELATED INFORMATION

   Routines:   dced_keytab_get_next_key
               dced_keytab_release_cursor
               sec_key_mgmt_initialize_cursor
               dced_binding_create
               dced_binding_from_rpc_binding

   Books: OSF DCE Application Development Guide.