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 (see text)

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

The GSS major status code GSS_S_FAILURE is used to indicate that the underlying mechanism detected an error for which no specific GSS–API status code is defined. The mechanism-specific status code (minor-status code) will provide more details about the error.

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.

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:

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.