Subject: draft-williams-gssapi-stackable-pseudo-mechs-00.txt

From: Nicolas Williams <[email-masked]>
Date: Wed, 19 May 2004 15:07:41 -0500

Network Working Group                                   Nicolas Williams
INTERNET-DRAFT                                          Sun Microsystems
                                                           November 2004

           Stackable Generic Security Service Pseudo-Mechanisms
           <draft-williams-gssapi-stackable-pseudo-mechs-00.txt>

Status of this Memo

   This document is an Internet-Draft and is subject to all provisions
   of Section 10 of RFC2026.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as
   Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six
   months and may be updated, replaced, or obsoleted by other
   documents at any time.  It is inappropriate to use Internet-
   Drafts as reference material or to cite them other than as
   "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/1id-abstracts.html

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html

Copyright Notice

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

Abstract

   This document defines and formalizes the concept of stackable pseudo-
   mechanisms for the Generic Security Service Application Programming
   Interface (GSS-API) and introduces a framework to support stackable
   pseudo-mechanisms and mechanism compositing.

   Stackable GSS-API pseudo-mechanisms allow for the composition of new
   mechanisms that combine features from multiple mechanisms.  Stackable
   mechanisms that add support for Perfect Forward Security (PFS), data
   compression, additional authentication factors, etc... are
   facilitated by this document.

Table of Contents

   1.       Introduction                                       pg. 3
   1.1.     Glossary                                           pg. 3
   2.       Issues with Mechanism Composition                  pg. 4

N. Williams							[Page 1]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   3.       Mechanism Composition                              pg. 5
   3.1.     Construction of Composed Mechanism OIDs            pg. 5
   3.2.     Mechanism Composition Rules                        pg. 6
   3.3.     Interfacing with Composite Mechanisms              pg. 6
   3.4.     Compatibility with the Basic GSS-API Interfaces    pg. 7
   3.5.     Processing of Tokens for Composite Mechanisms      pg. 7
   4.       New GSS-API Interfaces                             pg. 8
   4.1.     Mechanism Attributes and Attribute Sets            pg. 8
   4.1.1.   Determination of Attribute Sets of Composite Mechs pg. 9
   4.1.2.   Initial Set of Known Mechanism Attributes          pg. 9
   4.1.3.   Mechanism Attribute Sets of Existing Mechs         pg. 11
   4.2.     New GSS-API Function Interfaces                    pg. 12
   4.2.1.   GSS_Indicate_mechs_by_mech_attrs()                 pg. 12
   4.2.2.   GSS_Inquire_mech_attrs_for_mech()                  pg. 13
   4.2.3.   GSS_Display_mech_attr()                            pg. 14
   4.2.4.   GSS_Compose_oid()                                  pg. 15
   4.2.5.   GSS_Decompose_oid()                                pg. 15
   4.2.6.   GSS_Release_oid()                                  pg. 16
   4.2.7.   GSS_Indicate_negotiable_mechs()                    pg. 16
   4.2.8.   GSS_Negotiate_mechs()                              pg. 17
   4.3.     New Major Status Values                            pg. 18
   4.4.     C-Bindings                                         pg. 18
   5.       Negotiation of Composite Mechanisms                pg. 19
   5.1.     Negotiation of Composite Mechanisms Through SPNEGO pg. 20
   6.       Requirements for Mechanism Designers               pg. 20
   7.       IANA Considerations                                pg. 20
   8.       Security considerations                            pg. 20
   9.       References                                         pg. 21
   9.1.     Informative references                             pg. 21
   9.2.     Normative references                               pg. 21
   10.      Author's Address                                   pg. 21

N. Williams							[Page 2]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

Conventions used in this document

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].
   
1.    Introduction

   Recent discussions within the IETF have shown the need for a
   refactoring of the features that GSS-API mechanisms may provide and a
   way to compose new mechanisms from smaller components.

   Mechanism features are more formally referred to as "mechanism
   attributes" below.  The terms "feature" and mechanism attribute" are
   sometimes used interchangeably.

   One way to do this is to "stack" multiple mechanisms on top of each
   other such that the features of all of them are summed into a new,
   composite mechanism.

   One existing GSS-API mechanism, LIPKEY [LIPKEY], is essentially
   stacked over another, SPKM-3 [LIPKEY], although LIPKEY does not
   conform to the stackable pseduo-mechanism framework described herein.

   The first truly stackable pseudo-mechanism proposed, CCM [CCM] was
   for signalling the willingness of an initiator and/or acceptor to
   utilize channel bindings as well as to correctly implement channel
   bindings.

   Since then other similar mechanism compositing needs and ideas have
   come up, along with problems such as "what combinations are possible,
   useful, reasonable and secure?"  Problems which we believe are solved
   herein.

   Therefore the time has come to define the concept of GSS-API
   mechanism compositing through the use of stackable pseudo-mechanisms.

1.1.    Glossary

   Concrete GSS-API mechanism

      A mechanism which can be used standalone.  Examples include: the
      Kerberos V mechanism [CFX], SPKM-1/2 [SPKM] and SPKM-3 [LIPKEY].

   GSS-API Pseudo-mechanism

      A mechanism which uses other mechanisms in the construction of its
      context and/or per-message tokens and security contexts.  SPNEGO
      is an example of this.

N. Williams							[Page 3]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   Stackable GSS-API pseudo-mechanism

      A mechanism which uses a single other mechanism in the
      construction of its tokens such that the OID of the composite
      result can be constructed by prepending the OID of the stackable
      pseudo-mechanism to the OID of the mechanism to be used by it.

   Mechanism-negotiation GSS-API pseudo-mechanism

      A GSS-API mechanism that negotiates the use of GSS-API mechanisms.
      SPNEGO [SPNEGO] is an example of this.

2.    Issues with Mechanism Composition

   Interfacing with composite mechanisms through the existing GSS-API
   interfaces and the handling of composite mechanism tokens is
   straightforward enough and described in section 3.

   However, the concepts of stackable and composite mechanisms do give
   rise to several minor problems:

    - How to determine allowable combinations of mechanisms;

    - How to encode composite mechanism OIDs;

    - How to decompose the OID of a composite mechanism and process its
      tokens properly;

    - Application interfacing issues such as:

       - Whether and/or which composite mechanisms should be listed by
	 GSS_Indicate_mechs();

       - Whether and/or which composite mechanisms not listed by
	 GSS_Indicate_mechs() may nonetheless be available for use by
	 applications and how applications can detect their
	 availability;

       - What additional interfaces should be provided to help
	 applications select appropriate mechanisms;

    - Mechanism negotiation issues (related to the application interface
      issues listed above), such as:

       - Should applications advertise composite mechanisms in SPNEGO or
	 other application-specific mechanism negotiation contexts?

       - Or should applications advertise concrete and stackable pseudo-
	 mechanisms in SPNEGO or other application-specific mechanism
	 negotiation contexts?

N. Williams							[Page 4]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   Section 3 addresses the OID composition, decomposition and encoding
   issues, as well as basic interfacing and token handling issues.

   Section 4 addresses the application interfacing issues.

   Section 5 addresses the mechanism negotiation issues.

3.    Mechanism Composition

   Mechanism composition by stacking pseudo-mechanisms on a concrete
   mechanism is conceptually simple: join the OIDs of the several
   mechanisms in question and process GSS-API tokens and routine calls
   through the top-most pseudo-mechanism in a stack, which can then, if
   necessary, do the same with the remainder of the stack.

   Some stackable pseudo-mechanisms may do nothing more than perform
   transformations on application data (e.g., compression); such
   pseudo-mechanisms will generally chain the processing of tokens and
   routine calls to the mechanisms below them in the stack.

   Other stackable pseudo-mechanisms may utilize the mechanisms below
   them only during security context setup.  For example, a stackable
   pseudo-mechanism could perform a Diffie-Hellman key exchange and
   authenticate it by binding a security context established with the
   mechanism stacked below it; such a mechanism would provide its own
   per-message tokens.

3.1.    Construction of Composed Mechanism OIDs

   Composition of mechanism OIDs is simple: prepend the OID of one
   pseudo-mechanism to the OID of another mechanism (composite or
   otherwise), but there MUST always be at least one final mechanism OID
   and it MUST be useful standalone (i.e., it MUST NOT be a
   pseudo-mechanism).  A composite mechanism OID forms, essentially, a
   stack.

   The encoding of composed mechanism OIDs is not quite the
   concatenation of the component OIDs' encodings, however.  This is
   because the first two arcs of ASN.1 OIDs are encoded differently from
   subsequent arcs (the first two arcs have a limited namespace and are
   encoded as a single octet), so were composite mechanism OIDs to be
   encoded as the concatenation of the component OIDs the result would
   not decode as the concatenation of the component OIDs.  To avoid this
   problem the first two arcs of each component of a composite mechanism
   OID, other than the leading component, will be encoded as other arcs
   would.

   Decomposition of mechanism OIDs is similar, with each pseudo-
   mechanism in the stack being able to determine the OID suffix from
   knowledge of its own OID(s), from the composite mechanism OID in its
   OID or OID SET arguments and from the the composite OID from the
   initial context token for a given context.

N. Williams							[Page 5]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   New pseudo-mechanisms MAY be allocated OIDs from the prefix given
   below as follows by assignment of a sub-string of OID arcs to be
   appended to this prefix.  This prefix OID is:

   <TBD>
   [1.3.6.1.5.5.11 appears to be available, registration w/ IANA TBD]

   All OID allocations below this OID MUST be for stackable pseudo-
   mechanisms and MUST consist of a single arc.  This will make it
   possible to decompose the OIDs of composite mechanisms without
   necessarily knowing a priori the OIDs of the component stackable
   pseudo-mechanisms.

3.2.    Mechanism Composition Rules

   All new stackable pseudo-mechanisms MUST specify the rules for
   determining whether they can stack above a given mechanism, composite
   or otherwise.  Such rules may be based on specific mechanism
   attribute sets and/or specific OIDs (composite and otherwise) of
   mechanisms stacked below them.

   All stackable pseudo-mechanisms MUST have the following mechanism
   composition rule relating to unknown mechanism attributes:

    - composition with mechanisms supporting unknown mechanism
      attributes MUST NOT be permitted.

   This rule protects against compositions which cannot be considered
   today but which might nonetheless arise due to the introduction of
   new mechanisms and which might turn out to be insecure or otherwise
   undesirable.

   Mechanism composition rules for stackable pseudo-mechanisms MAY and
   SHOULD be updated as new GSS-API mechanism attributes and mechanisms
   sporting them are introduced.  The specifications of mechanisms that
   introduce new mechanism attributes or which otherwise should not be
   combined with others in ways which would be permitted under existing
   rules SHOULD also update the mechanism composition rules of affected
   pseudo-mechanisms.

3.3.    Interfacing with Composite Mechanisms

   The basic GSS-API [RFC2743] interfaces MUST NOT accept as input or
   provide as output the OID of any stackable pseudo-mechanism.
   Composite mechanisms MUST be treated as concrete mechanisms by the
   basic GSS-API interfaces [RFC2743].

   Thus the way in which a composite mechanism is used by applications
   with the basic GSS-API (version 2, update 1) is straightforward,
   exactly as if composite mechanisms were normal GSS-API mechanisms.

   This is facilitated by the fact that in all cases where the GSS-API

N. Williams							[Page 6]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   implementation might need to know how to process or create a token it
   has the necessary contextual information, the mechanism OID,
   available and can decompose composite mechanism OIDs as necessary.

   For example, for initial GSS_Init_sec_context() calls the
   implementation knows the desired mechanism OID, and if it should be
   left unspecified, it can pick a default mechanism given the initiator
   credentials provided by the application (and if none are provided
   other default mechanism and credential selections can still be made).
   For subsequent calls to GSS_Init_sec_context() the implementation
   knows which mechanism to use from the given [partially established]
   security context.  Similarly for GSS_Accept_sec_context, where on
   initial calls the mechanism OID can be determined from the given
   initial context token's framing.

   The manner in which GSS-API implementations and the various
   mechanisms and pseudo-mechanisms interface with one another is more
   interesting; it is also left as an excercise to implementors.

3.4.    Compatibility with the Basic GSS-API Interfaces

   In order to preserve backwards compatibility with applications that
   use only the basic GSS-API interfaces (version 2, update 1), several
   restrictions are imposed on the use of composite and stackable
   pseduo-mechanisms with the basic GSS-API interfaces:

    o  GSS_Indicate_mechs() MUST NOT indicate support for any stackable
       pseduo-mechanisms under any circumstance.

    o  GSS_Indicate_mechs() MAY indicate support for some, all or none
       of the available composite mechanisms.

    o  Which composite mechanisms, if any, are indicated through
       GSS_Indicate_mechs() SHOULD be configurable.

    o  GSS_Acquire_cred() and GSS_Add_cred() MUST NOT create credentials
       for composite mechanisms not explicitly requested or, if
       GSS_C_NULL_OID is given as a desired for composite mechanisms not
       indicated by GSS_Indicate_mechs().

    o  GSS_Acquire_cred() and GSS_Add_cred() MUST NOT (and truly cannot)
       create credentials for stackable pseudo-mechanisms.

3.5.    Processing of Tokens for Composite Mechanisms

   The initial context token for any mechanism, composite or otherwise,
   MUST be encapsulated as described in section 3.1 of rfc2743
   [RFC2743], and the OID used in that framing MUST be that of the
   mechanism, but in the case of composite mechanisms this OID MUST be
   the OID of the leading component of the composite mechanism.

   Note that this has implications for multi-mechanism implementations
   of the GSS-API, namely that acceptors MUST route initial context

N. Williams							[Page 7]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   tokens to the appropriate mechanism and they MUST allow that
   mechanism to determine the composite mechanism OID (such as by
   allowing that mechanism's GSS_Accept_sec_context() to output the
   actual mechanism to the application.

   In all other cases the mechanism that produced a given token can be
   determined by the given security context.

4.    New GSS-API Interfaces

   GSS-API applications face, today, the problem of how to select from
   multiple GSS-API mechanisms that may be available.  This problem is
   likely to be exacerbated by the introduction of stackable.

   To address this problem we introduce a new concept: that of mechanism
   attributes.  By allowing applications to query the set of attributes
   associated with individual mechanisms and to find out which
   mechanisms support a given set of attributes we allow applications to
   select mechanisms based on their attributes yet without having to
   hardcode mechanism OIDs.

   Section 4.1 describes the mechanism mechanism attributes concept.
   Sections 4.2.1, 4.2.2 and 4.2.3 describe three new interfaces that
   deal in mechanisms and attribute sets:

    - GSS_Indicate_mechs_by_attrs()
    - GSS_Inquire_attrs_for_mech()
    - GSS_Display_mech_attr()

   Additional utility functions for mechanism OID composition and
   decomposition are given in sections 4.2.4, 4.2.5 and 4.2.6.

   Finally, two utility functions, GSS_Indicate_negotiable_mechs() and
   GSS_Negotiate_mechs(), to aid applications in mechanism negotiation
   are described in sections 4.2.7 and 4.2.8.  These two interfaces may
   be implemented entirely in terms of the other interfaces described
   herein.

4.1.    Mechanism Attributes and Attribute Sets

   An abstraction for the features provided by pseudo-mechanisms is
   needed in order to facilitate the programmatic composition of
   mechanisms.

   Two data types are needed: one for individual mechanism attributes
   and one for mechanism attribute sets.  To simplify the mechanism
   attributes interfaces we reuse the 'OID' and 'OID set' data types and
   model individual mechanism attribute types as OIDs.

   To this end we define an open namespace of mechanism attributes and
   assign them arcs off of this OID:

   <TBD>

N. Williams							[Page 8]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   [1.3.6.1.5.5.12 appears to be available, registration w/ IANA TBD]

4.1.1.    Determination of Attribute Sets of Composite Mechs

   Each mechanism, composite or otherwise, has a set of mechanism
   attributes that it supports as specified.

   The mechanism attribute set of a composite mechanism is to be
   determined by the top-most stackable pseudo-mechanism of the
   composite according to its own attribute set and that of the
   mechanism stacked directly below it.

   It may well be that some composite mechanisms' attribute sets consist
   of the union of those of their every component, however this need not
   be the case and should not be assumed.

   Every stackable pseudo-mechanism's specification MUST specify the
   rules for determining the mechanism attribute set of mechanisms
   composed by it.

4.1.2.    Initial Set of Known Mechanism Attributes

   Mech Attr name           OID Arc	Arc name
   --------------           -------	--------

   GSS_C_MA_MECH_CONCRETE   (1)		concrete-mech
   GSS_C_MA_MECH_STACKABLE  (2)         pseudo-mech
   GSS_C_MA_MECH_COMPOSITE  (3)         composite-mech
   GSS_C_MA_MECH_NEGO       (4)         mech-negotiation-mech
   GSS_C_MA_MECH_GLUE       (5)         mech-glue
   GSS_C_MA_NOT_MECH        (6)         not-mech
   GSS_C_MA_DEPRECATED      (7)		mech-deprecated
   GSS_C_MA_NOT_DFLT_MECH   (8)		mech-not-default
   GSS_C_MA_ITOK_NOT_FRAMED (9)		initial-token-not-framed
   GSS_C_MA_AUTH_INIT       (10)        auth-init-princ
   GSS_C_MA_AUTH_TARG       (11)        auth-targ-princ
   GSS_C_MA_AUTH_INIT_INIT  (12)        auth-init-princ-initial
   GSS_C_MA_AUTH_TARG_INIT  (13)        auth-targ-princ-initial
   GSS_C_MA_AUTH_INIT_ANON  (14)        auth-init-princ-anon
   GSS_C_MA_AUTH_TARG_ANON  (15)        auth-targ-princ-anon
   GSS_C_MA_DELEG_CRED      (16)        deleg-cred
   GSS_C_MA_INTEG_PROT      (17)        integ-prot
   GSS_C_MA_CONF_PROT       (18)        conf-prot
   GSS_C_MA_PROT_READY      (19)        prot-ready
   GSS_C_MA_REPLAY_DET      (20)        replay-detection
   GSS_C_MA_OOS_DET         (21)        oos-detection
   GSS_C_MA_CBINDINGS       (22)        channel-bindings
   GSS_C_MA_CBINDINGS_BIDI  (23)        channel-bindings-bidirectional
   GSS_C_MA_CBINDINGS_NEGO  (24)        channel-bindings-negotiate
   GSS_C_MA_PFS             (25)        pfs
   GSS_C_MA_COMPRESS        (26)        compress
   <reserved>               (27..)

N. Williams							[Page 9]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   Mech Attr name           Purpose
   --------------           -------

   GSS_C_MA_MECH_CONCRETE   Indicates that a mech is neither a pseudo-
			    mechanism nor a composite mechanism.

   GSS_C_MA_MECH_STACKABLE  Indicates that a mech is a pseudo-mechanism.

   GSS_C_MA_MECH_COMPOSITE  Indicates that a mech is a composite
			    mechanism.

   GSS_C_MA_MECH_NEGO       Indicates that a mech negotiates other
			    mechs (e.g., SPNEGO has this attribute).

   GSS_C_MA_MECH_GLUE       Indicates that the OID is not for a
                            mechanism but for the GSS-API itself.

   GSS_C_MA_NOT_MECH        Indicates that the OID is known, yet also
			    known not to be the OID of any GSS-API
			    mechanism (or the GSS-API itself).

   GSS_C_MA_DEPRECATED      Indicates that a mech (or its OID) is
                            deprecated and MUST NOT be used as a default
			    mechanism.

   GSS_C_MA_NOT_DFLT_MECH   Indicates that a mech (or its OID) MUST NOT
			    be used as a default mechanism.

   GSS_C_MA_ITOK_NOT_FRAMED Indicates that the given mechanism's initial
			    context tokens are not properly framed as
			    per-section 3.1 of rfc2743.

   GSS_C_MA_AUTH_INIT       Indicates support for authentication of
			    initiator to acceptor.
   GSS_C_MA_AUTH_TARG       Indicates support for authentication of
			    acceptor to initiator.
   GSS_C_MA_AUTH_INIT_INIT  Indicates support for initial authentication
			    of initiator to acceptor.
   GSS_C_MA_AUTH_TARG_INIT  Indicates support for initial authentication
			    of acceptor to initiator.
   GSS_C_MA_AUTH_INIT_ANON  Indicates support for initiator anonymity.
   GSS_C_MA_AUTH_TARG_ANON  Indicates support for acceptor anonymity.

   GSS_C_MA_DELEG_CRED      Indicates support for credential delegation.

   GSS_C_MA_INTEG_PROT      Indicates support for per-message integrity
			    protection.
   GSS_C_MA_CONF_PROT       Indicates support for per-message
			    confidentiality protection.
   GSS_C_MA_PROT_READY      Indicates support for per-message protection
			    prior to full context establishment.

N. Williams							[Page 10]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   GSS_C_MA_REPLAY_DET      Indicates support for replay detection.
   GSS_C_MA_OOS_DET         Indicates support for out-of-sequence
			    detection.

   GSS_C_MA_CBINDINGS       Indicates support for channel bindings.
   GSS_C_MA_CBINDINGS_BIDI  Indicates support for bidirectional channel
			    bindings.
   GSS_C_MA_CBINDINGS_NEGO  Indicates that the mech acts as a signal for
			    application support for and willingness to
			    use channel bindings.

   GSS_C_MA_PFS             Indicates support for Perfect Forward
			    Security.

   GSS_C_MA_COMPRESS        Indicates support for compression of data
			    inputs to GSS_Wrap().

4.1.3.    Mechanism Attribute Sets of Existing Mechs

   The Kerberos V mechanism [RFC1964] [CFX] provides the following
   mechanism attributes:

      GSS_C_MA_MECH_CONCRETE 
      GSS_C_MA_AUTH_INIT
      GSS_C_MA_AUTH_TARG
      GSS_C_MA_DELEG_CRED
      GSS_C_MA_INTEG_PROT
      GSS_C_MA_CONF_PROT
      GSS_C_MA_PROT_READY (varies by initiator implementation)
      GSS_C_MA_REPLAY_DET
      GSS_C_MA_OOS_DET
      GSS_C_MA_CBINDINGS

   The Kerberos V mechanism also has a deprecated OID which has the same
   mechanism attributes as above, and GSS_C_MA_DEPRECATED.

   [The mechanism attributes of the SPKM family of mechanisms will be
    provided in a separate document as SPKM is current being reviewed
    for possibly significant changes due to problems in its
    specifications.]

   The LIPKEY mechanism offers the following attributes:

      GSS_C_MA_MECH_CONCRETE (should be stackable, but does not compose)
      GSS_C_MA_AUTH_INIT_INIT
      GSS_C_MA_AUTH_TARG (from SPKM-3)
      GSS_C_MA_AUTH_TARG_ANON (from SPKM-3)
      GSS_C_MA_INTEG_PROT
      GSS_C_MA_CONF_PROT
      GSS_C_MA_REPLAY_DET
      GSS_C_MA_OOS_DET

      (LIPKEY should also provide GSS_C_MA_CBINDINGS, but SPKM-3

N. Williams							[Page 11]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

       requires clarifications on this point.)

   The SPNEGO mechanism [SPNEGO] provides the following attribute:

      GSS_C_MA_MECH_NEGO

   All other mechanisms' attrivutes will be described elsewhere.

4.2.    New GSS-API Function Interfaces

   Several new interfaces are given by which, for example, GSS-API
   applications may determine what features are provided by a given
   mechanism, what mechanisms provide what features and what
   compositions are legal.

   These new interfaces are all OPTIONAL.

   In order to preserve backwards compatibility with applications that
   do not use the new interfaces GSS_Indicate_mechs() MUST NOT indicate
   support for any stackable pseduo-mechanisms.  GSS_Indicate_mechs()
   MAY indicate support for some, all or none of the available composite
   mechanisms; which composite mechanisms, if any, are indicated through
   GSS_Indicate_mechs() SHOULD be configurable.  GSS_Acquire_cred() and
   GSS_Add_cred() MUST NOT create credentials for composite mechanisms
   not explicitly requested or, if no desired mechanism or mechanisms
   are given, for composite mechanisms not indicated by
   GSS_Indicate_mechs().

   Applications SHOULD use GSS_Indicate_mechs_by_mech_attrs() instead of
   GSS_Indicate_mechs() wherever possible.

   Applications can use GSS_Indicate_mechs_by_mech_attrs() to determine
   what, if any, mechanisms provide a given set of features.

   GSS_Indicate_mechs_by_mech_attrs() can also be used to indicate (as
   in GSS_Indicate_mechs()) the set of available mechanisms of each type
   (concrete, mechanism negotiation pseudo-mechanism, stackable
   pseudo-mechanism and composite mechanisms).

   Applications may use GSS_Inquire_mech_attrs_for_mech() to test
   whether a given composite mechanism is available and the set of
   features that it offers.

   GSS_Negotiate_mechs() may be used to negotiate the use of mechanisms
   such that composite mechanisms need not be advertised but instead be
   implied by offering stackable pseudo-mechanisms.

4.2.1.    GSS_Indicate_mechs_by_mech_attrs()

   Inputs:

   o  desired_mech_attrs SET OF OBJECT IDENTIFIER  -- set of GSS_C_MA_*
   -- OIDs that the mechanisms indicated in the mechs output parameter

N. Williams							[Page 12]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   -- MUST offer.

   o  except_mech_attrs SET OF OBJECT IDENTIFIER  -- set of GSS_C_MA_*
   -- OIDs that the mechanisms indicated in the mechs output parameter
   -- MUST NOT offer.

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  mechs SET OF OBJECT IDENTIFIER  -- set of mechanisms that support
   -- the desired_mech_attrs but not the except_mech_attrs.

   Return major_status codes:

   o  GSS_S_COMPLETE indicates success; the output mechs parameter MAY
   be the empty set (GSS_C_NO_OID_SET).

   o  GSS_BAD_MECH_ATTR indicates that at least one mechanism attribute
   OID in desired_mech_attrs or except_mech_attrs is unknown to the
   implementation.

   o  GSS_S_FAILURE indicates that the request failed for some other
   reason.

   GSS_Indicate_mechs_by_mech_attrs() returns the set of mechanism OIDs
   that offer at least the desired_mech_attrs but none of the
   except_mech_attrs.

   When desired_mech_attrs and except_mech_attrs are the empty set this
   function acts as a version of GSS_indicate_mechs() that outputs the
   set of all supported mechanisms of all types.  By setting the
   desired_mechs input parameter to a set of a single GSS_C_MA_MECH*
   feature applications can obtain the list of all supported mechanisms
   of a given type (concrete, stackable, etc...).

4.2.2.    GSS_Inquire_mech_attrs_for_mech()

   Inputs:

   o  mech OBJECT IDENTIFIER -- mechanism OID

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  mech_attrs SET OF OBJECT IDENTIFIER  -- set of mech_attrs OIDs
   -- (GSS_C_MA_*)

N. Williams							[Page 13]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   Return major_status codes:

   o  GSS_S_COMPLETE indicates success; the output mech_attrs parameter
   MAY be the empty set (GSS_C_NO_OID_SET).

   o  GSS_S_BAD_MECH indicates that the mechanism named by the mech
   parameter does not exist or that mech is GSS_C_NO_OID and no default
   mechanism could be determined.

   o  GSS_S_FAILURE indicates that the request failed for some other
   reason.

   GSS_Inquire_mech_attrs_for_mech() indicates the set of mechanism
   attributes supported by a given mechanism.

   Because the mechanism attribute sets of composite mechanisms need not
   be the union of their components', when called to obtain the feature
   set of a composite mechanism GSS_Inquire_mech_attrs_for_mech()
   obtains it by querying the mechanism at the top of the stack.  See
   section 4.1.

4.2.3.    GSS_Display_mech_attr()

   Inputs:

   o  mech_attr OBJECT IDENTIFIER -- mechanism attribute OID

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  name OCTET STRING, -- name of mechanism attribute (e.g.,
   -- GSS_C_MA_*)

   o  short_desc OCTET STRING, -- a short description of the mechanism
   -- attribute

   o  long_desc OCTET STRING -- a longer description of the mechanism
   -- attribute

   Return major_status codes:

   o  GSS_S_COMPLETE indicates success.

   o  GSS_S_BAD_MECH_ATTR indicates that the mechanism attribute
   referenced by the mech_attr parameter is unknown to the
   implementation.

   o  GSS_S_FAILURE indicates that the request failed for some other
   reason.

N. Williams							[Page 14]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   This function can be used to obtain human-readable descriptions of
   GSS-API mechanism attributes.

4.2.4.    GSS_Compose_oid()

   Inputs:

   o  mech1 OBJECT IDENTIFIER, -- mechanism OID

   o  mech2 OBJECT IDENTIFIER -- mechanism OID

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  composite OBJECT IDENTIFIER  -- OID composition of mech1 with
   -- mech2 ({mech1 mech2})

   Return major_status codes:

   o  GSS_S_COMPLETE indicates success.

   o  GSS_S_BAD_MECH indicates that mech1 is not supported.

   o  GSS_S_FAILURE indicates that the request failed for some other
   reason.  The minor status will be specific to mech1 and may provide
   further information.

4.2.5.    GSS_Decompose_oid()

   Inputs:

   o  input_mech OBJECT IDENTIFIER, -- mechanism OID.

   o  mechs SET OF OBJECT IDENTIFIER -- mechanism OIDs (if
   -- GSS_C_NULL_OID_SET defaults to the set of stackable
   -- pseudo-mechanism OIDs indicated by
   -- GSS_Indicate_mechs_by_mech_attrs()).

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  lead_mech OBJECT IDENTIFIER,  -- leading stackable pseudo-
   -- mechanism OID.

   o  trail_mech OBJECT IDENTIFIER  -- input_mech with lead_mech removed
   -- from the front.

N. Williams							[Page 15]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   Return major_status codes:

   o  GSS_S_COMPLETE indicates success.

   o  GSS_S_BAD_MECH indicates that the input_mech could not be
   decomposed as no stackable pseudo-mechanism is available whose OID
   is a prefix of the input_mech.

   o  GSS_S_FAILURE indicates that the request failed for some other
   reason.

4.2.6.    GSS_Release_oid()

   The following text is adapted from the obsoleted rfc2078 [RFC2078].

   Inputs:

   o  oid OBJECT IDENTIFIER

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER

   Return major_status codes:

   o  GSS_S_COMPLETE indicates successful completion

   o  GSS_S_FAILURE indicates that the operation failed

   Allows the caller to release the storage associated with an OBJECT
   IDENTIFIER buffer allocated by another GSS-API call, specifically
   GSS_Compose_oid() and GSS_Decompose_oid().  This call's specific
   behavior depends on the language and programming environment within
   which a GSS-API implementation operates, and is therefore detailed
   within applicable bindings specifications; in particular, this call
   may be superfluous within bindings where memory management is
   automatic.

4.2.7.    GSS_Indicate_negotiable_mechs()

   Inputs:

   o  input_cred_handle CREDENTIAL HANDLE,  -- credential handle to be
   -- used with GSS_Init_sec_context(); may be GSS_C_NO_CREDENTIAL.

   o  peer_type_known BOOLEAN,  -- indicates whether the peer is known
   -- to support or not supprot the stackable pseudo-mechanism
   -- framework.

   o  peer_has_mech_stacking BOOLEAN  -- indicates whether the peer
   -- supports the stackable pseudo-mechanism framework; ignore if

N. Williams							[Page 16]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   -- peer_type_known is FALSE.

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  offer_mechs SET OF OBJECT IDENTIFIER,  -- mechanisms to offer.

   Return major_status codes:

   o  GSS_S_COMPLETE indicates success.

   o  GSS_S_NO_CREDENTIAL indicates that the caller's credentials are
   expired or, if input_cred_handle is GSS_C_NO_CREDENTIAL, that no
   credentials could be acquired for GSS_C_NO_NAME.

   o  GSS_S_FAILURE indicates that the request failed for some other
   reason.

   This function produces a set of mechanism OIDs, optimized for space,
   that its caller should advertise to peers during mechanism
   negotiation.

   The output offer_mechs parameter will include all of the mechanisms
   for which the input_cred_handle has elements (as indicated by
   GSS_Inquire_cred()), but composite mechanisms will be included either
   implicitly or implicitly as per the following rules:

    - if peer_type_known is TRUE and peer_has_mech_stacking is FALSE
      then no composite mechanisms not indicated by GSS_Indicate_mechs()
      will be advertised, explictly or implicitly;

    - if peer_type_known is FALSE then all composite mechanisms
      indicated by GSS_Indicate_mechs() for which input_cred_handle has
      elements will be indicated in offer_mechs explicitly and all
      others may be indicated in offer_mechs implicitly, by including
      their component stackable pseduo-mechanism OIDs (see below);

    - if peer_type_known is TRUE and peer_has_mech_stacking is TRUE
      composite mechanisms will generally not be advertised explicitly,
      but will be advertised implicitly, by including their component
      stackable pseduo-mechanism OIDs (see below);
      no composite mechanisms will be advertised explicitly

    - if the input_cred_handle does not have elements for all of the
      possible composite mechanisms that could be constructed from the
      its elements' decomposed mechanisms, then all composite mechanisms
      for which the input_cred_handle does have elements will be
      advertised explicitly in offer_mechs.

4.2.8.    GSS_Negotiate_mechs()

N. Williams							[Page 17]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   Inputs:

   o  input_credential_handle CREDENTIAL HANDLE,  -- mechanisms offered
   -- by the caller.

   o  peer_mechs SET OF OBJECT IDENTIFIER  -- mechanisms offered by
   -- the caller's peer.

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  mechs SET OF OBJECT IDENTIFIER  -- mechanisms common to the
   -- caller's credentials and the caller's peer.

   Return major_status codes:

   o  GSS_S_COMPLETE indicates success; the output mechs parameter MAY
   be the empty set (GSS_C_NO_OID_SET).

   o  GSS_S_NO_CREDENTIAL indicates that the caller's credentials are
   expired or, if input_cred_handle is GSS_C_NO_CREDENTIAL, that no
   credentials could be acquired for GSS_C_NO_NAME.

   o  GSS_S_FAILURE indicates that the request failed for some other
   reason.

   This function matches the mechanisms for which the caller has
   credentials with the mechanisms offered by the caller's peer and
   returns the set of mechanisms in common to both, accounting for any
   composite mechanisms offered by the peer implicitly.

4.3.    New Major Status Values

   A single new major status code is added for GSS_Display_mech_attr():

      GSS_S_BAD_MECH_ATTR

   roughly corresponding to GSS_S_BAD_MECH, but applicable to mechanism
   attribute OIDs, rather than to mechanism OIDs.

   For the C-bindings GSS_S_BAD_MECH_ATTR shall have a routine error
   number of 19 (this is shifted to the left by
   GSS_C_ROUTINE_ERROR_OFFSET).

4.4.    C-Bindings

   #define GSS_S_BAD_MECH_ATTR (19ul << GSS_C_ROUTINE_ERROR_OFFSET)

   OM_uint32 gss_inquire_mechs_for_mech_attrs(

N. Williams							[Page 18]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

      OM_uint32         *minor_status,
      const gss_OID_set  desired_mech_attrs,
      gss_OID_set       *mechs);

   OM_uint32 gss_inquire_mech_attrs_for_mech(
      OM_uint32         *minor_status,
      const gss_OID      mech,
      gss_OID_set       *mech_attrs);

   OM_uint32 gss_display_mech_attr(
      OM_uint32         *minor_status,
      const gss_OID      mech_attr,
      gss_buffer_t       name,
      gss_buffer_t       short_desc,
      gss_buffer_t       long_desc);

   OM_uint32 gss_compose_oid(
      OM_uint32         *minor_status,
      const gss_OID      mech1,
      const gss_OID      mech2,
      gss_OID		*composite);

   OM_uint32 gss_decompose_oid(
      OM_uint32         *minor_status,
      const gss_OID      input_mech,
      const gss_OID_set  mechs,
      gss_OID		*lead_mech,
      gss_OID		*trail_mech);

   OM_uint32 gss_release_oid(
      OM_uint32         *minor_status,
      gss_OID           *oid);

   OM_uint32 GSS_Indicate_negotiable_mechs(
      OM_uint32                 *minor_status,
      const gss_cred_id_t        input_cred_handle,
      OM_uint32                  peer_type_known,
      OM_uint32                  peer_has_mech_stacking,
      gss_OID_set               *offer_mechs);

   OM_uint32 gss_negotiate_mechs(
      OM_uint32                 *minor_status,
      const gss_cred_id_t        input_cred_handle,
      const gss_OID_set          peer_mechs,
      const gss_OID_set         *mechs);

5.    Negotiation of Composite Mechanisms

   Where GSS-API implementations do not support the stackable mechanism
   framework interfaces applications may only negotiate explicitly from
   a set of concrete and composite mechanism OIDs as indicated by
   GSS_Indicate_mechs() and for which suitable credentials are
   available.  GSS_Indicate_mechs(), as described in section 3.4, MUST

N. Williams							[Page 19]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   NOT indicate support for individual stackable pseudo-mechanisms, so
   there will not be any composite mechanisms implied but not explicitly
   offered in the mechanism negotiation.

   Applications that support the stackable mechanism framework SHOULD
   use GSS_Indicate_negotiable_mechs() to construct the set of mechanism
   OIDs to offer to their peers.  GSS_Indicate_negotiable_mechs()
   optimizes for bandwidth consumption by using decomposed OIDs instead
   of composed OIDs, where possible.  See section 4.2.7.

   Peers that support the stackable mechanism framework interfaces
   SHOULD use GSS_Negotiate_mechs() to select a mechanism as that
   routine accounts for composite mechanisms implicit in the mechanism
   offers.

5.1.    Negotiation of Composite Mechanisms Through SPNEGO

   SPNEGO applications MUST advertise either the set of mechanism OIDs
   for which they have suitable credentials or the set of mechanism OIDs
   produced by calling GSS_Indicate_negotiable_mechs() with the
   available credentials and the peer_type_known parameter as FALSE.

6.    Requirements for Mechanism Designers

   Stackable pseudo-mechanisms specifications MUST:

    - list the set of GSS-API mechanism attributes associated with them

    - list their initial mechanism composition rules

    - specify a mechanism for updating their mechanism composition rules

   All other mechanism specifications MUST:

    - list the set of GSS-API mechanism attributes associated with them

7.    IANA Considerations

   The namsepace of programming language symbols with names beginning
   with GSS_C_MA_* is reserved for allocation by the IANA.

   Allocation of arcs in the namespace of OIDs relative to the base
   mechanism attribute OID specified in section 4 is reserved to the
   IANA.

   Allocation of arcs in the namespace of OIDs relative to the base
   stackable pseduo-mechanism OID specified in section 3 is reserved to
   the IANA.

8.    Security considerations

   Some composite mechanisms may well not be secure.  The mechanism
   composition rules of pseudo-mechanisms (including the default

N. Williams							[Page 20]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   composition rule given in section 3 for unknown mechanism attributes)
   should be used to prevent the use of unsafe composite mechanisms.

   Designers of pseudo-mechanisms should study the possible combinations
   of their mechanisms with others and design mechanism composition
   rules accordingly.

   Similarly, pseudo-mechanism designers MUST specify, and implementors
   MUST implement, composite mechanism attribute set determination rules
   appropriate to the subject pseduo-mechanism, as described in section
   4.1.1.  Failure to do so may lead to inappropriate composite
   mechanisms being deemed permissible by programmatic application of
   flawed mechanism composition rules or to by their application with
   incorrect mechanism attribute sets.

9.    References

9.1.    Informative references

   [?]
   ...

9.2.    Normative references

   [RFC2026]
      S. Bradner, RFC2026:  "The Internet Standard Process - Revision
      3," October 1996, Obsoletes - RFC 1602, Status: Best Current
      Practice.

   [RFC2119]
      S. Bradner, RFC2119 (BCP14):  "Key words for use in RFCs to
      Indicate Requirement Levels," March 1997, Status: Best Current
      Practice.

   [RFC2743]
      J. Linn, RFC2743: "Generic Security Service Application Program
      Interface Version 2, Update 1," January 2000, Status: Proposed
      Standard.

   [RFC2744]
      J. Wray, RFC2744: "Generic Security Service API Version 2 :
      C-bindings," January 2000, Status: Proposed Standard.

   [MUST add references to LIPKEY, SPKM, the Kerberos V mechanism,
   SPNEGO, CCM, etc...]
   ...

10.    Author's Address

   Nicolas Williams
   Sun Microsystems
   5300 Riata Trace Ct
   Austin, TX 78727

N. Williams							[Page 21]

DRAFT		Stackable GSS-API Pseudo-Mechs		Expires November 2004

   Email: [email-masked]

Full Copyright Statement

   Copyright (C) The Internet Society (2004).  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
   English.

   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
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

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

N. Williams							[Page 22]
-++**==--++**==--++**==--++**==--++**==--++**==--++**==
This message was posted through the Stanford campus mailing list
server.  If you wish to unsubscribe from this mailing list, send the
message body of "unsubscribe ietf-cat-wg" to [email-masked]