Appendix B GSS-API Reference

This appendix includes the following sections:

• GSS-API Functions provides a table of GSS-API functions.

• GSS-API Status Codes discusses status codes returned by GSS-API functions, and provides a list of those status codes.

• GSS-API Data Types and Values discusses the various data types used by the GSS-API.

Additional GSS-API definitions can be found in the file gssapi.h.

GSS-API Functions

The following table lists the functions of the GSS-API. For more information on each function, see its man page. See also Functions From Previous Versions of the GSS-API.

Table B–1 GSS-API Functions

Function	Description
gss_acquire_cred()	Assume a global identity; obtain a GSS-API credential handle for pre-existing credentials
gss_add_cred()	Construct credentials incrementally
gss_inquire_cred()	Obtain information about a credential
gss_inquire_cred_by_mech()	Obtain per-mechanism information about a credential
gss_release_cred()	Discard a credential handle
gss_init_sec_context()	Initiate a security context with a peer application
gss_accept_sec_context()	Accept a security context initiated by a peer application
gss_delete_sec_context()	Discard a security context
gss_process_context_token()	Process a token on a security context from a peer application
gss_context_time()	Determine for how long a context will remain valid
gss_inquire_context()	Obtain information about a security context
gss_wrap_size_limit()	Determine token-size limit for gss_wrap() on a context
gss_export_sec_context()	Transfer a security context to another process
gss_import_sec_context()	Import a transferred context
gss_get_mic()	Calculate a cryptographic message integrity code (MIC) for a message; integrity service
gss_verify_mic()	Check a MIC against a message; verify integrity of a received message
gss_wrap()	Attach a MIC to a message, and optionally encrypt the message content
gss_unwrap()	Verify a message with attached MIC, and decrypt message content if necessary
gss_import_name()	Convert a contiguous string name to internal-form
gss_display_name()	Convert internal-form name to text
gss_compare_name()	Compare two internal-form names
gss_release_name()	Discard an internal-form name
gss_inquire_names_for_mech()	List the name types supported by the specified mechanism
gss_inquire_mechs_for_name()	List mechanisms that support the specified name type
gss_canonicalize_name()	Convert an internal name to an MN
gss_export_name()	Convert an MN to export form
gss_duplicate_name()	Create a copy of an internal name
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()	Determine whether an object identifier is a member of a set

Functions From Previous Versions of the GSS-API

This section explains functions that were included in previous versions of the GSS-API.

Functions for Manipulating OIDs

The following functions are supported by the Sun implementation of the GSS-API for convenience and for backward compatibility with programs written for older versions of the GSS-API. However, they should not be relied upon, as they might not be supported by other implementations of the GSS-API.

• gss_delete_oid()

• gss_oid_to_str()

• gss_str_to_oid()

Although these functions make it possible to convert a mechanism's name from a string to an OID, programmers should use the default GSS-API mechanism, instead of specifying one, if at all possible.

Renamed Functions

The following functions have been supplanted by newer functions. In each case, the new function is the functional equivalent of the old one. Although the old functions are supported, developers should replace them with the newer functions whenever possible.

• gss_sign() has been replaced with gss_get_mic().

• gss_verify() has been replaced with gss_verify_mic().

• gss_seal() has been replaced with gss_wrap().

• gss_unseal() has been replaced with gss_unwrap().

GSS-API Status Codes

Major status codes are encoded in the OM_uint32 as shown in Figure B–1.

Figure B–1 Major-Status Encoding

If a GSS-API routine returns a GSS status code whose upper 16 bits contain a non-zero value, the call has failed. If the calling error field is non-zero, the invoking application's call of the routine was erroneous. Calling errors are listed in Table B–2. If the routine error field is non-zero, the routine failed because of a routine-specific error, as listed below in Table B–3. Whether or not the upper 16 bits indicate a failure or a success, the routine might indicate additional information by setting bits in the supplementary information field of the status code. The meaning of individual bits is listed in Table B–4.

GSS-API Major Status Code Values

The following tables lists calling errors returned by the GSS-API; that is, errors that are specific to a particular language-binding (C, in this case).

Table B–2 Calling Errors

Error	Value in Field	Meaning
GSS_S_CALL_INACCESSIBLE_READ	1	A required input parameter could not be read
GSS_S_CALL_INACCESSIBLE_WRITE	2	A required output parameter could not be written
GSS_S_CALL_BAD_STRUCTURE	3	A parameter was malformed

The following table lists the routine errors (that is, generic errors returned by GSS-API functions).

Table B–3 Routine Errors

Error	Value in Field	Meaning
GSS_S_BAD_MECH	1	An unsupported mechanism was requested
GSS_S_BAD_NAME	2	An invalid name was supplied
GSS_S_BAD_NAMETYPE	3	A supplied name was of an unsupported type
GSS_S_BAD_BINDINGS	4	Incorrect channel bindings were supplied
GSS_S_BAD_STATUS	5	An invalid status code was supplied
GSS_S_BAD_MIC, GSS_S_BAD_SIG	6	A token had an invalid MIC
GSS_S_NO_CRED	7	No credentials were supplied, or the credentials were unavailable or inaccessible
GSS_S_NO_CONTEXT	8	No context has been established
GSS_S_DEFECTIVE_TOKEN	9	A token was invalid
GSS_S_DEFECTIVE_CREDENTIAL	10	A credential was invalid
GSS_S_CREDENTIALS_EXPIRED	11	The referenced credentials have expired
GSS_S_CONTEXT_EXPIRED	12	The context has expired
GSS_S_FAILURE	13	Miscellaneous failure. The underlying mechanism detected an error for which no specific GSS–API status code is defined. The mechanism-specific status code (minor-status code) provides more details about the error.
GSS_S_BAD_QOP	14	The quality-of-protection requested could not be provided
GSS_S_UNAUTHORIZED	15	The operation is forbidden by local security policy
GSS_S_UNAVAILABLE	16	The operation or option is unavailable
GSS_S_DUPLICATE_ELEMENT	17	The requested credential element already exists
GSS_S_NAME_NOT_MN	18	The provided name was not a Mechanism Name (MN)

The routine documentation also uses the name GSS_S_COMPLETE, which is a zero value, to indicate an absence of any API errors or supplementary information bits.

The following table lists the supplementary information values returned by GSS-API functions.

Table B–4 Supplementary Information Codes

Code	Bit Number	Meaning
GSS_S_CONTINUE_NEEDED	0 (LSB)	Returned only by gss_init_sec_context() or gss_accept_sec_context(). The routine must be called again to complete its function
GSS_S_DUPLICATE_TOKEN	1	The token was a duplicate of an earlier token
GSS_S_OLD_TOKEN	2	The token's validity period has expired
GSS_S_UNSEQ_TOKEN	3	A later token has already been processed
GSS_S_GAP_TOKEN	4	An expected per-message token was not received

For more on status codes, see Status Codes.

Displaying Status Codes

The function gss_display_status() translates GSS-API status codes into text format, allowing them to be displayed to a user or put in a text log. Because gss_display_status() only displays one status code at a time, and some functions can return multiple status conditions, it should be invoked as part of a loop. As long as gss_display_status() indicates a non-zero status code (in Example B–1, the value returned in the message_context parameter), another status code is available for the function to fetch.

---

Example B–1 Displaying Status Codes with gss_display_status()

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);

---

Status Code Macros

The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS status code and removes all but the relevant field. For example, the value obtained by applying GSS_ROUTINE_ERROR() to a status code removes the calling errors and supplementary information fields, leaving only the routine errors field. The values delivered by these macros can be directly compared with a GSS_S_xxx symbol of the appropriate type. The macro GSS_ERROR() is also provided, which when applied to a GSS–API status code returns a non-zero value if the status code indicated a calling or routine error, and a zero value otherwise. All macros defined by the GSS-API evaluate their argument(s) exactly once.

GSS-API Data Types and Values

This section covers various types of GSS-API data types and values. Certain data types that are opaque to the user, such as gss_cred_id_t or gss_name_t, are not covered here, since there is no advantage to knowing their structure. This section explains the following:

• Basic GSS-API Data Types — Shows the definitions of the OM_uint32, gss_buffer_desc, gss_OID_desc, gss_OID_set_desc_struct, and gss_channel_bindings_struct data types.

• Name Types — Shows the various name formats recognized by the GSS-API for specifying names.

• Address Types for Channel Bindings — Shows the various values that may be used as the initiator_addrtype and acceptor_addrtype fields of the gss_channel_bindings_t structure.

Basic GSS-API Data Types

These are some of the data types used by the GSS-API.

OM_uint32

The OM_uint32 is a platform-independent 32–bit unsigned integer.

gss_buffer_desc

This is the definition of the gss_buffer_desc and the gss_buffer_t pointer:

typedef struct gss_buffer_desc_struct {
        size_t length;
        void *value;
} gss_buffer_desc, *gss_buffer_t;

gss_OID_desc

This is the definition of the gss_OID_desc and the gss_OID pointer:

typedef struct gss_OID_desc_struct {
        OM_uint32 length;
        void*elements;
} gss_OID_desc, *gss_OID;

gss_OID_set_desc

This is the definition of the gss_OID_set_desc and the gss_OID_set pointer:

typedef struct gss_OID_set_desc_struct  {
        size_t  count;
        gss_OID elements;
} gss_OID_set_desc, *gss_OID_set;

gss_channel_bindings_struct

This is the definition of the gss_channel_bindings_struct structure and the gss_channel_bindings_t pointer:

typedef struct gss_channel_bindings_struct {
        OM_uint32 initiator_addrtype;
        gss_buffer_desc initiator_address;
        OM_uint32 acceptor_addrtype;
        gss_buffer_desc acceptor_address;
        gss_buffer_desc application_data;
} *gss_channel_bindings_t;

Name Types

A name type indicates the format of the name with which it is associated. (See Names and OIDs for more on names and name types.) The GSS-API supports the following name types, which are all gss_OID types:

Table B–5 Name Types

Name Type	Meaning
GSS_C_NO_NAME	The recommended symbolic name GSS_C_NO_NAME indicates that no name is being passed within a particular value of a parameter used for the purpose of transferring names.
GSS_C_NO_OID	This value corresponds to a null input value instead of an actual object identifier. Where specified, it indicates interpretation of an associated name based on a mechanism-specific default printable syntax.
GSS_C_NT_ANONYMOUS	Provided as a means to identify anonymous names, and can be compared against in order to determine, in a mechanism-independent fashion, whether a name refers to an anonymous principal.
GSS_C_NT_EXPORT_NAME	A name that has been exported with the gss_export_name() function.
GSS_C_NT_HOSTBASED_SERVICE	This name type is used to represent services associated with host computers. This name form is constructed using two elements, "service" and "hostname,” as follows: service@hostname.
GSS_C_NT_MACHINE_UID_NAME	This name type is used to indicate a numeric user identifier corresponding to a user on a local system. Its interpretation is OS-specific. The gss_import_name() function resolves this UID into a username, which is then treated as the User Name Form.
GSS_C_NT_STRING_STRING_UID_NAME	This name type is used to indicate a string of digits representing the numeric user identifier of a user on a local system. Its interpretation is OS-specific. This name type is similar to the Machine UID Form, except that the buffer contains a string representing the user ID.
GSS_C_NT_USER_NAME	A named user on a local system. Its interpretation is OS-specific. It takes the form: username.

Address Types for Channel Bindings

Table B–6 shows the possible values for the initiator_addrtype and acceptor_addrtype fields of the gss_channel_bindings_struct structure. These fields indicate the format that a name can take (for example, ARPAnet IMP address format or AppleTalk address format). Channel bindings are discussed in Channel Bindings.

Table B–6 Channel Binding Address Types

Field	Value (Decimal)	Address Type
GSS_C_AF_UNSPEC	0	Unspecified address type
GSS_C_AF_LOCAL	1	Host-local
GSS_C_AF_INET	2	Internet address type (example: IP)
GSS_C_AF_IMPLINK	3	ARPAnet IMP
GSS_C_AF_PUP	4	pup protocols (example: BSP)
GSS_C_AF_CHAOS	5	MIT CHAOS protocol
GSS_C_AF_NS	6	XEROX NS
GSS_C_AF_NBS	7	nbs
GSS_C_AF_ECMA	8	ECMA
GSS_C_AF_DATAKIT	9	datakit protocols
GSS_C_AF_CCITT	10	CCITT
GSS_C_AF_SNA	11	IBM SNA
GSS_C_AF_DECnet	12	DECnet
GSS_C_AF_DLI	13	Direct data link interface
GSS_C_AF_LAT	14	LAT
GSS_C_AF_HYLINK	15	NSC Hyperchannel
GSS_C_AF_APPLETALK	16	AppleTalk
GSS_C_AF_BSC	17	BISYNC
GSS_C_AF_DSS	18	Distributed system services
GSS_C_AF_OSI	19	OSI TP4
GSS_C_AF_X25	21	X.25
GSS_C_AF_NULLADDR	255	No address specified