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

 NAME
   sec_key_mgmt_manage_key - Automatically changes a principal's key before
                             it expires

 SYNOPSIS

   #include <dce/keymgmt.h>

   void sec_key_mgmt_manage_key(
           sec_key_mgmt_authn_service authn_service,
           void *arg,
           idl_char *principal_name,
           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 routine.
          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 managed.

   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_manage_key() routine changes the specified principal's
   key on a regular basis, as determined by the local cell's policy.  It
   will run indefinitely, never returning during normal operation, and
   therefore should be invoked only from a thread that has been devoted to
   managing keys.

   This routine queries the DCE Registry to determine the password
   expiration policy that applies to the named principal.  It then idles
   until a short time before the current key is due to expire and then uses
   the sec_key_mgmt_gen_rand_key() to produce a new random key, updating
   both the local key store and the DCE Registry.  This routine also
   invokes sec_key_mgmt_garbage_collect() as needed.

 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_key_unsupported
                The key type is not supported.

   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_rgy_server_unavailable
                The DCE Registry Server is unavailable.

   sec_rgy_object_not_found
                No principal was found with the given name.

   error_status_ok
                The call was successful.

 RELATED INFORMATION

   Functions: sec_intro
              sec_key_mgmt_gen_rand_key
              sec_key_mgmt_garbage_collect