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_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.  The possible status codes are:

            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

 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 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.

 RELATED INFORMATION

   Routines:   dced_keytab_add_key
               sec_key_mgmt_change_key
               dced_binding_create
               dced_binding_from_rpc_binding

   Books: OSF DCE Application Development Guide.