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