Major Status Values

A GSS status code can indicate a single, fatal generic API error from the routine and a single calling error. Additional status information can also be contained in the GSS status code. The errors are encoded into a 32-bit GSS status code, as follows:

MSB LSB
+---------------------------------------------------+
| Calling Error | Routine Error | Supplementary Info|
+---------------------------------------------------+
Bit 31 24 23 16 15 0

If a GSSAPI routine returns a GSS status code whose upper 16 bits contain a nonzero value, the call failed. If the calling error field is nonzero, the context initiator's use of the routine was in error. In addition, the routine can indicate additional information by setting bits in the supplementary information field of the status code. The tables that follow describe the routine errors, calling errors, and supplementary information status bits and their meanings.

The following table lists the GSSAPI routine errors and their meanings:

Name	Field Value	Meaning
GSS_S_BAD_MECH	1	The required mechanism is unsupported.
GSS_S_NAME	2	The name passed is invalid.
GSS_S_NAMETYPE	3	The name passed is unsupported.
GSS_S_BAD_BINDINGS	4	The channel bindings are incorrect.
GSS_S_BAD_STATUS	5	A status value was invalid.
GSS_S_BAD_SIG	6	A token had an invalid signature.
GSS_S_NO_CRED	7	No credentials were 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 expired.
GSS_S_CONTEXT_EXPIRED	12	The context expired.
GSS_S_FAILURE	13	The routine failed. Check minor status codes.

The following table lists the calling error values and their meanings:

Name	Field Value	Meaning
GSS_S_CALL_INACCESSIBLE_READ	1	Could not read a required input parameter.
GSS_S_CALL_INACCESSIBLE_WRITE	2	Could not write a required output parameter.
GSS_S_BAD_STRUCTURE	3	A parameter was incorrectly structured.

The following table lists the supplementary bits and their meanings.

Name	Bit Number
GSS_S_CONTINUE_NEEDED	0 (LSB)	Call the routine 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 expired; the routine cannot verify that the token is not a duplicate of an earlier token.
GSS_S_UNSEQ_TOKEN	3	A later token has been processed.

All GSS_S_ symbols equate to complete OM_uint32 status codes, rather than to bitfield values. For example, the actual value of GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3 << 16.

The major status code GSS_S_FAILURE indicates that DCE Security detected an error for which no major status code is available. Check the minor status code for details about the error. See Minor Status Values (below) for more information.

The GSSAPI provides three macros:

· GSS_CALLING_ERROR( )

· GSS_ROUTINE_ERROR( )

· GSS_SUPPLEMENTARY_INFO( )

Each macro takes a GSS status code and masks all but the relevant field. For example, when you use the GSS_ROUTINE_ERROR( ) macro on a status code, it returns a value. The value of the macro is arrived at by using only the routine errors field and zeroing the values of the calling error and the supplementary information fields.

An additional macro, GSS_ERROR( ), lets you determine whether the status code indicated a calling or routine error. If the status code indicated a calling or routine error, the macro returns a nonzero value. If no calling or routine error is indicated, the routine returns a 0 (zero).

Note: At times, a GSSAPI routine that is unable to access data can generate a platform-specific signal, instead of returning a GSS_S_CALL_INACCESSIBLE_READ or GSS_S_CALL_INACCESSIBLE_WRITE status value.