GSS-API Programming Guide

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 `OID`s

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

Diagram shows how major status codes are encoded in OM_uint32.

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