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

 NAME
   sec_key_mgmt_get_next_kvno - Retrieves the next eligible key version
                                number for a key

 SYNOPSIS

   #include <dce/keymgmt.h>

   void sec_key_mgmt_get_next_kvno(
           sec_key_mgmt_authn_service authn_service,
           void *arg,
           idl_char *principal_name,
           void *keytype,
           unsigned32 *key_vno,
           unsigned32 *next_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 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 associated with the key.

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

   Output

   key_vno
          The current version number of the key.  Specify NULL if you do
          not need this value to be returned.

   next_key_vno
          The next eligible version number for the key.  Specify NULL if
          you do not need this value to be returned.

   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_next_kvno() routine returns the current and next
   eligible version numbers for a key from the registry server (not from
   the local key table).  The key is identified via its associated
   authentication protocol, principal name, and key type.  The arg value
   associated with the key is also specified.

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