RFC 1509            GSSAPI - Overview and C bindings      September 1993


   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.

   A GSSAPI 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
   routine status values only.

2.1.9.2. Mechanism-specific status codes

   GSSAPI 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 GSSAPI routine,
   even if it returns a calling error or one of the generic API errors
   indicated above as fatal, although 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 set set
   by the routine, even in the event of an error, although in such cases
   the GSSAPI 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.

   The GSS 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 status code will provide more
   details about the error.

2.1.10. Names

   A name is used to identify a person or entity.  GSSAPI authenticates
   the relationship between a name and the entity claiming the name.




 
RFC 1509            GSSAPI - Overview and C bindings      September 1993


   Two distinct representations are defined for names:

        (a) A printable form, for presentation to a user

        (b) An internal form, for presentation at the API

   The syntax of a printable name is defined by the GSSAPI
   implementation, and may be dependent on local system configuration,
   or on individual user preference.  The internal form provides a
   canonical representation of the name that is independent of
   configuration.

   A given GSSAPI implementation may support names drawn from multiple
   namespaces.  In such an implementation, the internal form of the name
   must include fields that identify the namespace from which the name
   is drawn.  The namespace from which a printable name is drawn is
   specified by an accompanying object identifier.

   Routines (gss_import_name and  gss_display_name) are provided to
   convert names between their printable representations and the
   gss_name_t type.  gss_import_name may support multiple syntaxes for
   each supported namespace, allowing users the freedom to choose a
   preferred name representation.  gss_display_name should use an
   implementation-chosen preferred syntax for each supported name-type.

   Comparison of internal-form names is accomplished via the
   gss_compare_names routine.  This removes the need for the application
   program to understand the syntaxes of the various printable names
   that a given GSSAPI implementation may support.

   Storage is allocated by routines that return gss_name_t values.  A
   procedure, gss_release_name, is provided to free storage associated
   with a name.