### 3.4 Error Handling ¶

Every GSS-API routine returns two distinct values to report status information to the caller: GSS status codes and Mechanism status codes.

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