rfc1509.txt

RFC 的详细文档！

Network Working Group                                            J. Wray
Request for Comments: 1509                 Digital Equipment Corporation
                                                          September 1993


               Generic Security Service API : C-bindings

Status of this Memo

   This RFC specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" for the standardization state and status
   of this protocol.  Distribution of this memo is unlimited.

Abstract

   This document specifies C language bindings for the Generic Security
   Service Application Program Interface (GSS-API), which is described
   at a language-independent conceptual level in other documents.

   The Generic Security Service Application Programming Interface (GSS-
   API) provides security services to its callers, and is intended for
   implementation atop alternative underlying cryptographic mechanisms.
   Typically, GSS-API callers will be application protocols into which
   security enhancements are integrated through invocation of services
   provided by the GSS-API. The GSS-API allows a caller application to
   authenticate a principal identity associated with a peer application,
   to delegate rights to a peer, and to apply security services such as
   confidentiality and integrity on a per-message basis.

1. INTRODUCTION

   The Generic Security Service Application Programming Interface [1]
   provides security services to calling applications.  It allows a
   communicating application to authenticate the user associated with
   another application, to delegate rights to another application, and
   to apply security services such as confidentiality and integrity on a
   per-message basis.

   There are four stages to using the GSSAPI:

   (a) The application acquires a set of credentials with which it may
       prove its identity to other processes.  The application's
       credentials vouch for its global identity, which may or may not
       be related to the local username under which it is running.





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


   (b) A pair of communicating applications establish a joint security
       context using their credentials.  The security context is a
       pair of GSSAPI data structures that contain shared state
       information, which is required in order that per-message
       security services may be provided.  As part of the
       establishment of a security context, the context initiator is
       authenticated to the responder, and may require that the
       responder is authenticated in turn.  The initiator may
       optionally give the responder the right to initiate further
       security contexts.  This transfer of rights is termed
       delegation, and is achieved by creating a set of credentials,
       similar to those used by the originating application, but which
       may be used by the responder.  To establish and maintain the
       shared information that makes up the security context, certain
       GSSAPI calls will return a token data structure, which is a
       cryptographically protected opaque data type.  The caller of
       such a GSSAPI routine is responsible for transferring the token
       to the peer application, which should then pass it to a
       corresponding GSSAPI routine which will decode it and extract
       the information.

   (c) Per-message services are invoked to apply either:

       (i) integrity and data origin authentication, or

       (ii) confidentiality, integrity and data origin authentication
            to application data, which are treated by GSSAPI as
            arbitrary octet-strings.  The application transmitting a
            message that it wishes to protect will call the appropriate
            GSSAPI routine (sign or seal) to apply protection, specifying
            the appropriate security context, and send the result to the
            receiving application.  The receiver will pass the received
            data to the corresponding decoding routine (verify or unseal)
            to remove the protection and validate the data.

   (d) At the completion of a communications session (which may extend
       across several connections), the peer applications call GSSAPI
       routines to delete the security context.  Multiple contexts may
       also be used (either successively or simultaneously) within a
       single communications association.

2. GSSAPI Routines

   This section lists the functions performed by each of the GSSAPI
   routines and discusses their major parameters, describing how they
   are to be passed to the routines.  The routines are listed in figure
   4-1.




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


                      Figure 4-1  GSSAPI Routines


            Routine                               Function

            gss_acquire_cred               Assume a global identity

            gss_release_cred               Discard credentials

            gss_init_sec_context           Initiate a security context
                                           with a peer application

            gss_accept_sec_context         Accept a security context
                                           initiated by a peer
                                           application

            gss_process_context_token      Process a token on a security
                                           context from a peer
                                           application

            gss_delete_sec_context         Discard a security context

            gss_context_time               Determine for how long a
                                           context will remain valid

            gss_sign                       Sign a message; integrity
                                           service

            gss_verify                     Check signature on a message

            gss_seal                       Sign (optionally encrypt) a
                                           message; confidentiality
                                           service

            gss_unseal                     Verify (optionally decrypt)
                                           message

            gss_display_status             Convert an API status code
                                           to text

            gss_indicate_mechs             Determine underlying
                                           authentication mechanism

            gss_compare_name               Compare two internal-form
                                           names

            gss_display_name               Convert opaque name to text




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


            gss_import_name                Convert a textual name to
                                           internal-form

            gss_release_name               Discard an internal-form
                                           name

            gss_release_buffer             Discard a buffer

            gss_release_oid_set            Discard a set of object
                                           identifiers

            gss_inquire_cred               Determine information about
                                           a credential

   Individual GSSAPI implementations may augment these routines by
   providing additional mechanism-specific routines if required
   functionality is not available from the generic forms.  Applications
   are encouraged to use the generic routines wherever possible on
   portability grounds.

2.1. Data Types and Calling Conventions

   The following conventions are used by the GSSAPI:

2.1.1. Structured data types

   Wherever these GSSAPI C-bindings describe structured data, only
   fields that must be provided by all GSSAPI implementation are
   documented.  Individual implementations may provide additional
   fields, either for internal use within GSSAPI routines, or for use by
   non-portable applications.

2.1.2. Integer types

   GSSAPI defines 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 GSSAPI routine definitions. Individual GSSAPI
   implementations will include appropriate typedef definitions to map
   this type onto a built-in data type.

2.1.3. String and similar data

   Many of the GSSAPI routines take arguments and return values that
   describe contiguous multiple-byte data.  All such data is passed
   between the GSSAPI and the caller using the gss_buffer_t data type.



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


   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 passed to the application by a GSSAPI routine using
   the gss_buffer_t conventions is allocated by the GSSAPI 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.

2.1.3.1. Opaque data types

   Certain multiple-word data items are considered opaque data types at
   the GSSAPI, because their internal structure has no significance
   either to the GSSAPI 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_seal
   (which is opaque to the GSSAPI).  Opaque data is passed between the
   GSSAPI and the application using the gss_buffer_t datatype.

2.1.3.2. Character strings

   Certain multiple-word data items may be regarded as simple ISO
   Latin-1 character strings.  An example of this is the
   input_name_buffer parameter to gss_import_name.  Some GSSAPI routines
   also return character strings.  Character strings are passed between
   the application and the GSSAPI using the gss_buffer_t datatype,
   defined earlier.

2.1.4. Object Identifiers

   Certain GSSAPI 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 GSSAPI caller to select an
   underlying security mechanism.  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;




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


   The elements field of this structure points to the first byte of an
   octet string containing the ASN.1 BER encoding of the value 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- oganization(3) icd-ecma(12) member-company(2) dec(1011)
   cryptoAlgorithms(7) SPX(5)} meaning SPX (Digital's X.509
   authentication mechanism) has a length field of 7 and an elements
   field pointing to seven octets containing the following octal values:
   53,14,2,207,163,7,5. GSSAPI implementations should provide constant
   gss_OID values to allow callers 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
   2.1.10).  Applications should treat gss_OID_desc values returned by
   GSSAPI routines as read-only.  In particular, the application should
   not attempt to deallocate them.  The gss_OID_desc datatype is
   equivalent to the X/Open OM_object_identifier datatype [2].

2.1.5. Object Identifier Sets

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