dced_keytab_change

dced_keytab_change_key(3dce)

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

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

Input/Output

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

Output

status
Returns 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(3sec) 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 if the server calls sec_key_mgmt_garbage_collect( ) to purge its old keys explicitly, or sec_key_mgmt_manage_key( ) to purge them implicitly.

When more than one server shares the same principal identity, they 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