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.
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 |
This section explains functions that were included in previous versions of the GSS-API.
OID
sThe 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.
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.
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.
Major status codes are encoded in the OM_uint32 as shown in Figure B–1.
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.
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.
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.
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);
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.
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.
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.
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;
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;
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;
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;
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. |
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 |