Next: , Previous: Name Manipulation, Up: Standard GSS API


3.9 Miscellaneous Routines

   GSS-API Miscellaneous Routines

   Routine                        Function
   -------                        --------
   gss_add_oid_set_member         Add an object identifier to
                                  a set.
   gss_display_status             Convert a GSS-API status code
                                  to text.
   gss_indicate_mechs             Determine available underlying
                                  authentication mechanisms.
   gss_release_buffer             Discard a buffer.
   gss_release_oid_set            Discard a set of object
                                  identifiers.
   gss_create_empty_oid_set       Create a set containing no
                                  object identifiers.
   gss_test_oid_set_member        Determines whether an object
                                  identifier is a member of a set.
   gss_encapsulate_token          Encapsulate a context token.
   gss_decapsulate_token          Decapsulate a context token.
   gss_oid_equal                  Compare two OIDs for equality.

gss_add_oid_set_member

— Function: OM_uint32 gss_add_oid_set_member (OM_uint32 * minor_status, const gss_OID member_oid, gss_OID_set * oid_set)

minor_status: (integer, modify) Mechanism specific status code.

member_oid: (Object ID, read) The object identifier to copied into the set.

oid_set: (Set of Object ID, modify) The set in which the object identifier should be inserted.

Add an Object Identifier to an Object Identifier set. This routine is intended for use in conjunction with gss_create_empty_oid_set when constructing a set of mechanism OIDs for input to gss_acquire_cred. The oid_set parameter must refer to an OID-set that was created by GSS-API (e.g. a set returned by gss_create_empty_oid_set()). GSS-API creates a copy of the member_oid and inserts this copy into the set, expanding the storage allocated to the OID-set's elements array if necessary. The routine may add the new member OID anywhere within the elements array, and implementations should verify that the new member_oid is not already contained within the elements array; if the member_oid is already present, the oid_set should remain unchanged.

Return value:

GSS_S_COMPLETE: Successful completion.

gss_display_status

— Function: OM_uint32 gss_display_status (OM_uint32 * minor_status, OM_uint32 status_value, int status_type, const gss_OID mech_type, OM_uint32 * message_context, gss_buffer_t status_string)

minor_status: (integer, modify) Mechanism specific status code.

status_value: (Integer, read) Status value to be converted.

status_type: (Integer, read) GSS_C_GSS_CODE - status_value is a GSS status code. GSS_C_MECH_CODE - status_value is a mechanism status code.

mech_type: (Object ID, read, optional) Underlying mechanism (used to interpret a minor status value). Supply GSS_C_NO_OID to obtain the system default.

message_context: (Integer, read/modify) Should be initialized to zero by the application prior to the first call. On return from gss_display_status(), a non-zero status_value parameter indicates that additional messages may be extracted from the status code via subsequent calls to gss_display_status(), passing the same status_value, status_type, mech_type, and message_context parameters.

status_string: (buffer, character string, modify) Textual interpretation of the status_value. Storage associated with this parameter must be freed by the application after use with a call to gss_release_buffer().

Allows an application to obtain a textual representation of a GSS-API status code, for display to the user or for logging purposes. Since some status values may indicate multiple conditions, applications may need to call gss_display_status multiple times, each call generating a single text string. The message_context parameter is used by gss_display_status to store state information about which error messages have already been extracted from a given status_value; message_context must be initialized to 0 by the application prior to the first call, and gss_display_status will return a non-zero value in this parameter if there are further messages to extract.

The message_context parameter contains all state information required by gss_display_status in order to extract further messages from the status_value; even when a non-zero value is returned in this parameter, the application is not required to call gss_display_status again unless subsequent messages are desired. The following code extracts all messages from a given status code and prints them to stderr:

          OM_uint32 message_context;
          OM_uint32 status_code;
          OM_uint32 maj_status;
          OM_uint32 min_status;
          gss_buffer_desc status_string;
          
                 ...
          
          message_context = 0;
          
          do {
            maj_status = gss_display_status (
                            &min_status,
                            status_code,
                            GSS_C_GSS_CODE,
                            GSS_C_NO_OID,
                            &message_context,
                            &status_string)
          
            fprintf(stderr,
                    "%.*s\n",
                   (int)status_string.length,
          
                   (char *)status_string.value);
          
            gss_release_buffer(&min_status, &status_string);
          
          } while (message_context != 0);

Return value:

GSS_S_COMPLETE: Successful completion.

GSS_S_BAD_MECH: Indicates that translation in accordance with an unsupported mechanism type was requested.

GSS_S_BAD_STATUS: The status value was not recognized, or the status type was neither GSS_C_GSS_CODE nor GSS_C_MECH_CODE.

gss_indicate_mechs

— Function: OM_uint32 gss_indicate_mechs (OM_uint32 * minor_status, gss_OID_set * mech_set)

minor_status: (integer, modify) Mechanism specific status code.

mech_set: (set of Object IDs, modify) Set of implementation-supported mechanisms. The returned gss_OID_set value will be a dynamically-allocated OID set, that should be released by the caller after use with a call to gss_release_oid_set().

Allows an application to determine which underlying security mechanisms are available.

Return value:

GSS_S_COMPLETE: Successful completion.

gss_release_buffer

— Function: OM_uint32 gss_release_buffer (OM_uint32 * minor_status, gss_buffer_t buffer)

minor_status: (integer, modify) Mechanism specific status code.

buffer: (buffer, modify) The storage associated with the buffer will be deleted. The gss_buffer_desc object will not be freed, but its length field will be zeroed.

Free storage associated with a buffer. The storage must have been allocated by a GSS-API routine. In addition to freeing the associated storage, the routine will zero the length field in the descriptor to which the buffer parameter refers, and implementations are encouraged to additionally set the pointer field in the descriptor to NULL. Any buffer object returned by a GSS-API routine may be passed to gss_release_buffer (even if there is no storage associated with the buffer).

Return value:

GSS_S_COMPLETE: Successful completion.

gss_release_oid_set

— Function: OM_uint32 gss_release_oid_set (OM_uint32 * minor_status, gss_OID_set * set)

minor_status: (integer, modify) Mechanism specific status code.

set: (Set of Object IDs, modify) The storage associated with the gss_OID_set will be deleted.

Free storage associated with a GSSAPI-generated gss_OID_set object. The set parameter must refer to an OID-set that was returned from a GSS-API routine. gss_release_oid_set() will free the storage associated with each individual member OID, the OID set's elements array, and the gss_OID_set_desc.

The gss_OID_set parameter is set to GSS_C_NO_OID_SET on successful completion of this routine.

Return value:

GSS_S_COMPLETE: Successful completion.

gss_create_empty_oid_set

— Function: OM_uint32 gss_create_empty_oid_set (OM_uint32 * minor_status, gss_OID_set * oid_set)

minor_status: (integer, modify) Mechanism specific status code.

oid_set: (Set of Object IDs, modify) The empty object identifier set. The routine will allocate the gss_OID_set_desc object, which the application must free after use with a call to gss_release_oid_set().

Create an object-identifier set containing no object identifiers, to which members may be subsequently added using the gss_add_oid_set_member() routine. These routines are intended to be used to construct sets of mechanism object identifiers, for input to gss_acquire_cred.

Return value:

GSS_S_COMPLETE: Successful completion.

gss_test_oid_set_member

— Function: OM_uint32 gss_test_oid_set_member (OM_uint32 * minor_status, const gss_OID member, const gss_OID_set set, int * present)

minor_status: (integer, modify) Mechanism specific status code.

member: (Object ID, read) The object identifier whose presence is to be tested.

set: (Set of Object ID, read) The Object Identifier set.

present: (Boolean, modify) Non-zero if the specified OID is a member of the set, zero if not.

Interrogate an Object Identifier set to determine whether a specified Object Identifier is a member. This routine is intended to be used with OID sets returned by gss_indicate_mechs(), gss_acquire_cred(), and gss_inquire_cred(), but will also work with user-generated sets.

Return value:

GSS_S_COMPLETE: Successful completion.

gss_encapsulate_token

— Function: extern OM_uint32 gss_encapsulate_token (gss_const_buffer_t input_token, gss_const_OID token_oid, gss_buffer_t output_token)

input_token: (buffer, opaque, read) Buffer with GSS-API context token data.

token_oid: (Object ID, read) Object identifier of token.

output_token: (buffer, opaque, modify) Encapsulated token data; caller must release with gss_release_buffer().

Add the mechanism-independent token header to GSS-API context token data. This is used for the initial token of a GSS-API context establishment sequence. It incorporates an identifier of the mechanism type to be used on that context, and enables tokens to be interpreted unambiguously at GSS-API peers. See further section 3.1 of RFC 2743. This function is standardized in RFC 6339.

Returns:

GSS_S_COMPLETE: Indicates successful completion, and that output parameters holds correct information.

GSS_S_FAILURE: Indicates that encapsulation failed for reasons unspecified at the GSS-API level.

gss_decapsulate_token

— Function: OM_uint32 gss_decapsulate_token (gss_const_buffer_t input_token, gss_const_OID token_oid, gss_buffer_t output_token)

input_token: (buffer, opaque, read) Buffer with GSS-API context token.

token_oid: (Object ID, read) Expected object identifier of token.

output_token: (buffer, opaque, modify) Decapsulated token data; caller must release with gss_release_buffer().

Remove the mechanism-independent token header from an initial GSS-API context token. Unwrap a buffer in the mechanism-independent token format. This is the reverse of gss_encapsulate_token(). The translation is loss-less, all data is preserved as is. This function is standardized in RFC 6339.

Return value:

GSS_S_COMPLETE: Indicates successful completion, and that output parameters holds correct information.

GSS_S_DEFECTIVE_TOKEN: Means that the token failed consistency checks (e.g., OID mismatch or ASN.1 DER length errors).

GSS_S_FAILURE: Indicates that decapsulation failed for reasons unspecified at the GSS-API level.

gss_oid_equal

— Function: int gss_oid_equal (gss_const_OID first_oid, gss_const_OID second_oid)

first_oid: (Object ID, read) First Object identifier.

second_oid: (Object ID, read) First Object identifier.

Compare two OIDs for equality. The comparison is "deep", i.e., the actual byte sequences of the OIDs are compared instead of just the pointer equality. This function is standardized in RFC 6339.

Return value: Returns boolean value true when the two OIDs are equal, otherwise false.