rfc2744.txt

RFC 的详细文档！

Network Working Group                                             J. Wray
Request for Comments: 2744                                Iris Associates
Obsoletes: 1509                                              January 2000
Category: Standards Track


          Generic Security Service API Version 2 : C-bindings

Status of this Memo

   This document 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" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2000).  All Rights Reserved.

Abstract

   This document specifies C language bindings for Version 2, Update 1
   of the Generic Security Service Application Program Interface (GSS-
   API), which is described at a language-independent conceptual level
   in RFC-2743 [GSSAPI].  It obsoletes RFC-1509, making specific
   incremental changes in response to implementation experience and
   liaison requests.  It is intended, therefore, that this memo or a
   successor version thereof will become the basis for subsequent
   progression of the GSS-API specification on the standards track.

   The Generic Security Service Application Programming Interface
   provides security services to its callers, and is intended for
   implementation atop a variety of 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.











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


1.   Introduction

   The Generic Security Service Application Programming Interface
   [GSSAPI] 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 GSS-API:

   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 any local username under which it may be running.

   b) A pair of communicating applications establish a joint security
      context using their credentials.  The security context is a pair
      of GSS-API data structures that contain shared state information,
      which is required in order that per-message security services may
      be provided.  Examples of state that might be shared between
      applications as part of a security context are cryptographic keys,
      and message sequence numbers.  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, acting as an agent or
      delegate of the initiator.  This transfer of rights is termed
      delegation, and is achieved by creating a set of credentials,
      similar to those used by the initiating application, but which may
      be used by the responder.

      To establish and maintain the shared information that makes up the
      security context, certain GSS-API calls will return a token data
      structure, which is an opaque data type that may contain
      cryptographically protected data.  The caller of such a GSS-API
      routine is responsible for transferring the token to the peer
      application, encapsulated if necessary in an application-
      application protocol.  On receipt of such a token, the peer
      application should pass it to a corresponding GSS-API routine
      which will decode the token and extract the information, updating
      the security context state information accordingly.









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


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

      integrity and data origin authentication, or confidentiality,
      integrity and data origin authentication to application data,
      which are treated by GSS-API as arbitrary octet-strings.  An
      application transmitting a message that it wishes to protect will
      call the appropriate GSS-API routine (gss_get_mic or gss_wrap) to
      apply protection, specifying the appropriate security context, and
      send the resulting token to the receiving application.  The
      receiver will pass the received token (and, in the case of data
      protected by gss_get_mic, the accompanying message-data) to the
      corresponding decoding routine (gss_verify_mic or gss_unwrap) to
      remove the protection and validate the data.

   d) At the completion of a communications session (which may extend
      across several transport connections), each application calls a
      GSS-API routine to delete the security context.  Multiple contexts
      may also be used (either successively or simultaneously) within a
      single communications association, at the option of the
      applications.

2.   GSS-API Routines

      This section lists the routines that make up the GSS-API, and
      offers a brief description of the purpose of each routine.
      Detailed descriptions of each routine are listed in alphabetical
      order in section 5.

   Table 2-1  GSS-API Credential-management Routines

   Routine                Section              Function
   -------                -------              --------
   gss_acquire_cred           5.2  Assume a global identity; Obtain
                                   a GSS-API credential handle for
                                   pre-existing credentials.
   gss_add_cred               5.3  Construct credentials
                                   incrementally
   gss_inquire_cred           5.21 Obtain information about a
                                   credential
   gss_inquire_cred_by_mech   5.22 Obtain per-mechanism information
                                   about a credential.
   gss_release_cred           5.27 Discard a credential handle.









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


   Table 2-2  GSS-API Context-Level Routines

   Routine                 Section              Function
   -------                 -------              --------
   gss_init_sec_context       5.19 Initiate a security context with
                                   a peer application
   gss_accept_sec_context     5.1  Accept a security context
                                   initiated by a
                                   peer application
   gss_delete_sec_context     5.9  Discard a security context
   gss_process_context_token  5.25 Process a token on a security
                                   context from a peer application
   gss_context_time           5.7  Determine for how long a context
                                   will remain valid
   gss_inquire_context        5.20 Obtain information about a
                                   security context
   gss_wrap_size_limit        5.34 Determine token-size limit for
                                   gss_wrap on a context
   gss_export_sec_context     5.14 Transfer a security context to
                                   another process
   gss_import_sec_context     5.17 Import a transferred context


   Table 2-3  GSS-API Per-message Routines

   Routine                 Section              Function
   -------                 -------              --------
   gss_get_mic                5.15 Calculate a cryptographic message
                                   integrity code (MIC) for a
                                   message; integrity service
   gss_verify_mic             5.32 Check a MIC against a message;
                                   verify integrity of a received
                                   message
   gss_wrap                   5.33 Attach a MIC to a message, and
                                   optionally encrypt the message
                                   content;
                                   confidentiality service
   gss_unwrap                 5.31 Verify a message with attached
                                   MIC, and decrypt message content
                                   if necessary.











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


   Table 2-4  GSS-API Name manipulation Routines

   Routine                 Section              Function
   -------                 -------              --------
   gss_import_name            5.16 Convert a contiguous string name
                                   to internal-form
   gss_display_name           5.10 Convert internal-form name to
                                   text
   gss_compare_name           5.6  Compare two internal-form names

   gss_release_name           5.28 Discard an internal-form name
   gss_inquire_names_for_mech 5.24 List the name-types supported by
                                   the specified mechanism
   gss_inquire_mechs_for_name 5.23 List mechanisms that support the
                                   specified name-type
   gss_canonicalize_name      5.5  Convert an internal name to an MN
   gss_export_name            5.13 Convert an MN to export form
   gss_duplicate_name         5.12 Create a copy of an internal name


   Table 2-5  GSS-API Miscellaneous Routines

   Routine                Section              Function
   -------                -------              --------
   gss_add_oid_set_member    5.4  Add an object identifier to
                                  a set
   gss_display_status        5.11 Convert a GSS-API status code
                                  to text
   gss_indicate_mechs        5.18 Determine available underlying
                                  authentication mechanisms
   gss_release_buffer        5.26 Discard a buffer
   gss_release_oid_set       5.29 Discard a set of object
                                  identifiers
   gss_create_empty_oid_set  5.8  Create a set containing no
                                  object identifiers
   gss_test_oid_set_member   5.30 Determines whether an object
                                       identifier is a member of a set.

   Individual GSS-API 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.








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


3.   Data Types and Calling Conventions

   The following conventions are used by the GSS-API C-language
   bindings:

3.1. Integer types