Name

dced_keytab_change_key - Changes a key (server password) in both a key table and in the security registry

Synopsis

#include <dce/dced.h> void dced_keytab_change_key(
dced_binding_handle_t dced_bh,
uuid_t ∗keytab_uuid,
dced_key_t ∗key,
error_status_t ∗status);

Parameters

Input

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

keytab_uuidSpecifies the UUID dced uses to identify the key table in which the key is to be changed. 

Input/Output

keySpecifies the new key.  Some fields are modified by dced. 

Output

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_change_key() routine updates a key in both the key table on a specific host and in the security registry.  Management applications change keys remotely with this routine.  (Servers can change their own keys locally with the sec_key_mgmt_change_key() routine.) 

The security registry needs a copy of a server’s current key, so that during the authentication process, it can encrypt tickets that only a server with that key can later decrypt.  When a management application calls dced_keytab_change_key(), dced first tries to make the modification in the security registry, and, if successful, it then modifies the key in the key table.  The old key is not really replaced, but a new version and key is established for all new authenticated communication.  The old version is maintained in the key table (and registry too) for a time, so that existing clients with valid tickets can still communicate with the server.  The old key is removed depending on the local cell’s change policy and whether the server calls sec_key_mgmt_garbage_collect() to purge its old keys explicitly, or calls sec_key_mgmt_manage_key() to purge them implicitly. 

When more than one server shares the same principal identity, the servers use the same key.  If you need to change the same key in more than one key table, use decd_keytab_change_key() for one change and then use the dced_keytab_add_key() routine for all others. 

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

db_s_bad_index_type

db_s_key_not_found

dced_s_bad_binding

dced_s_key_version_mismatch

dced_s_need_privacy

rpc_s_binding_has_no_auth

rpc_s_invalid_binding

rpc_s_wrong_kind_of_binding

sec_acl_invalid_permission

sec_key_mgmt_e_authn_invalid

sec_key_mgmt_e_authn_unavailable

sec_key_mgmt_e_key_unavailable

sec_key_mgmt_e_key_unsupported

sec_key_mgmt_e_key_version_exists

sec_key_mgmt_e_not_implemented

sec_key_mgmt_e_unauthorized

sec_rgy_object_not_found

sec_rgy_server_unavailable

Related Information

Functions: dced_binding_create(3dce), dced_binding_from_rpc_binding(3dce), dced_keytab_add_key(3dce), sec_key_mgmt_change_key(3sec). 

Books: OSF DCE Application Development Guide.