NAME
   sec_key_mgmt_get_key - Retrieves a key from local storage

 SYNOPSIS

 #include <dce/keymgmt.h>

 void sec_key_mgmt_get_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.  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 to whom the key belongs.

 key_vno
        The version number of the desired key. To return the latest
        version of the key, set this parameter to sec_c_key_version_none.

 Output

 keydata
        A pointer to a value of type sec_passwd_rec_t. The storage for
        keydata is allocated dynamically, so the returned pointer
        actually indicates a pointer to the key value.  The storage for
        this data may be freed with the sec_key_mgmt_free_key() routine.

 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_get_key() routine extracts the specified key from
 the local key store.

 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 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.

 sec_s_no_memory
              Unable to allocate memory.

 error_status_ok
              The call was successful.

 RELATED INFORMATION

 Functions: sec_intro