rfc1509.txt

著名的RFC文档,其中有一些文档是已经翻译成中文的的.

   returned to the application by the GSSAPI may be deallocated by the
   gss_release_oid_set routine.

2.1.6. Credentials

   A credential handle is a caller-opaque atomic datum that identifies a
   GSSAPI credential data structure.  It is represented by the caller-
   opaque type gss_cred_id_t, which may be implemented as either an
   arithmetic or a pointer type.  Credentials describe a principal, and
   they give their holder the ability to act as that principal.  The
   GSSAPI does not make the actual credentials available to
   applications; instead the credential handle is used to identify a
   particular credential, held internally by GSSAPI or underlying



Wray                                                            [Page 6]

RFC 1509            GSSAPI - Overview and C bindings      September 1993


   mechanism.  Thus the credential handle contains no security-relavent
   information, and requires no special protection by the application.
   Depending on the implementation, a given credential handle may refer
   to different credentials when presented to the GSSAPI by different
   callers.  Individual GSSAPI implementations should define both the
   scope of a credential handle and the scope of a credential itself
   (which must be at least as wide as that of a handle).  Possibilities
   for credential handle scope include the process that acquired the
   handle, the acquiring process and its children, or all processes
   sharing some local identification information (e.g., UID).  If no
   handles exist by which a given credential may be reached, the GSSAPI
   may delete the credential.

   Certain routines allow credential handle parameters to be omitted to
   indicate the use of a default credential.  The mechanism by which a
   default credential is established and its scope should be defined by
   the individual GSSAPI implementation.

2.1.7. Contexts

   The gss_ctx_id_t data type contains a caller-opaque atomic value that
   identifies one end of a GSSAPI security context.  It may be
   implemented as either an arithmetic or a pointer type. Depending on
   the implementation, a given gss_ctx_id_t value may refer to different
   GSSAPI security contexts when presented to the GSSAPI by different
   callers.  The security context holds state information about each end
   of a peer communication, including cryptographic state information.
   Individual GSSAPI implementations should define the scope of a
   context.  Since no way is provided by which a new gss_ctx_id_t value
   may be obtained for an existing context, the scope of a context
   should be the same as the scope of a gss_ctx_id_t.

2.1.8. Authentication tokens

   A token is a caller-opaque type that GSSAPI uses to maintain
   synchronization between the context data structures at each end of a
   GSSAPI security context.  The token is a cryptographically protected
   bit-string, generated by the underlying mechanism at one end of a
   GSSAPI security context for use by the peer mechanism at the other
   end.  Encapsulation (if required) and transfer of the token are the
   responsibility of the peer applications.  A token is passed between
   the GSSAPI and the application using the gss_buffer_t conventions.

2.1.9. Status values

   One or more status codes are returned by each GSSAPI routine.  Two
   distinct sorts of status codes are returned.  These are termed GSS
   status codes and Mechanism status codes.



Wray                                                            [Page 7]

RFC 1509            GSSAPI - Overview and C bindings      September 1993


2.1.9.1. GSS status codes

   GSSAPI routines return GSS status codes as their OM_uint32 function
   value.  These codes indicate errors that are independent of the
   underlying mechanism 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 GSSAPI
   specification) or calling errors (errors that are specific to these
   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 GSSAPI 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 5-1  Calling Errors

              Name                    Value in        Meaning
                                        Field
         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                                                            [Page 8]

RFC 1509            GSSAPI - Overview and C bindings      September 1993


                     Table 5-2  Routine Errors

               Name             Value in       Meaning
                                 Field

         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_SIG              6      A token had an invalid
                                           signature
         GSS_S_NO_CRED              7      No credentials were supplied
         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)

                     Table 5-3  Supplementary Status Bits

         Name                Bit Number         Meaning
         GSS_S_CONTINUE_NEEDED   0 (LSB)  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

   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.





Wray                                                            [Page 9]

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.



Wray                                                           [Page 10]

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.

2.1.11. Channel Bindings

   GSSAPI supports the use of user-specified tags to identify a given
   context to the peer application.  These tags are used to identify the
   particular communications channel that carries the context.  Channel
   bindings are communicated to the GSSAPI using the following
   structure:










Wray                                                           [Page 11]

RFC 1509            GSSAPI - Overview and C bindings      September 1993


                 typedef struct gss_channel_bindings_struct {
                    OM_uint32       initiator_addrtype;
                    gss_buffer_desc initiator_address;
                    OM_uint32       acceptor_addrtype;
                    gss_buffer_desc acceptor_address;
                    gss_buffer_desc application_data;
                 } *gss_channel_bindings_t;

   The initiator_addrtype and acceptor_addrtype fields denote the type
   of addresses contained in the initiator_address and acceptor_address
   buffers.  The address type should be one of the following:

          GSS_C_AF_UNSPEC      Unspecified address type
          GSS_C_AF_LOCAL       Host-local address type
          GSS_C_AF_INET        DARPA Internet address type
          GSS_C_AF_IMPLINK     ARPAnet IMP address type (eg IP)
          GSS_C_AF_PUP         pup protocols (eg BSP) address type
          GSS_C_AF_CHAOS       MIT CHAOS protocol address type
          GSS_C_AF_NS          XEROX NS address type
          GSS_C_AF_NBS         nbs address type