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

 NAME
   sec_key_mgmt_delete_key - Deletes a key from the local storage

 SYNOPSIS

   #include <dce/keymgmt.h>

   void sec_key_mgmt_delete_key(
           sec_key_mgmt_authn_service authn_service,
           void *arg,
           idl_char *principal_name,
           unsigned32 key_vno,
           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 deleted.

   key_vno
          The version number of the desired key.

   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_delete_key() routine deletes the specified key from
   the local key store. If an administrator ever discovers or suspects that
   the security of a server's key has been compromised, the administrator
   should delete the key immediately with sec_key_mgmt_delete_key().  This
   routine removes the key from the local key storage, which invalidates
   all extant tickets encoded with the key. If the compromised key is the
   current one, the principal should change the key with
   sec_key_mgmt_change_key() before deleting it. It is not an error for a
   process to delete the current key (as long as it is done after the
   network context has been established), but it may seriously
   inconvenience legitimate clients of a service.

   This routine deletes all key types that have the specified key version
   number.  A key type identifies the data encryption algorithm being used
   (for example, DES).  This routine differs from
   sec_key_mgmt_delete_key_type() in that sec_key_mgmt_delete_key_type()
   deletes only the specified key version of the specified key type from
   the local key store.

 FILES
     SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
                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 requested key is not present.

   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.

   error_status_ok
                The call was successful.

 RELATED INFORMATION

   Functions: sec_intro
              sec_key_mgmt_delete_key_type
              sec_key_mgmt_garbage_collect