tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 2743


Generic Security Service Application Program Interface Version 2, Update 1

Part 4 of 4, p. 93 to 101
Prev RFC Part


prevText      Top      Up      ToC       Page 93 
8:  Referenced Documents

   [ISO-7498-2]  International Standard ISO 7498-2-1988(E), Security

   [ISOIEC-8824] ISO/IEC 8824, "Specification of Abstract Syntax
                 Notation One (ASN.1)".

   [ISOIEC-8825] ISO/IEC 8825, "Specification of Basic Encoding Rules
                 for Abstract Syntax Notation One (ASN.1)".)

   [RFC-1507]:   Kaufman, C., "DASS: Distributed Authentication Security
                 Service", RFC 1507, September 1993.

   [RFC-1508]:   Linn, J., "Generic Security Service Application Program
                 Interface", RFC 1508, September 1993.

   [RFC-1509]:   Wray, J., "Generic Security Service API: C-bindings",
                 RFC 1509, September 1993.

   [RFC-1964]:   Linn, J., "The Kerberos Version 5 GSS-API Mechanism",
                 RFC 1964, June 1996.

   [RFC-2025]:   Adams, C., "The Simple Public-Key GSS-API Mechanism
                 (SPKM)", RFC 2025, October 1996.

   [RFC-2078]:   Linn, J., "Generic Security Service Application Program
                 Interface, Version 2", RFC 2078, January 1997.

   [RFC-2203]:   Eisler, M., Chiu, A. and L. Ling, "RPCSEC_GSS Protocol
                 Specification", RFC 2203, September 1997.

   [RFC-2744]:   Wray, J., "Generic Security Service API Version 2 :
                 C-bindings", RFC 2744, January 2000.

Top      Up      ToC       Page 94 

   The following constraints on GSS-API mechanism designs are adopted in
   response to observed caller protocol requirements, and adherence
   thereto is anticipated in subsequent descriptions of GSS-API
   mechanisms to be documented in standards-track Internet

   It is strongly recommended that mechanisms offering per-message
   protection services also offer at least one of the replay detection
   and sequencing services, as mechanisms offering neither of the latter
   will fail to satisfy recognized requirements of certain candidate
   caller protocols.


   It is the intent of this document to define an interface and
   procedures which preserve compatibility between GSS-V1 [RFC-1508]
   callers and GSS-V2 providers.  All calls defined in GSS-V1 are
   preserved, and it has been a goal that GSS-V1 callers should be able
   to operate atop GSS-V2 provider implementations.  Certain detailed
   changes, summarized in this section, have been made in order to
   resolve omissions identified in GSS-V1.

   The following GSS-V1 constructs, while supported within GSS-V2, are

      Names for per-message processing routines: GSS_Seal() deprecated
      in favor of GSS_Wrap(); GSS_Sign() deprecated in favor of
      GSS_GetMIC(); GSS_Unseal() deprecated in favor of GSS_Unwrap();
      GSS_Verify() deprecated in favor of GSS_VerifyMIC().

      GSS_Delete_sec_context() facility for context_token usage,
      allowing mechanisms to signal context deletion, is retained for
      compatibility with GSS-V1.  For current usage, it is recommended
      that both peers to a context invoke GSS_Delete_sec_context()
      independently, passing a null output_context_token buffer to
      indicate that no context_token is required.  Implementations of
      GSS_Delete_sec_context() should delete relevant locally-stored
      context information.

   This GSS-V2 specification adds the following calls which are not
   present in GSS-V1:

Top      Up      ToC       Page 95 
      Credential management calls: GSS_Add_cred(),

      Context-level calls: GSS_Inquire_context(), GSS_Wrap_size_limit(),
      GSS_Export_sec_context(), GSS_Import_sec_context().

      Per-message calls: No new calls.  Existing calls have been

      Support calls: GSS_Create_empty_OID_set(),
      GSS_Add_OID_set_member(), GSS_Test_OID_set_member(),
      GSS_Inquire_names_for_mech(), GSS_Inquire_mechs_for_name(),
      GSS_Canonicalize_name(), GSS_Export_name(), GSS_Duplicate_name().

   This GSS-V2 specification introduces three new facilities applicable
   to security contexts, indicated using the following context state
   values which are not present in GSS-V1:

      anon_state, set TRUE to indicate that a context's initiator is
      anonymous from the viewpoint of the target; Section 1.2.5 of this
      specification provides a summary description of the GSS-V2
      anonymity support facility, support and use of which is optional.

      prot_ready_state, set TRUE to indicate that a context may be used
      for per-message protection before final completion of context
      establishment; Section 1.2.7 of this specification provides a
      summary description of the GSS-V2 facility enabling mechanisms to
      selectively permit per-message protection during context
      establishment, support and use of which is optional.

      trans_state, set TRUE to indicate that a context is transferable
      to another process using the GSS-V2 GSS_Export_sec_context()

   These state values are represented (at the C bindings level) in
   positions within a bit vector which are unused in GSS-V1, and may be
   safely ignored by GSS-V1 callers.

   New conf_req_flag and integ_req_flag inputs are defined for
   GSS_Init_sec_context(), primarily to provide information to
   negotiating mechanisms.  This introduces a compatibility issue with
   GSS-V1 callers, discussed in section 2.2.1 of this specification.

Top      Up      ToC       Page 96 
   Relative to GSS-V1, GSS-V2 provides additional guidance to GSS-API
   implementors in the following areas: implementation robustness,
   credential management, behavior in multi-mechanism configurations,
   naming support, and inclusion of optional sequencing services.  The
   token tagging facility as defined in GSS-V2, Section 3.1, is now
   described directly in terms of octets to facilitate interoperable
   implementation without general ASN.1 processing code; the
   corresponding ASN.1 syntax, included for descriptive purposes, is
   unchanged from that in GSS-V1. For use in conjunction with added
   naming support facilities, a new Exported Name Object construct is
   added.  Additional name types are introduced in Section 4.

   This GSS-V2 specification adds the following major_status values
   which are not defined in GSS-V1:

        GSS_S_BAD_QOP                 unsupported QOP value
        GSS_S_UNAUTHORIZED            operation unauthorized
        GSS_S_UNAVAILABLE             operation unavailable
        GSS_S_DUPLICATE_ELEMENT       duplicate credential element
        GSS_S_NAME_NOT_MN                   name contains multi-mechanism
        GSS_S_GAP_TOKEN               skipped predecessor token(s)

   Of these added status codes, only two values are defined to be
   returnable by calls existing in GSS-V1: GSS_S_BAD_QOP (returnable by
   GSS_GetMIC() and GSS_Wrap()), and GSS_S_GAP_TOKEN (returnable by
   GSS_VerifyMIC() and GSS_Unwrap()).

   Additionally, GSS-V2 descriptions of certain calls present in GSS-V1
   have been updated to allow return of additional major_status values
   from the set as defined in GSS-V1: GSS_Inquire_cred() has
   returnable, GSS_Init_sec_context() has GSS_S_OLD_TOKEN,
   GSS_S_DUPLICATE_TOKEN, and GSS_S_BAD_MECH defined as returnable, and
   GSS_Accept_sec_context() has GSS_S_BAD_MECH defined as returnable.


   This document incorporates a number of changes relative to RFC-2078,
   made primarily in response to implementation experience, for purposes
   of alignment with the GSS-V2 C language bindings document, and to add
   informative clarification.  This section summarizes technical changes

Top      Up      ToC       Page 97 

      Clarified usage of object release routines, and incorporated
      statement that some may be omitted within certain operating

      Removed GSS_Release_OID, GSS_OID_to_str(), and GSS_Str_to_OID()

      Clarified circumstances under which zero-length tokens may validly
      exist as inputs and outputs to/from GSS-API calls.

      Added GSS_S_BAD_MIC status code as alias for GSS_S_BAD_SIG.

      For GSS_Display_status(), deferred to language bindings the choice
      of whether to return multiple status values in parallel or via
      iteration, and added commentary deprecating return of

      Adapted and incorporated clarifying material on optional service
      support, delegation, and interprocess context transfer from C
      bindings document.

      Added and updated references to related documents, and to current
      status of cited Kerberos mechanism OID.

      Added general statement about GSS-API calls having no side effects
      visible at the GSS-API level.

   Context-related (including per-message protection issues):

      Clarified GSS_Delete_sec_context() usage for partially-established

      Added clarification on GSS_Export_sec_context() and
      GSS_Import_sec_context() behavior and context usage following an
      export-import sequence.

      Added informatory conf_req_flag, integ_req_flag inputs to
      GSS_Init_sec_context().  (Note: this facility introduces a
      backward incompatibility with GSS-V1 callers, discussed in Section
      2.2.1; this implication was recognized and accepted in working
      group discussion.)

      Stated that GSS_S_FAILURE is to be returned if
      GSS_Init_sec_context() or GSS_Accept_sec_context() is passed the
      handle of a context which is already fully established.

Top      Up      ToC       Page 98 
      Re GSS_Inquire_sec_context(), stated that src_name and targ_name
      are not returned until GSS_S_COMPLETE status is reached; removed
      use of GSS_S_CONTEXT_EXPIRED status code (replacing with EXPIRED
      lifetime return value); stated requirement to retain inquirable
      data until context released by caller; added result value
      indicating whether or not context is fully open.

      Added discussion of interoperability conditions for mechanisms
      permitting optional support of QOPs. Removed reference to
      structured QOP elements in GSS_Verify_MIC().

      Added discussion of use of GSS_S_DUPLICATE_TOKEN status to
      indicate reflected per-message tokens.

      Clarified use of informational sequencing codes from per-message
      protection calls in conjunction with GSS_S_COMPLETE and
      GSS_S_FAILURE major_status returns, adjusting status code
      descriptions accordingly.

      Added specific statements about impact of GSS_GetMIC() and
      GSS_Wrap() failures on context state information, and generalized
      existing statements about impact of processing failures on
      received per-message tokens.

      For GSS_Init_sec_context() and GSS_Accept_sec_context(), permitted
      returned mech_type to be valid before GSS_S_COMPLETE, recognizing
      that the value may change on successive continuation calls in the
      negotiated mechanism case.

      Deleted GSS_S_CONTEXT_EXPIRED status from

      Added conf_req_flag input to GSS_Wrap_size_limit().

      Stated requirement for mechanisms' support of per-message
      protection services to be usable concurrently in both directions
      on a context.


      For GSS_Acquire_cred() and GSS_Add_cred(), aligned with C bindings
      statement of likely non-support for INITIATE or BOTH credentials
      if input name is neither empty nor a name resulting from applying
      GSS_Inquire_cred() against the default credential.  Further,
      stated that an explicit name returned by GSS_Inquire_context()
      should also be accepted.  Added commentary about potentially
      time-variant results of default resolution and attendant
      implications.  Aligned with C bindings re behavior when

Top      Up      ToC       Page 99 
      GSS_C_NO_NAME provided for desired_name. In GSS_Acquire_cred(),
      stated that NULL, rather than empty OID set, should be used for
      desired_mechs in order to request default mechanism set.

      Added GSS_S_CREDENTIALS_EXPIRED as returnable major_status for
      GSS_Acquire_cred(), GSS_Add_cred(), also specifying GSS_S_NO_CRED
      as appropriate return for temporary, user-fixable credential
      unavailability.  GSS_Acquire_cred() and GSS_Add_cred() are also to
      return GSS_S_NO_CRED if an authorization failure is encountered
      upon credential acquisition.

      Removed GSS_S_CREDENTIALS_EXPIRED status return from per-message
      protection, GSS_Context_time(), and GSS_Inquire_context() calls.

      For GSS_Add_cred(), aligned with C bindings' description of
      behavior when addition of elements to the default credential is

      Upgraded recommended default credential resolution algorithm to
      status of requirement for initiator credentials.

      For GSS_Release_cred(), GSS_Inquire_cred(), and
      GSS_Inquire_cred_by_mech(), clarified behavior for input


      Aligned GSS_Inquire_mechs_for_name() description with C bindings.

      Removed GSS_S_BAD_NAMETYPE status return from
      GSS_Duplicate_name(), GSS_Display_name(); constrained its
      applicability for GSS_Compare_name().

      Aligned with C bindings statement re GSS_Import_name() behavior
      with GSS_C_NO_OID input name type, and stated that GSS-V2
      mechanism specifications are to define processing procedures
      applicable to their mechanisms.  Also clarified GSS_C_NO_OID usage
      with GSS_Display_name().

      Downgraded reference to name canonicalization via DNS lookup to an

      For GSS_Canonicalize_name(), stated that neither negotiated
      mechanisms nor the default mechanism are supported input
      mech_types for this operation, and specified GSS_S_BAD_MECH status
      to be returned in this case.  Clarified that the
      GSS_Canonicalize_name() operation is non-destructive to its input

Top      Up      ToC       Page 100 
      Clarified semantics of GSS_C_NT_USER_NAME name type.

      Added descriptions of additional name types.  Also added
      discussion of GSS_C_NO_NAME and its constrained usage with
      specific GSS calls.

      Adapted and incorporated C bindings discussion about name
      comparisons with exported name objects.

      Added recommendation to mechanism designers for support of host-
      based service name type, deferring any requirement statement to
      individual mechanism specifications.  Added discussion of host-
      based service's service name element and proposed approach for
      IANA registration policy therefor.

      Clarified byte ordering within exported name object.  Stated that
      GSS_S_BAD_MECH is to be returned if, in the course of attempted
      import of an exported name object, the name object's enclosed
      mechanism type is unrecognized or unsupported.

      Stated that mechanisms may optionally accept GSS_C_NO_NAME as an
      input target name to GSS_Init_sec_context(), with comment that
      such support is unlikely within mechanisms predating GSS-V2,
      Update 1.


   John Linn
   RSA Laboratories
   20 Crosby Drive
   Bedford, MA  01730 USA

   Phone: +1 781.687.7817

Top      Up      ToC       Page 101 
Full Copyright Statement

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

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an


   Funding for the RFC Editor function is currently provided by the
   Internet Society.