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

   keytab_uuid
          Specifies the UUID that dced uses to identify the key table
          to which the key is to be added.

   Input/Output

   key    Specifies the key to be added.  Some fields are completed
          by dced.  See dced_intro.

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

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

 RELATED INFORMATION

   Routines:   dced_keytab_change_key
               sec_key_mgmt_set_key
               dced_binding_create
               dced_binding_from_rpc_binding

   Books: OSF DCE Application Development Guide.