GSS-API Status Codes

Major status codes are encoded in the OM_uint32 as shown in the following figure.

Figure B-1 Major-Status Encoding

If a GSS-API routine returns a GSS status code whose upper 16 bits contain a nonzero value, the call has failed. If the calling error field is nonzero, the application's call of the routine was erroneous. The calling errors are listed in Table B-1. If the routine error field is nonzero, the routine failed because of a routine-specific error, as listed in Table B-2. The bits in the supplementary information field of the status code can be set whether the upper 16 bits indicate a failure or a success. The meaning of individual bits is listed in Table B-3.

GSS-API Major Status Code Values

The following tables list the calling errors that are returned by GSS-API. These errors are specific to a particular language-binding, which is C in this case.

Table B-1 GSS-API Calling Errors

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

Table B-2 GSS-API Routine Errors

The name GSS_S_COMPLETE, which is a zero value, indicates 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-3 GSS-API Supplementary Information Codes

For more on status codes, see GSS-API Status Codes.

Displaying Status Codes

The function gss_display_status() translates GSS-API status codes into text format. This format allows the codes to be displayed to a user or put in a text log. gss_display_status() only displays one status code at a time, and some functions can return multiple status conditions. Accordingly, gss_display_status() should be called as part of a loop. When gss_display_status() indicates a non-zero status code, 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(), take a GSS status code. These macros remove all information except for the relevant field. For example, the GSS_ROUTINE_ERROR() can be applied to a status code to remove the calling errors and supplementary information fields. This operation leaves the routine errors field only. The values delivered by these macros can be directly compared with a GSS_S_xxx symbol of the appropriate type. The macro GSS_ERROR() returns a non-zero value if a status code indicates a calling or routine error, and a zero value otherwise. All macros that are defined by GSS-API evaluate the arguments exactly once.