2.1.  Credential management calls

   These GSS-API calls provide functions related to the management of
   credentials. Their characterization with regard to whether or not
   they may block pending exchanges with other network entities (e.g.,
   directories or authentication servers) depends in part on OS-specific
   (extra-GSS-API) issues, so is not specified in this document.

   The GSS_Acquire_cred()  call is defined within the GSS-API in support
   of application portability, with a particular orientation towards
   support of portable server applications. It is recognized that (for
   certain systems and mechanisms) credentials for interactive users may
   be managed differently from credentials for server processes; in such
   environments, it is the GSS-API implementation's responsibility to
   distinguish these cases and the procedures for making this
   distinction are a local matter. The GSS_Release_cred()  call provides
   a means for callers to indicate to the GSS-API that use of a
   credentials structure is no longer required. The GSS_Inquire_cred()
   call allows callers to determine information about a credentials
   structure.

2.1.1.  GSS_Acquire_cred call

   Inputs:

   o  desired_name INTERNAL NAME, -NULL requests locally-determined
      default

   o  lifetime_req INTEGER,-in seconds; 0 requests default

   o  desired_mechs SET OF OBJECT IDENTIFIER,-empty set requests
      system-selected default

   o  cred_usage INTEGER-0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
      2=ACCEPT-ONLY

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  output_cred_handle OCTET STRING,

   o  actual_mechs SET OF OBJECT IDENTIFIER,

   o  lifetime_rec INTEGER -in seconds, or reserved value for
      INDEFINITE




 
RFC 1508               Generic Security Interface         September 1993


   Return major_status codes:

   o  GSS_COMPLETE indicates that requested credentials were
      successfully established, for the duration indicated in
      lifetime_rec, suitable for the usage requested in cred_usage, for
      the set of mech_types indicated in actual_mechs, and that those
      credentials can be referenced for subsequent use with the handle
      returned in output_cred_handle.

   o  GSS_BAD_MECH indicates that a mech_type unsupported by the GSS-API
      implementation type was requested, causing the credential
      establishment operation to fail.

   o  GSS_BAD_NAMETYPE indicates that the provided desired_name is
      uninterpretable or of a type unsupported by the supporting GSS-API
      implementation, so no credentials could be established for the
      accompanying desired_name.

   o  GSS_BAD_NAME indicates that the provided desired_name is
      inconsistent in terms of internally-incorporated type specifier
      information, so no credentials could be established for the
      accompanying desired_name.

   o  GSS_FAILURE indicates that credential establishment failed for
      reasons unspecified at the GSS-API level, including lack of
      authorization to establish and use credentials associated with the
      identity named in the input desired_name argument.

   GSS_Acquire_cred()  is used to acquire credentials so that a
   principal can (as a function of the input cred_usage parameter)
   initiate and/or accept security contexts under the identity
   represented by the desired_name input argument. On successful
   completion, the returned output_cred_handle result provides a handle
   for subsequent references to the acquired credentials.  Typically,
   single-user client processes using only default credentials for
   context establishment purposes will have no need to invoke this call.

   A caller may provide the value NULL for desired_name, signifying a
   request for credentials corresponding to a default principal
   identity.  The procedures used by GSS-API implementations to select
   the appropriate principal identity in response to this form of
   request are local matters. It is possible that multiple pre-