rfc2744.txt

RFC 的详细文档！

   GSS-API uses the following integer data type:

   OM_uint32    32-bit unsigned integer

   Where guaranteed minimum bit-count is important, this portable data
   type is used by the GSS-API routine definitions.  Individual GSS-API
   implementations will include appropriate typedef definitions to map
   this type onto a built-in data type.  If the platform supports the
   X/Open xom.h header file, the OM_uint32 definition contained therein
   should be used; the GSS-API header file in Appendix A contains logic
   that will detect the prior inclusion of xom.h, and will not attempt
   to re-declare OM_uint32.  If the X/Open header file is not available
   on the platform, the GSS-API implementation should use the smallest
   natural unsigned integer type that provides at least 32 bits of
   precision.

3.2. String and similar data

   Many of the GSS-API routines take arguments and return values that
   describe contiguous octet-strings.  All such data is passed between
   the GSS-API and the caller using the gss_buffer_t data type.  This
   data type is a pointer to a buffer descriptor, which consists of a
   length field that contains the total number of bytes in the datum,
   and a value field which contains a pointer to the actual datum:

   typedef struct gss_buffer_desc_struct {
      size_t    length;
      void      *value;
   } gss_buffer_desc, *gss_buffer_t;

   Storage for data returned to the application by a GSS-API routine
   using the gss_buffer_t conventions is allocated by the GSS-API
   routine.  The application may free this storage by invoking the
   gss_release_buffer routine.  Allocation of the gss_buffer_desc object
   is always the responsibility of the application;  unused
   gss_buffer_desc objects may be initialized to the value
   GSS_C_EMPTY_BUFFER.







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


3.2.1. Opaque data types

   Certain multiple-word data items are considered opaque data types at
   the GSS-API, because their internal structure has no significance
   either to the GSS-API or to the caller.  Examples of such opaque data
   types are the input_token parameter to gss_init_sec_context (which is
   opaque to the caller), and the input_message parameter to gss_wrap
   (which is opaque to the GSS-API).  Opaque data is passed between the
   GSS-API and the application using the gss_buffer_t datatype.

3.2.2. Character strings

   Certain multiple-word data items may be regarded as simple ISO
   Latin-1 character strings.  Examples are the printable strings passed
   to gss_import_name via the input_name_buffer parameter. Some GSS-API
   routines also return character strings.  All such character strings
   are passed between the application and the GSS-API implementation
   using the gss_buffer_t datatype, which is a pointer to a
   gss_buffer_desc object.

   When a gss_buffer_desc object describes a printable string, the
   length field of the gss_buffer_desc should only count printable
   characters within the string.  In particular, a trailing NUL
   character should NOT be included in the length count, nor should
   either the GSS-API implementation or the application assume the
   presence of an uncounted trailing NUL.

3.3. Object Identifiers

   Certain GSS-API procedures take parameters of the type gss_OID, or
   Object identifier.  This is a type containing ISO-defined tree-
   structured values, and is used by the GSS-API caller to select an
   underlying security mechanism and to specify namespaces.  A value of
   type gss_OID has the following structure:

   typedef struct gss_OID_desc_struct {
      OM_uint32   length;
      void        *elements;
   } gss_OID_desc, *gss_OID;

   The elements field of this structure points to the first byte of an
   octet string containing the ASN.1 BER encoding of the value portion
   of the normal BER TLV encoding of the gss_OID.  The length field
   contains the number of bytes in this value.  For example, the gss_OID
   value corresponding to {iso(1) identified-organization(3) icd-
   ecma(12) member-company(2) dec(1011) cryptoAlgorithms(7) DASS(5)},
   meaning the DASS X.509 authentication mechanism, has a length field
   of 7 and an elements field pointing to seven octets containing the



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


   following octal values: 53,14,2,207,163,7,5. GSS-API implementations
   should provide constant gss_OID values to allow applications to
   request any supported mechanism, although applications are encouraged
   on portability grounds to accept the default mechanism.  gss_OID
   values should also be provided to allow applications to specify
   particular name types (see section 3.10).  Applications should treat
   gss_OID_desc values returned by GSS-API routines as read-only.  In
   particular, the application should not attempt to deallocate them
   with free().  The gss_OID_desc datatype is equivalent to the X/Open
   OM_object_identifier datatype[XOM].

3.4. Object Identifier Sets

   Certain GSS-API procedures take parameters of the type gss_OID_set.
   This type represents one or more object identifiers (section 2.3).  A
   gss_OID_set object has the following structure:

   typedef struct gss_OID_set_desc_struct {
      size_t    count;
      gss_OID   elements;
   } gss_OID_set_desc, *gss_OID_set;

   The count field contains the number of OIDs within the set.  The
   elements field is a pointer to an array of gss_OID_desc objects, each
   of which describes a single OID.  gss_OID_set values are used to name
   the available mechanisms supported by the GSS-API, to request the use
   of specific mechanisms, and to indicate which mechanisms a given
   credential supports.

   All OID sets returned to the application by GSS-API are dynamic
   objects (the gss_OID_set_desc, the "elements" array of the set, and
   the "elements" array of each member OID are all dynamically
   allocated), and this storage must be deallocated by the application
   using the gss_release_oid_set() routine.

3.5. Credentials

   A credential handle is a caller-opaque atomic datum that identifies a
   GSS-API credential data structure.  It is represented by the caller-
   opaque type gss_cred_id_t, which should be implemented as a pointer
   or arithmetic type.  If a pointer implementation is chosen, care must
   be taken to ensure that two gss_cred_id_t values may be compared with
   the == operator.

   GSS-API credentials can contain mechanism-specific principal
   authentication data for multiple mechanisms.  A GSS-API credential is
   composed of a set of credential-elements, each of which is applicable
   to a single mechanism.  A credential may contain at most one



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


   credential-element for each supported mechanism. A credential-element
   identifies the data needed by a single mechanism to authenticate a
   single principal, and conceptually contains two credential-references
   that describe the actual mechanism-specific authentication data, one
   to be used by GSS-API for initiating contexts,  and one to be used
   for accepting contexts.  For mechanisms that do not distinguish
   between acceptor and initiator credentials, both references would
   point to the same underlying mechanism-specific authentication data.

   Credentials describe a set of mechanism-specific principals, and give
   their holder the ability to act as any of those principals. All
   principal identities asserted by a single GSS-API credential should
   belong to the same entity, although enforcement of this property is
   an implementation-specific matter.  The GSS-API does not make the
   actual credentials available to applications; instead a credential
   handle is used to identify a particular credential, held internally
   by GSS-API.  The combination of GSS-API credential handle and
   mechanism identifies the principal whose identity will be asserted by
   the credential when used with that mechanism.

   The gss_init_sec_context and gss_accept_sec_context routines allow
   the value GSS_C_NO_CREDENTIAL to be specified as their credential
   handle parameter.  This special credential-handle indicates a desire
   by the application to act as a default principal.  While individual
   GSS-API implementations are free to determine such default behavior
   as appropriate to the mechanism, the following default behavior by
   these routines is recommended for portability:

   gss_init_sec_context

      1) If there is only a single principal capable of initiating
         security contexts for the chosen mechanism that the application
         is authorized to act on behalf of, then that principal shall be
         used, otherwise

      2) If the platform maintains a concept of a default network-
         identity for the chosen mechanism, and if the application is
         authorized to act on behalf of that identity for the purpose of
         initiating security contexts, then the principal corresponding
         to that identity shall be used, otherwise

      3) If the platform maintains a concept of a default local
         identity, and provides a means to map local identities into
         network-identities for the chosen mechanism, and if the
         application is authorized to act on behalf of the network-
         identity image of the default local identity for the purpose of





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


         initiating security contexts using the chosen mechanism, then
         the principal corresponding to that identity shall be used,
         otherwise

      4) A user-configurable default identity should be used.

   gss_accept_sec_context

      1) If there is only a single authorized principal identity capable
         of accepting security contexts for the chosen mechanism, then
         that principal shall be used, otherwise

      2) If the mechanism can determine the identity of the target
         principal by examining the context-establishment token, and if
         the accepting application is authorized to act as that
         principal for the purpose of accepting security contexts using
         the chosen mechanism, then that principal identity shall be
         used, otherwise

      3) If the mechanism supports context acceptance by any principal,
         and if mutual authentication was not requested, any principal
         that the application is authorized to accept security contexts
         under using the chosen mechanism may be used, otherwise

      4)A user-configurable default identity shall be used.

   The purpose of the above rules is to allow security contexts to be
   established by both initiator and acceptor using the default behavior
   wherever possible.  Applications requesting default behavior are
   likely to be more portable across mechanisms and platforms than ones
   that use gss_acquire_cred to request a specific identity.

3.6. Contexts

   The gss_ctx_id_t data type contains a caller-opaque atomic value that
   identifies one end of a GSS-API security context.  It should be
   implemented as a pointer or arithmetic type.  If a pointer type is
   chosen, care should be taken to ensure that two gss_ctx_id_t values
   may be compared with the == operator.

   The security context holds state information about each end of a peer
   communication, including cryptographic state information.









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


3.7. Authentication tokens

   A token is a caller-opaque type that GSS-API uses to maintain
   synchronization between the context data structures at each end of a
   GSS-API security context.  The token is a cryptographically protected
   octet-string, generated by the underlying mechanism at one end of a
   GSS-API 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 GSS-API and the application using the gss_buffer_t conventions.

3.8. Interprocess tokens

   Certain GSS-API routines are intended to transfer data between
   processes in multi-process programs.  These routines use a caller-
   opaque octet-string, generated by the GSS-API in one process for use
   by the GSS-API in another process.  The calling application is
   responsible for transferring such tokens between processes in an OS-