VMS Help DCE_SECURITY, API Routines, sec_key_mgmt_set_key  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 NAME
   sec_key_mgmt_set_key - Inserts a key value into the local storage

 SYNOPSIS

   #include <dce/keymgmt.h>

   void sec_key_mgmt_set_key(
           sec_key_mgmt_authn_service authn_service,
           void *arg,
           idl_char *principal_name,
           unsigned32 key_vno,
           void *keydata,
           error_status_t *status);

 PARAMETERS

   Input

   authn_service
          Identifies the authentication protocol using this key.  The
          possible authentication protocols are as follows:

          rpc_c_authn_dce_secret
                      DCE shared-secret key authentication.

          rpc_c_authn_dce_public
                      DCE public key authentication (reserved for future
                      use).

   arg    This parameter can specify either the local key file or an
          argument to the get_key_fn key acquisition routine of the
          rpc_server_register_auth_info routine.  A value of NULL specifies
          that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be
          used.  A key file name specifies that file should be used as the
          key file. The file name must begin with FILE:.  If the file name
          does not begin with FILE:, the code will add it.  Any other value
          specifies an argument for the get_key_fn key acquisition routine.
          See the rpc_server_register_auth_info() reference page for more
          information.

   principal_name
          A pointer to a character string indicating the name of the
          principal associated with the key to be set.

   key_vno
          The version number of the key to be set.

   keydata
          A pointer to the key value to be set.

   Output

   status
          A pointer to the completion status.  On successful completion,
          the routine returns error_status_ok.  Otherwise, it returns an
          error.

 DESCRIPTION

   The sec_key_mgmt_set_key() routine performs all local activities
   necessary to update a principal's key to the specified value.  This
   routine will not update the authentication protocol's value for the
   principal's key.

   In some circumstances, a server may only wish to change its key in the
   local key storage, and not in the DCE Registry.  For example, a
   database system may have several replicas of a master database, managed
   by servers running on independent machines. Since these servers together
   represent only one service, they should all share the same key.  This
   way, a user with a ticket to use the database can choose whichever
   server is least busy. To change the database key, the master server
   would signal all the replica (slave) servers to change the current key
   in their local key storage. They would use the sec_key_mgmt_set_key()
   routine, which does not communicate with the DCE Registry. Once all the
   slaves have complied, the master server can then change the Registry key
   and its own local storage.

 FILES
         SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
                The idl file from which dce/keymgmt.h was derived.

 ERRORS

   sec_key_mgmt_e_key_unavailable
                The old key is not present and therefore cannot be used to
                set a client side authentication context.

   sec_key_mgmt_e_authn_invalid
                The authentication protocol is not valid.

   sec_key_mgmt_e_unauthorized
                The caller is not authorized to perform the operation.

   sec_key_mgmt_e_key_unsupported
                The key type is not supported.

   sec_key_mgmt_e_key_version_ex
                A key with this version number already exists.

   error_status_ok
                The call was successful.

 RELATED INFORMATION

   Functions: sec_intro
              sec_key_mgmt_change_key
              sec_key_mgmt_gen_rand_key