3.4.1 GSS status codes

GSS-API routines return GSS status codes as their OM_uint32 function value. These codes indicate errors that are independent of the underlying mechanism(s) used to provide the security service. The errors that can be indicated via a GSS status code are either generic API routine errors (errors that are defined in the GSS-API specification) or calling errors (errors that are specific to these language bindings).

A GSS status code can indicate a single fatal generic API error from the routine and a single calling error. In addition, supplementary status information may be indicated via the setting of bits in the supplementary info field of a GSS status code.

These errors are encoded into the 32-bit GSS status code as follows:

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

Hence if a GSS-API routine returns a GSS status code whose upper 16 bits contain a non-zero value, the call failed. If the calling error field is non-zero, the invoking application’s call of the routine was erroneous. Calling errors are defined in table 3-1. If the routine error field is non-zero, the routine failed for one of the routine- specific reasons listed below in table 3-2. Whether or not the upper 16 bits indicate a failure or a success, the routine may indicate additional information by setting bits in the supplementary info field of the status code. The meaning of individual bits is listed below in table 3-3.

   Table 3-1  Calling Errors

   Name                   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

   Table 3-2  Routine Errors

   Name                   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

   Table 3-3  Supplementary Status Bits

   Name                   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.
                                     See routine documentation for
                                     detailed description
   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 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.

All GSS_S_xxx symbols equate to complete OM_uint32 status codes, rather than to bitfield values. For example, the actual value of the symbol GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3<<16. 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 info fields, leaving only the routine errors field. The values delivered by these macros may 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 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 GSS-API evaluate their argument(s) exactly once.

A GSS-API implementation may choose to signal calling errors in a platform-specific manner instead of, or in addition to the routine value; routine errors and supplementary info should be returned via major status values only.

The GSS major status code GSS_S_FAILURE is used to indicate that the underlying mechanism detected an error for which no specific GSS status code is defined. The mechanism-specific status code will provide more details about the error.

In addition to the explicit major status codes for each API function, the code GSS_S_FAILURE may be returned by any routine, indicating an implementation-specific or mechanism-specific error condition, further details of which are reported via the minor_status parameter.

3.4.2 Mechanism-specific status codes

GSS-API routines return a minor_status parameter, which is used to indicate specialized errors from the underlying security mechanism. This parameter may contain a single mechanism-specific error, indicated by a OM_uint32 value.

The minor_status parameter will always be set by a GSS-API routine, even if it returns a calling error or one of the generic API errors indicated above as fatal, although most other output parameters may remain unset in such cases. However, output parameters that are expected to return pointers to storage allocated by a routine must always be set by the routine, even in the event of an error, although in such cases the GSS-API routine may elect to set the returned parameter value to NULL to indicate that no storage was actually allocated. Any length field associated with such pointers (as in a gss_buffer_desc structure) should also be set to zero in such cases.