NAME
   sec_key_mgmt_gen_rand_key - Generates a new random key of a specified
                               key type

 SYNOPSIS

 #include <dce/keymgmt.h>

 void sec_key_mgmt_gen_rand_key(
         sec_key_mgmt_authn_service authn_service,
         void *arg,
         idl_char *principal_name,
         void *keytype,
         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 for whom the key is to be generated.

 keytype
        A pointer to a value of type sec_passwd_type_t.  The value
        identifies the data encryption algorithm to be used for the key
        (for example, DES).

 key_vno
        The version number of the new key.

 Output

 keydata
        A pointer to a value of 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() function.

 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_gen_rand_key() routine generates a new random key
 for a specified principal and of a specified key type.  The generated
 key can be used with the sec_key_mgmt_change_key() and
 sec_key_mgmt_set_key() routines.

 Note that to initialize the random keyseed, the process must first
 make an authenticated call such as sec_rgy_site_open().

 FILES
   SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
              The idl file from which dce/keymgmt.h was derived.

 ERRORS

 sec_key_mgmt_e_not_implemented
              The specified keytype is not supported.

 sec_s_no_key_seed
              No random key seed has been set.

 sec_s_no_memory
              Unable to allocate memory.

 error_status_ok
              The call was successful.

 RELATED INFORMATION

 Functions: sec_intro
            sec_key_mgmt_change_key
            sec_key_mgmt_generate_key
            sec_key_mgmt_set_key