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

 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