< draft-zhu-spnego-2478bis-00.txt   draft-zhu-spnego-2478bis-01.txt >
NETWORK WORKING GROUP L. Zhu NETWORK WORKING GROUP L. Zhu
Internet-Draft K. Jaganathan Internet-Draft P. Leach
Obsoletes: 2478 (if approved) R. Ward Obsoletes: 2478 (if approved) K. Jaganathan
Expires: April 18, 2005 Microsoft Corporation Expires: May 22, 2005 Microsoft Corporation
October 18, 2004 S. Harman
MIT
W. Ingersoll
Sun Microsystems
November 21, 2004
The Simple and Protected GSS-API Negotiation Mechanism The Simple and Protected GSS-API Negotiation Mechanism
draft-zhu-spnego-2478bis-00 draft-zhu-spnego-2478bis-01
Status of this Memo Status of this Memo
This document is an Internet-Draft and is subject to all provisions This document is an Internet-Draft and is subject to all provisions
of section 3 of RFC 3667. By submitting this Internet-Draft, each of section 3 of RFC 3667. By submitting this Internet-Draft, each
author represents that any applicable patent or other IPR claims of author represents that any applicable patent or other IPR claims of
which he or she is aware have been or will be disclosed, and any of which he or she is aware have been or will be disclosed, and any of
which he or she become aware will be disclosed, in accordance with which he or she become aware will be disclosed, in accordance with
RFC 3668. RFC 3668.
skipping to change at page 1, line 36 skipping to change at page 1, line 40
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on April 18, 2005. This Internet-Draft will expire on May 22, 2005.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2004). Copyright (C) The Internet Society (2004).
Abstract Abstract
This document specifies a security negotiation mechanism for the This document specifies a negotiation mechanism for the Generic
Generic Security Service Application Program Interface (GSS-API) Security Service Application Program Interface (GSS-API) which is
which is described in RFC 2743. described in RFC 2743.
This mechanism allows negotiating and choosing one security mechanism
from a common set of security mechanisms shared by GSS-API peers.
Once the common security mechanism is identified, the security GSS-API peers can use this negotiation mechanism to choose from a
mechanism MAY also negotiate mechanism-specific options during its common set of security mechanisms.
context establishment, but that will be inside the mechanism tokens,
and invisible to this protocol.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions Used in This Document . . . . . . . . . . . . . . 4 2. Conventions Used in This Document . . . . . . . . . . . . . . 5
3. Negotiation Model . . . . . . . . . . . . . . . . . . . . . . 5 3. Negotiation Protocol . . . . . . . . . . . . . . . . . . . . . 6
3.1 Negotiation Description . . . . . . . . . . . . . . . . . 5 3.1 Negotiation Description . . . . . . . . . . . . . . . . . 6
3.2 Negotiation Procedure . . . . . . . . . . . . . . . . . . 6 3.2 Negotiation Procedure . . . . . . . . . . . . . . . . . . 7
4. Data Elements . . . . . . . . . . . . . . . . . . . . . . . . 11 4. Token Definitions . . . . . . . . . . . . . . . . . . . . . . 9
4.1 Mechanism Type . . . . . . . . . . . . . . . . . . . . . . 11 4.1 Mechanism Types . . . . . . . . . . . . . . . . . . . . . 9
4.2 Negotiation Tokens . . . . . . . . . . . . . . . . . . . . 11 4.2 Negotiation Tokens . . . . . . . . . . . . . . . . . . . . 9
4.2.1 negTokenInit . . . . . . . . . . . . . . . . . . . . . 12 4.2.1 negTokenInit . . . . . . . . . . . . . . . . . . . . . 10
4.2.2 negTokenResp . . . . . . . . . . . . . . . . . . . . . 13 4.2.2 negTokenResp . . . . . . . . . . . . . . . . . . . . . 11
5. Security Considerations . . . . . . . . . . . . . . . . . . . 15 5. Processing of mechListMIC . . . . . . . . . . . . . . . . . . 13
6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 6. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 15
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 16 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17
A. Changes since RFC2478 . . . . . . . . . . . . . . . . . . . . 17 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Intellectual Property and Copyright Statements . . . . . . . . 18 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 17
A. GSS-API Negotiation Support API . . . . . . . . . . . . . . . 19
A.1 GSS_Set_neg_mechs call . . . . . . . . . . . . . . . . . . 19
A.2 GSS_Get_neg_mechs call . . . . . . . . . . . . . . . . . . 19
B. Changes since RFC2478 . . . . . . . . . . . . . . . . . . . . 21
Intellectual Property and Copyright Statements . . . . . . . . 22
1. Introduction 1. Introduction
The GSS-API [RFC2743] provides a generic interface which can be The GSS-API [RFC2743] provides a generic interface which can be
layered atop different security mechanisms such that if communicating layered atop different security mechanisms such that if communicating
peers acquire GSS-API credentials for the same security mechanism, peers acquire GSS-API credentials for the same security mechanism,
then a security context MAY be established between them (subject to then a security context may be established between them (subject to
policy). However, GSS-API doesn't prescribe the method by which policy). However, GSS-API doesn't prescribe the method by which
GSS-API peers can establish whether they have a common security GSS-API peers can establish whether they have a common security
mechanism. mechanism.
The Simple and Protected GSS-API Negotiation (SPNEGO) mechanism The Simple and Protected GSS-API Negotiation (SPNEGO) mechanism
defined here is a pseudo-security mechanism, represented by the defined here is a pseudo security mechanism, represented by the
object identifier iso.org.dod.internet.security.mechanism.snego Object Identifier iso.org.dod.internet.security.mechanism.snego
(1.3.6.1.5.5.2) which enables GSS-API peers to determine in-band (1.3.6.1.5.5.2), which enables GSS-API peers to determine in-band
whether their credentials share common GSS-API security mechanism(s), whether their credentials share common GSS-API security mechanism(s),
and if so, to invoke normal security context establishment for a and if so, to invoke normal security context establishment for a
selected common security mechanism. This is most useful for selected common security mechanism. This is most useful for
applications that are based on GSS-API implementations which support applications that are based on GSS-API implementations and multiple
multiple security mechanisms. mechanisms are shared between the peers.
The simple and protected GSS-API mechanism negotiation is based on The SPNEGO mechanism negotiation is based on the following
the following negotiation model: the initiator proposes one security negotiation model: the initiator proposes a list of security
mechanism or a list of security mechanisms in its preference order mechanism(s), in its preference order (favorite choice first), the
(favorite choice first), the acceptor (the target) either accepts the acceptor (also known as the target) either accepts the initiator's
proposed security mechanism, or chooses one from the offered list, or preferred security mechanism (the first in the list), or chooses one
rejects the proposed value(s). The target then informs the initiator that is available from the offered list, or rejects the proposed
of its choice. value(s). The target then informs the initiator of its choice.
In order to avoid an extra round trip, the initial security token of Once a common security mechanism is chosen, it MAY also negotiate
the preferred mechanism for the initiator SHOULD be embedded in the mechanism-specific options during its context establishment, but that
initial negotiation token (as defined in Section 4.2). If the target will be inside the mechanism tokens and invisible to this protocol.
preferred mechanism matches the initiator's preferred mechanism, no
additional round trips may be incurred by using the negotiation
protocol.
The negotiation is protected and all the underlying mechanisms If per-message integrity services are available on the established
offered by the initiator MUST be capable of integrity protection. mechanism security context, the peers can then exchange MIC tokens to
ensure that the mechanism list was not tampered with. This MIC token
exchange is OPTIONAL if no interference could have material impact on
the negotiation, i.e., when the selected mechanism is the first
choice for both peers.
The Simple and Protected GSS-API Negotiation Mechanism uses the In order to avoid an extra round trip, the first security token of
concepts developed in the GSS-API specification [RFC2743]. The the preferred mechanism SHOULD be embedded in the initial negotiation
negotiation data is encapsulated in context-level tokens. Therefore, message (as defined in Section 4.2). This mechanism token is
callers of the GSS-API do not need to be aware of the existence of referred to as the optimistic token in this document. If the
the negotiation tokens but only of the new pseudo-security mechanism. selected mechanism matches the initiator's preferred mechanism, no
A failure in the negotiation phase causes a major status code to be additional round trips need to be incurred by using this protocol.
returned: GSS_S_BAD_MECH. In addition, by using the optimistic token, the initiator can recover
from a non-fatal error in producing the first token before a
mechanism can be selected. Implementations, however, MAY omit the
optimistic token, to avoid the cost of generating it in cases where
the initiator's preferred mechanism is not selected by the acceptor.
SPNEGO uses the concepts developed in the GSS-API specification
[RFC2743]. The negotiation data is encapsulated in context-level
tokens. Therefore, callers of the GSS-API do not need to be aware of
the existence of the negotiation tokens but only of the new
pseudo-security mechanism. A failure in the negotiation phase causes
a major status code to be returned: GSS_S_BAD_MECH.
2. Conventions Used in This Document 2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
3. Negotiation Model 3. Negotiation Protocol
3.1 Negotiation Description When the established mechanism context provides for integrity
protection, the mechanism negotiation can be protected. When
acquiring negotiated security mechanism tokens, per-message integrity
services are always requested by the SPNEGO mechanism.
Each OID represents one GSS-API mechanism or one variant of it. When the established mechanism context supports per-message integrity
services, SPNEGO guarantees that the selected mechanism is mutually
preferred.
This section describes the negotiation process of this protocol.
3.1 Negotiation Description
The first negotiation token sent by the initiator contains an ordered The first negotiation token sent by the initiator contains an ordered
list of mechanisms (in preference order, favorite choice first), and list of mechanisms (in preference order, favorite choice first), and
OPTIONALLY the initial security token for the preferred mechanism of optionally the initial security token for the preferred mechanism of
the initiator (i.e. the first of the list). the initiator (i.e., the first in the list). The list of security
mechanisms available for negotiation is based on the credentials
being used.
The target then processes the token from the initiator. This will The target then processes the token from the initiator. This will
result in one of three possible states (as defined in Section 4.2.2): result in one of four possible states (as defined in Section 4.2.2):
accept_completed, accept_incomplete, or reject. A reject state will accept_completed, accept_incomplete, reject, or request_mic. A
terminate the negotiation. An accept_completed state indicates that reject state will terminate the negotiation; an accept_completed
not only was the initiator-selected mechanism acceptable to the state indicates that not only was the initiator-selected mechanism
target, but that the initial token was sufficient to complete the acceptable to the target, but that the initial token was sufficient
authentication. An accept_incomplete state indicates that the target to complete the authentication; an accept_incomplete state indicates
has selected a different mechanism or the preferred mechanism is that further message exchange is needed but the MIC token exchange as
acceptable, but this mechanism requires at least one additional described in Section 5 is OPITONAL; a request_mic state (this state
message to complete the authentication. The target MAY produce a can only be present in the first reply message from the target)
context level token for a reject state. indicates the MIC token exchange is REQUIRED if per-message integrity
services are available.
The first negotiation token sent by the acceptor contains the result Unless the preference order is specified by the application (see
of the negotiation (accept_completed, accept_incomplete or reject) Appendix A), the policy by which the target chooses a mechanism is an
and, in case of accept, the agreed security mechanism. It MUST also implementation-specific local matter. In the absence of application
include the response mechanism token to the initial mechanism token specified preference order or other policy, the target SHALL choose
from the initiator, when the first proposed mechanism of the the first mechanism in the initiator proposed list for which it has
initiator has been selected and an initial mechanism token was valid credentials.
provided by the initiator. However, if the initiator's preferred
mechanism is not possible, the target will not emit a response
mechanism token in the first reply.
The policy by which the target chooses a mechanism is an In case of a successful negotiation, the security mechanism in the
implementation-specific local matter. In the absence of other first reply message represents the value suitable for the target, and
policy, the target MUST choose the first mechanism in the list for picked up from the list offered by the initiator. A context level
which valid credentials are available. token for a reject state is OPTIONAL.
The first negotiation token is the negTokenInit message and all Once a mechanism has been selected, the tokens specific to the
subsequent negotiation tokens are the negTokenResp message, as selected mechanism are carried within the negotiation tokens.
defined in Section 4.2.
The use of partially-established contexts (as indicated by the Lastly, MIC tokens MAY be exchanged to ensure the authenticity of the
prot_ready_state in [RFC2743]), either for this mechanism or mechanism list as seen by the target.
mechanisms negotiated using this mechanism, is prohibited.
To avoid conflicts with the use of MIC tokens by SPNEGO,
partially-established contexts are not used for per-message calls:
the prot_ready_state [RFC2743] will be false even if the underlying
mechanism would return true natively.
3.2 Negotiation Procedure 3.2 Negotiation Procedure
The negotiation procedure is summarized as follows: The basic form of the procedure assumes that per-message integrity
services are available on the established mechanism context, and it
is summarized as follows:
(a) The GSS-API initiator invokes GSS_Init_sec_context() as normal, (a) The GSS-API initiator invokes GSS_Init_sec_context() as normal,
but requests (either explicitly, with the negotiation mechanism, but requests (either explicitly, with the negotiation mechanism,
or through accepting a default, when the default is the or through accepting a default, when the default is this
negotiation mechanism) that the Simple and Protected GSS-API negotiation mechanism) that SPNEGO is used.
Negotiation Mechanism is used;
(b) The initiator GSS-API implementation emits a negotiation token (b) The initiator GSS-API implementation emits a negotiation token
containing a list of supported security mechanisms for the containing a list of supported security mechanisms (possible just
credentials used for this context establishment, and OPTIONALLY an one mechanism) for the credentials used for this context
initial security token for the first mechanism from that list establishment, and optionally an initial security token for the
(i.e. the preferred mechanism), and indicates first mechanism from that list.
GSS_S_CONTINUE_NEEDED status;
(c) The GSS-API initiator application sends the token to the target (c) The GSS-API initiator application sends the token to the target
application; application. The GSS-API target application deposits the token
through invoking GSS_Accept_sec_context(). The acceptor will do
(d) The GSS-API target application deposits the token through one of the following:
invoking GSS_Accept_sec_context. The target GSS-API application
will do one of the following:
(I) If the initiator's preferred mechanism is accepted by the
target, an initial token is included in the first token from
the initiator, no further mechanism token from the initiator is
needed for the chosen mechanism to establish the security
context, (e.g. when the authentication mechanism is unilateral
or mutual authentication has been performed and involves a
single token in either direction), and the initiator has not
sent a MIC token (the output token of the GSS_GetMIC() call
[RFC2743], the input to GSS_GetMIC() is the OTCET STRING field
representing the MechTypes in the initial NegTokenInit token),
of the mechanism list, the acceptor will do one of the
following:
1) If the initiator's preferred mechanism is accepted and there
is no policy on the target such that a different mechanism
other than the initiator's preferred mechanism could have
been selected given a different list of mechanisms,
GSS_Accept_sec_context() MUST indicate GSS_S_COMPLETE and it
MUST produce a negotiation token with the accept_completed
state, and with no MIC of the mechanism list. This is
referred in this document as the Safe to Omit MIC (SOMIC)
rule number 1. The resulting negotiation token MUST include
the security token if one is returned by the selected
mechanism;
2) If the initiator's preferred mechanism is accepted and there
is policy exists on the target such that a different
mechanism other than the initiator's preferred mechanism
could have been selected given a different list of
mechanisms, GSS_Accept_sec_context() MUST indicate
GSS_S_CONTINUE_NEEDED with the accept_incomplete state, and
a MIC MUST be generated by the target. This MIC is to be
verified by the initiator and the result will be sent back
to the acceptor. This is referred in this document as the
Safe to Omit MIC (SOMIC) rule number 2. The resulting
negotiation token MUST include the security token if one is
returned by the selected mechanism.
3) If there is a MIC token and it is correct,
GSS_Accept_sec_context() MUST indicate GSS_S_COMPLETE with
no output token; If there is an incorrect MIC token,
GSS_Accept_sec_context() must indicate GSS_S_BAD_MIC status,
OPTIONALLY returning a negotiation token with the reject
state.
(II) If the initiator's preferred mechanism is accepted, and an
initial token from this mechanism is sent by the initiator, but
a failure is returned by the chosen mechanism,
GSS_Accept_sec_context() MUST report the failure and the
mech_type output parameter indicates the selected mechanism.
The target MUST produce a negotiation token with the reject
state if the selected mechanism returns a response token (e.g.
a KRB_ERROR when the Kerberos Version 5 GSS-API mechanism is
chosen [GSSAPICFX]);
(III) If the initiator's preferred mechanism is accepted, and an
initial token from this mechanism is sent by the initiator, but
at last one more initiator token need to be transferred to
establish the context, GSS_Accept_sec_context() MUST indicate
GSS_S_CONTINUE_NEEDED status, returning a negotiation token
with the accept_incomplete state, the response mechanism token,
and no MIC token.
(IV) If the initiator's preferred mechanism is accepted, but no
initial token from this mechanism is sent by the initiator,
GSS_Accept_sec_context() MUST indicate GSS_S_CONTINUE_NEEDED
status, returning a negotiation token with the
accept_incomplete state, the selected mechanism, no response
mechanism token or MIC token.
(V) If a proposed mechanism is accepted, and it is not the
initiator's preferred mechanism, GSS_Accept_sec_context() MUST
indicate GSS_S_CONTINUE_NEEDED status, returning a negotiation
token with the accept_incomplete state, the selected mechanism,
no response mechanism token or MIC token. The negotiation will
be the agreed security mechanism if the negotiation is
successful.
(e) The GSS-API target application returns the negotiation token to
the initiator application;
(f) The GSS-API initiator application deposits the token through
invoking GSS_Init_sec_context(). The initiator will do one of the
following:
(I) When the negotiation token carries an accept_completed result,
the initiator MUST do one of the following:
1) If the selected mechanism is the initiator's preferred
mechanism, the initiator SHALL NOT reject the negotiation if
no MIC token is present. This is referred in this document
as the Safe to Omit MIC ("SOMIC") rule number 3. The
initiator MUST deposit the security token if one is
included, GSS_Init_sec_context() MUST indicate
GSS_S_BAD_MECH status if the context is not established
after this GSS_Init_sec_context() call. If a MIC token is
present, the initiator MUST verify it and a GSS_S_BAD_MIC
must be returned if the MIC is incorrect;
2) If the selected mechanism is not the initiator's preferred
mechanism, and there is no or an incorrect MIC token,
GSS_Init_sec_context() MUST indicate GSS_S_BAD_MIC status.
This is referred in this document as the Safe to Omit MIC
("SOMIC") rule number 4.
(II) When the negotiation token carries a reject result without a
response security token, GSS_Init_sec_context() MUST indicate
GSS_S_BAD_MECH status;
(III) When the negotiation token carries a reject result with a
response security token, the initiator MUST deposit the
security token, and GSS_Init_sec_context() MUST indicate a
failure status reported by the underlying mechanism, and the
output mech_type indicates the selected mechanism;
(IV) When the negotiation token carries an accept_incomplete (I) No proposed mechanism is acceptable, the negotiation SHALL be
result and further mechanism tokens from the acceptor must be terminated. GSS_Accept_sec_context indicates GSS_S_BAD_MECH.
transferred in order to complete context establishment, The acceptor MAY output a negotiation token containing a reject
GSS_Init_sec_context() MUST indicate GSS_S_CONTINUE_NEEDED state.
status, returning an output token with the accept_incomplete,
and the selected mechanism's context level token;
(V) When the negotiation token carries an accept_incomplete (II) If either the initiator's preferred mechanism is not accepted
result, no further mechanism token need to be transferred from by the target, or this mechanism is accepted but it is not the
the acceptor to complete the context establishment, the most preferred mechanism available for the acceptor (see
initiator MUST do one of the following: Section 3.1 and Section 5), GSS_Accept_sec_context() indicates
GSS_S_CONTINUE_NEEDED. The acceptor MUST output a negotiation
token containing a request_mic state.
1) If a MIC token was included, the initiator MUST verify it (III) Otherwise, GSS_Accept_sec_conext() indicates GSS_S_COMPLETE
and GSS_Init_sec_context() MUST indicate GSS_S_BAD_MIC if or GSS_S_CONTINUE_NEEDED, depending on if at least one
the MIC is incorrect; GSS_Init_sec_context() MUST indicate additional negotiation token from the initiator is needed to
GSS_S_COMPLETE and produce a negotiation with the establish this context. The acceptor outputs a negotiation
accept_completed state if the MIC is correct. This is token containing an accept_complete or accept_incomplete state,
referred in this document as the Safe to Omit MIC ("SOMIC") respectively.
rule number 5;
2) If no MIC token was present, GSS_Init_sec_context() MUST If the initiator's preferred mechanism is accepted, and an
indicate GSS_S_BAD_MIC statue, This is referred in this optimistic mechanism token was included, this mechanism token MUST
document as the Safe to Omit MIC ("SOMIC") rule number 6. be deposited to the selected mechanism through invoking
GSS_Accept_sec_context() and if a response mechanism token is
emitted, it MUST be included in the response negotiation token.
Otherwise, the target will not emit a response mechanism token in
the first reply.
(g) The initiator application then sends the output_token to the (d) The GSS-API target application returns the negotiation token to
target if one is returned. The security context initialization is the initiator application. The GSS-API initiator application
then continued according to the standard GSS-API conventions for deposits the token through invoking GSS_Init_sec_context(). The
the selected mechanism, where the tokens of the selected mechanism security context initialization is then continued according to the
are encapsulated until the GSS_S_COMPLETE is returned for both the standard GSS-API conventions for the selected mechanism, where the
initiator and the target. When no further mechanism token is tokens of the selected mechanism are encapsulated until the
needed to be transferred and the context for the chosen mechanism GSS_S_COMPLETE is returned for both the initiator and the target
is established, the initiator and the acceptor will need to either by the selected security mechanism.
apply the "SOMIC" rules above and skip MIC generation and
verification, or generate and verify the MIC token to protect the
negotiation.
(h) When GSS_S_CONTINUE_NEEDED is returned, the mech_type output (e) MIC tokens are then either skipped or exchanged according to
parameter is not yet valid. When GSS_S_COMPLETE is returned, the Section 5.
mech_type output parameter indicates the selected mechanism.
Note that the *_req_flag input parameters for context establishment Note that the *_req_flag input parameters for context establishment
are relative to the selected mechanism, as are the *_state output are relative to the selected mechanism, as are the *_state output
parameters. i.e., these parameters are not applicable to the parameters. i.e., these parameters are not applicable to the
negotiation process per se. negotiation process per se.
On receipt of a negotiation token on the target side, a GSS-API On receipt of a negotiation token on the target side, a GSS-API
implementation that does not support negotiation would indicate the implementation that does not support negotiation would indicate the
GSS_S_BAD_MECH status as if a particular basic security mechanism had GSS_S_BAD_MECH status as if a particular basic security mechanism had
been requested but was not supported. been requested but was not supported.
When GSS_Acquire_cred is invoked with the negotiation mechanism as When GSS_Acquire_cred is invoked with this SPNEGO mechanism as
desired_mechs, an implementation-specific default credential is used desired_mechs, an implementation-specific default credential is used
to carry on the negotiation. A set of mechanisms as specified to carry on the negotiation. A set of mechanisms as specified
locally by the system administrator is then available for locally by the system administrator is then available for
negotiation. If there is a desire for the caller to make its own negotiation. If there is a desire for the caller to make its own
choice, then an additional API has to be used as defined in [PRTSTK]. choice, then an additional API has to be used (see Appendix A).
4. Data Elements 4. Token Definitions
The type definitions in this section assume an ASN.1 module The type definitions in this section assume an ASN.1 module
definition of the following form: definition of the following form:
SPNEGOASNOneSpec { SPNEGOASNOneSpec {
iso(1) identified-organization(3) dod(6) internet(1) iso(1) identified-organization(3) dod(6) internet(1)
security(5) mechanism(5) snego (2) security(5) mechanism(5) snego (2) modules(4) spec2(2)
} DEFINITIONS EXPLICIT TAGS ::= BEGIN } DEFINITIONS EXPLICIT TAGS ::= BEGIN
-- rest of definitions here -- rest of definitions here
END END
This specifies that the tagging context for the module will be This specifies that the tagging context for the module will be
explicit and non-automatic. explicit and non-automatic.
The encoding of SPNEGO protocol messages shall obey the Distinguished The encoding of SPNEGO protocol messages shall obey the Distinguished
Encoding Rules (DER) of ASN.1 as described in [X690]. Encoding Rules (DER) of ASN.1 as described in [X690].
4.1 Mechanism Type 4.1 Mechanism Types
MechType ::= OBJECT IDENTIFIER In this negotiation model, each OID represents one GSS-API mechanism
-- OID represents each security mechanism as suggested by or one variant of it according to [RFC2743].
-- [RFC2743]
MechType ::= OBJECT IDENTIFIER
-- OID represents each security mechanism as suggested by
-- [RFC2743]
MechTypeList ::= SEQUENCE OF MechType
4.2 Negotiation Tokens 4.2 Negotiation Tokens
The syntax of the initial negotiation tokens follows the The syntax of the initial negotiation tokens follows the
InitialContextToken syntax defined in [RFC2743]. The security initialContextToken syntax defined in Section 3.1 of [RFC2743]. The
mechanism of the initial negotiation token is identified by the SPNEGO pseudo mechanism is identified by the Object Identifier
Object Identifier in Section 1. All subsequent tokens are not specified in Section 1. Subsequent tokens are not encapsulated in
encapsulated in the above generic token framing. this GSS-API generic token framing.
This section specifies the syntax of initial and subsequent context
level tokens.
NegotiationToken ::= CHOICE { This section specifies the syntax of the inner token for the initial
negTokenInit [0] NegTokenInit, message, and the syntax of subsequent context establishment tokens.
negTokenResp [1] negTokenResp
}
MechTypeList ::= SEQUENCE OF MechType NegotiationToken ::= CHOICE {
negTokenInit [0] NegTokenInit,
negTokenResp [1] negTokenResp
}
4.2.1 negTokenInit 4.2.1 negTokenInit
NegTokenInit ::= SEQUENCE { NegTokenInit ::= SEQUENCE {
mechTypes [0] MechTypeList, mechTypes [0] MechTypeList,
reqFlags [1] ContextFlags OPTIONAL, reqFlags [1] ContextFlags OPTIONAL,
mechToken [2] OCTET STRING OPTIONAL, mechToken [2] OCTET STRING OPTIONAL,
mechListMIC [3] OCTET STRING OPTIONAL, mechListMIC [3] OCTET STRING OPTIONAL,
... ...
} }
ContextFlags ::= BIT STRING {
ContextFlags ::= BIT STRING { delegFlag (0),
delegFlag (0), mutualFlag (1),
mutualFlag (1), replayFlag (2),
replayFlag (2), sequenceFlag (3),
sequenceFlag (3), anonFlag (4),
anonFlag (4), confFlag (5),
confFlag (5), integFlag (6)
integFlag (6) }
}
This is the message for the initial negotiation token. This is the syntax for the inner token of the initial negotiation
message.
mechTypes mechTypes
This field contains one or more security mechanisms in the This field contains one or more security mechanisms available
preference order (favorite choice first) supported by the for the initiator in preference order (favorite choice first).
initiator (as indicated in the field mechTypes).
reqFlags reqFlags
This field, if present, contains the service options that are This field, if present, contains the service options that are
requested to establish the context. The context flags SHOULD requested to establish the context. The context flags SHOULD
be filled in from the req_flags parameter of be filled in from the req_flags parameter of
GSS_Init_sec_context(). This field SHALL NOT influence the GSS_Init_sec_context(). This field SHALL NOT have impact on
outcome of the negotiation. the negotiation.
mechToken mechToken
This field, is present, contains an optimistic negotiation This field, is present, contains the optimistic security
response. mechanism token.
mechListMIC mechlistMIC
This field, if present, contains the result of a GSS_GetMIC() This field, is present, contains a MIC token, which is computed
[RFC2743] of the MechTypes field in the initial NegTokenInit according to Section 5, for the mechanism list in the initial
token. It allows verifying that the list initially sent by the negotiation message.
initiator has been received unmodified by the target.
4.2.2 negTokenResp 4.2.2 negTokenResp
NegTokenResp ::= SEQUENCE { NegTokenResp ::= SEQUENCE {
negResult [0] ENUMERATED { negResult [0] ENUMERATED {
accept_completed (0), accept_completed (0),
accept_incomplete (1), accept_incomplete (1),
reject (2) reject (2),
}, request_mic (3)
supportedMech [1] MechType OPTIONAL, },
responseToken [2] OCTET STRING OPTIONAL, supportedMech [1] MechType OPTIONAL,
mechListMIC [3] OCTET STRING OPTIONAL, responseToken [2] OCTET STRING OPTIONAL,
-- used only by the acceptor mechListMIC [3] OCTET STRING OPTIONAL,
... ...
} }
This is the message for all the subsequent tokens. This is the syntax for all subsequent negotiation messages.
negResult negResult
Result of the negotiation exchange, specified by the target. This field contains the state of the negotiation. This can be:
This can be:
accept_completed accept_completed
A security mechanism is selected, and the context is No further negotiation message from the peer is expected,
established for the sender; and the security context is established for the sender.
accept_incomplete accept_incomplete
Further exchanges are necessary; At least one more negotiation message from the peer is
needed to establish the security context.
reject reject
The sender reject the proposed security mechanism(s). The sender terminates the negotiation.
accept_completed indicates that a context has been successfully request_mic
established, while the result accept_incomplete indicates that The sender indicates that the exchange of MIC tokens, as
additional token exchanges are needed. described in Section 5, will be REQUIRED if per-message
integrity services are available on the mechanism context to
be established. This value SHALL only be present in the
first reply from the target.
For those targets that support piggybacking the initial supportedMech
mechToken, an optimistic negotiation response is possible and
includes in that case a responseToken which MAY continue the
authentication exchange (e.g. when mutual authentication has
been requested or when unilateral authentication requires
several round trips). Otherwise the responseToken is used to
carry the tokens specific to the mechanism selected.
The mechListMIC, when present, is a MIC computed over the This field SHALL only be present in the first reply from the
MechTypes using the mechanism list field in the initial token target. It is a choice from the mechanism(s) offered by the
(encoded in DER). initiator.
supportedMech ResponseToken
This field is present and only present in the first The field, if present, contains tokens specific to the
negTokenResp token. It is a choice from the mechanisms offered mechanism selected.
by the initiator.
responseToken mechlistMIC
This field, if present, contains the security token of the This field, is present, contains a MIC token, which is computed
selected mechanism. according to Section 5, for the mechanism list in the initial
negotiation message.
mechListMIC 5. Processing of mechListMIC
This field, if present, contains the result of a GSS_GetMIC() If the mechanism selected by the negotiation does not support
[RFC2743] of the MechTypes field in the initial NegTokenInit integrity protection, then no mechlistMIC token is used. Otherwise
token. It allows verifying that the list initially sent by the if the initiator's preferred mechanism is accepted and it is also the
initiator has been received unmodified by the target. most preferred mechanism available for the acceptor (there is no
mechanism which, had it been present in the mechanism list, the
acceptor would have preferred over the accepted mechanism), then the
MIC token exchange, as described later in this section, is OPTIONAL.
In all other cases, MIC tokens MUST be exchanged after the mechanism
context is fully established.
5. Security Considerations It is assumed that per-message integrity services are available on
the established mechanism context in the following procedure for
processing MIC tokens of the initiator's mechanism list.
In order to produce the MIC for the mechanism list, the mechanism a) The mechlistMIC token (or simply the MIC token) is computed
MUST provide integirty protection. When one of the mechanisms through invoking GSS_GetMIC(): the input context_handle is the
proposed by the initiator does not support integrity protection, then established mechanism context, the input qop_req is 0, and the
the negotiation is exposed to all threats a non secured service is input message is the mechTypes field in the initial negotiation
exposed. In particular, an active attacker can force to use a message (only the "value" portion, omitting the tag and length, of
security mechanism which is not the common preferred one (when the ASN.1 encoding for that field is included).
multiple security mechanisms are shared between peers) but which is
acceptable anyway to the target, thus this mechanism does not support
selecting a mechanism that does not support integrity protection.
In any case, the communicating peers MAY be exposed to the denial of b) If the selected mechanism uses an even number of mechanism tokens
(namely the acceptor sends the last mechanism token), the acceptor
does the following when emitting the negotiation message
containing the last mechanism token: if the MIC token exchange is
not required, GSS_Accept_sec_context() either indicates
GSS_S_COMPLETE and does not include a mechlistMIC token, or
indicates GSS_S_CONTINUE_NEEDED and includes a mechlistMIC token
and an accept_incomplete state; if the MIC token exchange is
required, GSS_Accept_sec_context() indicates
GSS_S_CONTINUE_NEEDED, and includes a mechlistMIC token.
Acceptors who wish to be compatible with legacy Windows SPNEGO
implementations as described in Appendix B shall not generate a
mechlistMIC token when the MIC token exchange is not required.
The initiator then processes the last mechanism token, and does
one of the following:
(I) If a mechlistMIC token was included, and is correctly
verified, GSS_Init_sec_context() indicates GSS_S_COMPLETE. The
output negotiation message contains a mechlistMIC token, and an
accept_complete state. The acceptor MUST then verify this
mechlistMIC token.
(II) If a mechlistMIC token was included but is incorrect, the
negotiation SHALL be terminated. GSS_Accept_sec_context()
indicates GSS_S_DEFECTIVE_TOKEN.
(III) If no mechlistMIC token was included, and the MIC token
exchange is not required, GSS_Init_sec_context() indicates
GSS_S_COMPLETE with no output token.
(IV) If no mechlistMIC token was included, but the MIC token
exchange is required, the negotiation SHALL be terminated.
GSS_Accept_sec_context() indicates GSS_S_DEFECTIVE_TOKEN.
c) In the case that the chosen mechanism uses an odd number of
mechanism tokens (namely the initiator sends the last mechanism
token), the initiator does the following when emitting the
negotiation message containing the last mechanism token: if the
negResult state was request_mic in the first reply from the
target, a mechlistMIC token MUST be included, otherwise the
mechlistMIC token is OPTIONAL. GSS_Init_sec_context() indicates
GSS_S_CONTINUE_NEEDED. Initiators who wish to be compatible with
legacy Windows SPNEGO implementations as described in Appendix B
shall not generate a mechlistMIC token when the MIC token exchange
is not required. The acceptor then processes the last mechanism
token, and does one of the following:
(I) If a mechlistMIC token was included, and is correctly
verified, GSS_Accept_sec_context() indicates GSS_S_COMPLETE.
The output negotiation message contains a mechlistMIC token,
and an accept_complete state. The initiator MUST then verify
this mechlistMIC token.
(II) If a mechlistMIC token was included but is incorrect, the
negotiation SHALL be terminated. GSS_Accept_sec_context()
indicates GSS_S_DEFECTIVE_TOKEN.
(III) If no mechlistMIC token was included and the mechlistMIC
token exchange is not required, GSS_Accept_sec_context()
indicates GSS_S_COMPLETE. The output negotiation message
contains an accept_complete state.
(IV) If no mechlistMIC token was included and the acceptor sent a
request_mic state in the first reply message (the exchange of
MIC tokens is required), the negotiation SHALL be terminated.
GSS_Accept_sec_context() indicates GSS_S_DEFECTIVE_TOKEN.
6. Extensibility
Two mechanisms are provided by extensibility. First, the ASN.1
structures in this specification MAY be expanded by IETF standards
action. Implementations receiving unknown fields MUST ignore these
fields.
Secondly, OIDs corresponding to a desired mechanism attribute may be
included in the set of preferred mechanisms by an initiator. The
acceptor can choose to honor this request by preferring mechanisms
that have that attribute. Future work within the Kitten working
group is expected to standardize common attributes that SPNEGO
mechanisms may wish to support. At this time it is sufficient to say
that initiators MAY include OIDs that do not correspond to mechanisms
but instead correspond to desired mechanism attributes in their
requests. Such OIDs MAY influence the acceptor's choice of
mechanism. As discussed in Section 5, if there are mechanisms that
if present in the initiator's list of mechanisms might be preferred
by the acceptor to the initiator's preferred mechanism, the acceptor
MUST demand the MIC token exchange. As a consequence, acceptors MUST
demand the MIC token exchange if they support negotiation of
attributes not available in the initiator's preferred mechanism
regardless of whether the initiator actually requested these
attributes.
7. Security Considerations
In order to produce the MIC token for the mechanism list, the
mechanism must provide integrity protection. When the selected
mechanism does not support integrity protection, then the negotiation
is vulnerable: an active attacker can force it to use a security
mechanism that is not mutually preferred but is acceptable anyway to
the target.
When per-message integrity services are available on the established
mechanism context, and there was an alteration of the mechanism list
by an adversary such that a common mechanism that is not mutually
preferred could be selected, this protocol provides the following
guarantees: if the last mechanism token is sent by the initiator,
both peers shall fail; if the last mechanism token is sent by the
acceptor, the acceptor shall not complete and the initiator at worst
shall complete with its preferred mechanism being selected. The
negotiation may not be terminated if an alteration was made but it
had no material impact.
The protection of the negotiation depends on the strength of the
integrity protection. In particular, the strength of SPNEGO is no
stronger than the integrity protection of the weakest mechanism
acceptable to GSS-API peers.
In all cases, the communicating peers are exposed to the denial of
service threat. service threat.
6. Acknowledgments 8. Acknowledgments
The authors wish to thank Paul Leach and Todd Stecher for theirs The authors wish to thank Nicolas Williams, Ken Raeburn, Jeff Altman,
comments and suggestions on earlier versions of this document. Cristian Ilac and Martin Rex for their comments and suggestions on
earlier versions of this document.
Eric Baize and Denis Pinkas wrote the original SPNEGO specification Eric Baize and Denis Pinkas wrote the original SPNEGO specification
[RFC2478], of which some of the text has been retained in this [RFC2478], of which some of the text has been retained in this
document. document.
7 References 9 References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2478] Baize, E. and D. Pinkas, "The Simple and Protected GSS-API [RFC2478] Baize, E. and D. Pinkas, "The Simple and Protected GSS-API
Negotiation Mechanism", RFC 2478, December 1998. Negotiation Mechanism", RFC 2478, December 1998.
[RFC2743] Linn, J., "Generic Security Service Application Program [RFC2743] Linn, J., "Generic Security Service Application Program
Interface Version 2, Update 1", RFC 2743, January 2000. Interface Version 2, Update 1", RFC 2743, January 2000.
[PRTSTK] RFC-Editor: To be replaced by RFC number for draft-williams
-gssapi-stackable-pseudo-mechs. Work in progress.
[X690] ASN.1 encoding rules: Specification of Basic Encoding Rules [X690] ASN.1 encoding rules: Specification of Basic Encoding Rules
(BER), Canonical Encoding Rules (CER) and Distinguished (BER), Canonical Encoding Rules (CER) and Distinguished
Encoding Rules (DER), ITU-T Recommendation X.690 (1997) | Encoding Rules (DER), ITU-T Recommendation X.690 (1997) |
ISO/IEC International Standard 8825-1:1998. ISO/IEC International Standard 8825-1:1998.
Authors' Addresses Authors' Addresses
Larry Zhu Larry Zhu
Microsoft Corporation Microsoft Corporation
One Microsoft Way One Microsoft Way
Redmond, WA 98052 Redmond, WA 98052
US US
EMail: lzhu@microsoft.com EMail: lzhu@microsoft.com
Karthik Jaganathan Paul Leach
Microsoft Corporation Microsoft Corporation
One Microsoft Way One Microsoft Way
Redmond, WA 98052 Redmond, WA 98052
US US
EMail: karthikj@microsoft.com EMail: paulle@microsoft.com
Karthik Jaganathan
Richard B. Ward
Microsoft Corporation Microsoft Corporation
One Microsoft Way One Microsoft Way
Redmond, WA 98052 Redmond, WA 98052
US US
EMail: richardw@microsoft.com EMail: karthikj@microsoft.com
Appendix A. Changes since RFC2478 Sam Hartman
Massachusetts Institute of Technology
77 Massachusetts Avenue
Cambridge, MA 02139
US
The following changes are designed to be compatible with an EMail: hartmans@mit.edu
incorrect implementation of RFC 2478 shipped in Windows 2000. A
correct implementation of this protocol that negotiates the 2 leg
Kerberos GSS-API mechanism as the only available security
mechanism should be ale to interoperate with the implementation of
Windows 2000 when the mangled OID (1.2.840.48018.1.2.2) can be
used to identify Kerberos.
* The negTokenTarg is changed to negTokenResp and it is now the Wyllys Ingersoll
format for all subsequent negotiation messages. Sun Microsystems
* negTokenInit is the message for the initial token and that 1775 Wiehle Avenue, 2nd Floor
Reston, VA 20190
US
EMail: wyllys.ingersoll@sun.com
Appendix A. GSS-API Negotiation Support API
In order to provide to a GSS-API caller (either the initiator or the
target or both) the ability to choose among the set of supported
mechanisms a reduced set of mechanisms for negotiation, two
additional APIs are defined:
o GSS_Get_neg_mechs() indicates the set of security mechanisms
available on the local system to the caller for negotiation, based
on the credentials being used.
o GSS_Set_neg_mechs() specifies the set of security mechanisms to be
used on the local system by the caller for negotiation, for the
given credentials.
A.1 GSS_Set_neg_mechs call
Inputs:
o cred_handle CREDENTIAL HANDLE, -- NULL specifies default
-- credentials
o mech_set SET OF OBJECT IDENTIFIER
Outputs:
o major_status INTEGER,
o minor_status INTEGER
Return major_status codes:
o GSS_S_COMPLETE indicates that the set of security mechanisms
available for negotiation has been set to mech_set.
o GSS_S_FAILURE indicates that the requested operation could not be
performed for reasons unspecified at the GSS-API level.
Allows callers to specify the set of security mechanisms that may be
negotiated with the credential identified by cred_handle. This call
is intended for support of specialized callers who need to restrict
the set of negotiable security mechanisms from the set of all
security mechanisms available to the caller (based on available
credentials). Note that if more than one mechanism is specified in
mech_set, the order in which those mechanisms are specified implies a
relative preference.
A.2 GSS_Get_neg_mechs call
Input:
o cred_handle CREDENTIAL HANDLE -- NULL specifies default
-- credentials
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o mech_set SET OF OBJECT IDENTIFIER
Return major_status codes:
o GSS_S_COMPLETE indicates that the set of security mechanisms
available for negotiation has been returned in mech_set.
o GSS_S_FAILURE indicates that the requested operation could not be
performed for reasons unspecified at the GSS-API level.
Allows callers to determine the set of security mechanisms available
for negotiation with the credential identified by cred_handle. This
call is intended for support of specialized callers who need to
reduce the set of negotiable security mechanisms from the set of
supported security mechanisms available to the caller (based on
available credentials).
Note: The GSS_Indicate_mechs() function indicates the full set of
mechanism types available on the local system. Since this call has
no input parameter, the returned set is not necessarily available for
all credentials.
Appendix B. Changes since RFC2478
SPNEGO implementations in Windows 2000/Windows XP/Windows Server
2003 have the following behavior: no mechlistMIC is produced, and
mechlistMIC is not processed if one is provided; if the initiator
sends the last mechanism token, the acceptor will send back a
negotiation token with an accept_complete state and no mechlistMIC
token. In addition, the OID (1.2.840.48018.1.2.2) can be used to
identify the GSS-API Kerberos Version 5 mechanism.
The following changes have been made to be compatible with these
legacy implementations.
* NegTokenTarg is changed to negTokenResp and it is the message
format for all subsequent negotiation tokens.
* NegTokenInit is the message for the initial token and that
token only. token only.
* mechTypes in negTokenInit is no longer optional. * mechTypes in negTokenInit is not optional.
* negResult is no longer optional in the negTokenResp token. * negResult is not optional in the negTokenResp token.
* The initiator does not send the MIC token. * Two MIC tokens are exchanged, one in each direction.
* Add rules when it is safe to omit the MIC token. Search for * If the selected mechanism is also the most preferred mechanism
SOMIC. for both peers, it is safe to omit the MIC tokens.
If at least one of the two peers implements the pseudo mechanism
in this document, the negotiation is protected.
The following changes are to address the problems in RFC 2478. The following changes are to address the problems in RFC 2478.
* reqFlags is not protected therefore it should not impact the * reqFlags is not protected therefore it should not impact the
negotiation. negotiation.
* BER encoding is required. * DER encoding is required.
* GSS_GetMIC() input is clarified. * GSS_GetMIC() input is clarified.
* Nico's stackable pseudo mechanism draft is used to replace the * Per-message integrity services are requested for the negotiated
support APIs. mechanism.
* We no longer support negotiating mechanisms that do not provide
for integrity. That support does not add security values but
blows up the interoperability test matrix.
Intellectual Property Statement Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be on the procedures with respect to rights in RFC documents can be
 End of changes. 79 change blocks. 
396 lines changed or deleted 516 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/