Previous: Name Manipulation, Up: Standard GSS API
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.
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.
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.
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.
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.
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.
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.
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.