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

 NAME
   sec_key_mgmt_change_key - Changes a principal's key

 SYNOPSIS

   #include <dce/keymgmt.h>

   void sec_key_mgmt_change_key(
           sec_key_mgmt_authn_service authn_service,
           void *arg,
           idl_char *principal_name,
           unsigned32 key_vno,
           void *keydata,
           sec_timeval_period_t *garbage_collect_time,
           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.  You must
          prepend the file's absolute filename with FILE: and the file
          must have been created with the rgy_edit ktadd command or the
          sec_key_mgmt_set_key function.
          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 whose key is to be changed.

   key_vno
          The version number of the new key. If 0 (zero) is specified,
          the routine will select the next appropriate key version number.

   keydata
          A pointer to a structure of type sec_passwd_rec_t.

   Output

   garbage_collect_time
          The number of seconds that must elapse before all currently
          valid tickets (which are encoded with the current or previous
          keys) expire.  At that time, all obsolete keys may be "garbage
          collected", since no valid tickets encoded with those keys will
          remain outstanding on the network.

   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_change_key() routine performs all activities necessary
   to update a principal's key to the specified value.  This includes
   updating any local storage for the principal's key and also performing
   any remote operations needed to keep the authentication protocol (or
   network registry) current.  Old keys for the principal are garbage
   collected if appropriate.

 FILES

                The idl file from which dce/keymgmt.h was derived.

 ERRORS

   Any error condition will leave the key state unchanged.

   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_auth_unavailable
                The authentication protocol is not available to update
                the network database or to obtain the necessary network
                credentials.

   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.

   sec_rgy_server_unavailable
                The DCE Registry Server is unavailable.

   sec_rgy_object_not_found
                No principal was found with the given name.

   sec_login_s_no_memory
                A memory allocation error occurred.

   error_status_ok
                The call was successful.

 RELATED INFORMATION

   Functions: sec_intro
              sec_key_mgmt_generate_key
              sec_key_mgmt_set_key