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 (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.
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.