Major status codes are encoded in the OM_uint32 as shown in the following figure.
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.
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
Error |
Value in Field |
Meaning |
---|---|---|
GSS_S_CALL_INACCESSIBLE_READ |
1 |
An input parameter that is required 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 GSS-API routine errors, generic errors that are returned by GSS-API functions.
Table B–2 GSS-API 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 |
The credentials were unavailable, inaccessible, or not supplied. |
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, that is, the minor-status code, provides more details about the error. |
GSS_S_BAD_QOP |
14 |
The quality-of-protection that was 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 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
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 GSS-API 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.
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(), 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.