Name

dced_keytab_add_key - Adds a key (server password) to a specified key table on a specific host

Synopsis

#include <dce/dced.h> void dced_keytab_add_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 that dced uses to identify the key table to which the key is to be added. 

Input/Output

keySpecifies the key to be added.  Some fields are completed by dced.  See dced_intro(3dce). 

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_add_key() routine adds a key to a server’s key table (file) on a specific host, without changing the key in the security registry.  (Servers use sec_key_mgmt_set_key(3sec) to do this for their own local key table.) 

Most management applications use the dced_keytab_change_key() routine to remotely change a key because it also changes the key in the security registry. 

Managing the same key in multiple key tables is a more complex process.  The security registry needs a copy of a server’s key, so that during the authentication process, it can encrypt tickets that only a server with that key can later decrypt.  Part of updating a key in the security registry also includes automatic version number updating.  When servers share the same principle identity they use the same key.  If these servers are on different hosts, then the key must be in more than one key table.  (Even if the servers are on the same host, it is possible for their keys to be in different key tables, although this is not a recommended key management practice.)  When the same keys in different tables need changing, one (perhaps the master server or busiest one) is changed using dced_keytab_change_key() which also causes an automatic version update.  However, all other copies of the key must be changed using the dced_keytab_add_key() routine so that the version number does not change again. 

Prior to calling dced_keytab_add_key() 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

db_s_bad_index_type

db_s_key_not_found

dced_s_bad_binding

dced_s_key_v0_not_allowe

dced_s_key_version_mismatch

dced_s_need_privacy

dced_s_random_key_not_allowed

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_key_unavailable

sec_key_mgmt_e_key_unsupported

sec_key_mgmt_e_key_version_exists

sec_key_mgmt_e_unauthorized

Related Information

Functions: dced_binding_create(3dce), dced_binding_from_rpc_binding(3dce), dced_keytab_change_key(3dce), sec_key_mgmt_set_key(3sec). 

Books: OSF DCE Application Development Guide.