rfc2744.txt

RFC 的详细文档！

   specific manner.  Note that, while GSS-API implementors are
   encouraged to avoid placing sensitive information within interprocess
   tokens, or to cryptographically protect them, many implementations
   will be unable to avoid placing key material or other sensitive data
   within them.  It is the application's responsibility to ensure that
   interprocess tokens are protected in transit, and transferred only to
   processes that are trustworthy. An interprocess token is passed
   between the GSS-API and the application using the gss_buffer_t
   conventions.

3.9. Status values

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

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



Wray                        Standards Track                    [Page 11]

RFC 2744                 GSS-API V2: C-bindings             January 2000


   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 5-1.  If the routine
   error field is non-zero, the routine failed for one of the routine-
   specific reasons listed below in table 5-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 5-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























Wray                        Standards Track                    [Page 12]

RFC 2744                 GSS-API V2: C-bindings             January 2000


   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











Wray                        Standards Track                    [Page 13]

RFC 2744                 GSS-API V2: C-bindings             January 2000


   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.



Wray                        Standards Track                    [Page 14]

RFC 2744                 GSS-API V2: C-bindings             January 2000


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

3.10. Names

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

   Since different authentication mechanisms may employ different
   namespaces for identifying their principals, GSSAPI's naming support
   is necessarily complex in multi-mechanism environments (or even in
   some single-mechanism environments where the underlying mechanism
   supports multiple namespaces).

   Two distinct representations are defined for names:

   An internal form.  This is the GSS-API "native" format for names,
      represented by the implementation-specific gss_name_t type.  It is
      opaque to GSS-API callers.  A single gss_name_t object may contain
      multiple names from different namespaces, but all names should
      refer to the same entity.  An example of such an internal name
      would be the name returned from a call to the gss_inquire_cred
      routine, when applied to a credential containing credential
      elements for multiple authentication mechanisms employing
      different namespaces.  This gss_name_t object will contain a
      distinct name for the entity for each authentication mechanism.

      For GSS-API implementations supporting multiple namespaces,
      objects of type gss_name_t must contain sufficient information to
      determine the namespace to which each primitive name belongs.






Wray                        Standards Track                    [Page 15]

RFC 2744                 GSS-API V2: C-bindings             January 2000


   Mechanism-specific contiguous octet-string forms.  A format
      capable of containing a single name (from a single namespace).
      Contiguous string names are always accompanied by an object
      identifier specifying the namespace to which the name belongs, and
      their format is dependent on the authentication mechanism that
      employs the name.  Many, but not all, contiguous string names will
      be printable, and may therefore be used by GSS-API applications
      for communication with their users.

   Routines (gss_import_name and gss_display_name) are provided to
   convert names between contiguous string representations and the
   internal 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 printable syntax for each supported name-
   type.

   If an application calls gss_display_name(), passing the internal name
   resulting from a call to gss_import_name(), there is no guarantee the
   the resulting contiguous string name will be the same as the original
   imported string name.  Nor do name-space identifiers necessarily
   survive unchanged after a journey through the internal name-form.  An
   example of this might be a mechanism that authenticates X.500 names,
   but provides an algorithmic mapping of Internet DNS names into X.500.
   That mechanism's implementation of gss_import_name() might, when
   presented with a DNS name, generate an internal name that contained
   both the original DNS name and the equivalent X.500 name.
   Alternatively, it might only store the X.500 name.  In the latter
   case, gss_display_name() would most likely generate a printable X.500
   name, rather than the original DNS name.