GSS-API Status Codes

All GSS-API functions return two types of codes that provide information on the function's success or failure. Both types of status codes are returned as OM_uint32 values.

The two types of return codes are as follows:

• Major status codes

  Major status codes indicate the following errors:

  • Generic GSS-API routine errors, such as giving a routine an invalid mechanism

  • Call errors that are specific to a particular GSS-API language binding, such as a function argument that cannot be read, cannot be written, or is malformed

  • Both types of errors

  Additionally, major status codes can provide supplementary information about a routine's status. For example, a code might indicate that an operation is not finished, or that a token has been sent out of order. If no errors occur, the routine returns a major status value of GSS_S_COMPLETE.

  Major status codes are returned as follows:

  OM_uint32 major_status ;    /* status returned by GSS-API */
  
  major_status = gss_generic_function(arg1, arg2 ...);

  Major status return codes can be processed like any other OM_uint32. For example, consider the following code.

  OM_uint32 maj_stat;
  
  maj_sta = gss_generic_function(arg1, arg2 ...);
  
  if (maj_stat == GSS_CREDENTIALS_EXPIRED)
       <do something...>

  Major status codes can be processed with the macros GSS_ROUTINE_ERROR(), GSS_CALLING_ERROR(), and GSS_SUPPLEMENTARY_INFO(). GSS-API Status Codes explains how to read major status codes and contains a list of GSS-API status codes.

• Minor status codes

  Minor status codes are returned by the underlying mechanism. These codes are not specifically documented in this manual.

  Every GSS-API function has as a first argument an OM_uint32 type for the minor code status. The minor status code is stored in the OM_uint32 argument when the function returns to the calling function. Consider the following code.

  OM_uint32 *minor_status ;    /* status returned by mech */
  
  major_status = gss_generic_function(&minor_status, arg1, arg2 ...);

  The minor_status parameter is always set by a GSS-API routine, even if a fatal major status code error is returned. Note that most other output parameters can remain unset. However, output parameters that are expected to return pointers to storage that has been allocated by the routine are set to NULL. NULL indicates that no storage was actually allocated. Any length field associated with such pointers, as in a gss_buffer_desc structure, are set to zero. In such cases, applications do not need to release these buffers.