idnits 2.17.1 draft-zhu-negoex-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC4178, but the abstract doesn't seem to directly say this. It does mention RFC4178 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC4178, updated by this document, for RFC5378 checks: 2004-11-29) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 3, 2011) is 4862 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '32' on line 979 == Unused Reference: 'RFC4120' is defined on line 880, but no explicit reference was found in the text Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETWORK WORKING GROUP M. Short 3 Internet-Draft L. Zhu 4 Updates: 4178 (if approved) K. Damour 5 Intended status: Standards Track D. McPherson 6 Expires: July 7, 2011 Microsoft Corporation 7 January 3, 2011 9 SPNEGO Extended Negotiation (NEGOEX) Security Mechanism 10 draft-zhu-negoex-04 12 Abstract 14 This document defines the SPNEGO Extended Negotiation (NEGOEX) 15 Security Mechanism. NEGOEX enhances the capabilities of SPNEGO by 16 providing a security mechanism which can be negotiated by the SPNEGO 17 protocol as defined in RFC4178. 19 The NEGOEX protocol itself is a security mechanism negotiated by 20 SPNEGO. When the NEGOEX security mechanism is selected by SPNEGO, 21 NEGOEX provides a method allowing selection of a common 22 authentication protocol based on factors beyond just the fact that 23 both client and server support a given security mechanism. NEGOEX 24 OPTIONALLY adds a pair of meta-data messages for each negotiated 25 security mechanism. The meta-data exchange allows security 26 mechanisms to exchange auxiliary information such as trust 27 configurations, thus NEGOEX provides more flexibility than just 28 exchanging security mechanism OIDs in SPNEGO. 30 NEGOEX preserves the optimistic token semantics of SPNEGO and applies 31 that recursively. Consequently a context establishment mechanism 32 token can be included in the initial NEGOEX message, and NEGOEX does 33 not require an extra round-trip when the initiator's optimistic token 34 is accepted by the target. 36 Similar to SPNEGO, NEGOEX defines a few new GSS-API extensions that a 37 security mechanism MUST support in order to be negotiated by NEGOEX. 38 This document defines these GSS-API extensions. 40 Unlike SPNEGO however, NEGOEX defines its own way for signing the 41 protocol messages in order to protect the protocol negotiation. The 42 NEGOEX message signing or verification can occur before the security 43 context for the negotiated real security mechanism is fully 44 established. 46 Status of this Memo 48 This Internet-Draft is submitted in full conformance with the 49 provisions of BCP 78 and BCP 79. 51 Internet-Drafts are working documents of the Internet Engineering 52 Task Force (IETF). Note that other groups may also distribute 53 working documents as Internet-Drafts. The list of current Internet- 54 Drafts is at http://datatracker.ietf.org/drafts/current/. 56 Internet-Drafts are draft documents valid for a maximum of six months 57 and may be updated, replaced, or obsoleted by other documents at any 58 time. It is inappropriate to use Internet-Drafts as reference 59 material or to cite them other than as "work in progress." 61 This Internet-Draft will expire on July 7, 2011. 63 Copyright Notice 65 Copyright (c) 2011 IETF Trust and the persons identified as the 66 document authors. All rights reserved. 68 This document is subject to BCP 78 and the IETF Trust's Legal 69 Provisions Relating to IETF Documents 70 (http://trustee.ietf.org/license-info) in effect on the date of 71 publication of this document. Please review these documents 72 carefully, as they describe your rights and restrictions with respect 73 to this document. Code Components extracted from this document must 74 include Simplified BSD License text as described in Section 4.e of 75 the Trust Legal Provisions and are provided without warranty as 76 described in the Simplified BSD License. 78 Table of Contents 80 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 81 2. Requirements Terminology . . . . . . . . . . . . . . . . . . . 6 82 3. Presentation Language and Primitive Data Types . . . . . . . . 7 83 3.1. Basic Block Size . . . . . . . . . . . . . . . . . . . . . 7 84 3.2. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . 7 85 3.3. Constants . . . . . . . . . . . . . . . . . . . . . . . . 7 86 3.4. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 7 87 3.5. Enum Types . . . . . . . . . . . . . . . . . . . . . . . . 7 88 3.6. Typedef Declarations . . . . . . . . . . . . . . . . . . . 8 89 3.7. Array Types . . . . . . . . . . . . . . . . . . . . . . . 8 90 3.8. Constructed Types . . . . . . . . . . . . . . . . . . . . 8 91 4. Vector Types . . . . . . . . . . . . . . . . . . . . . . . . . 10 92 5. NEGOEX Messages . . . . . . . . . . . . . . . . . . . . . . . 11 93 6. Cryptographic Computations . . . . . . . . . . . . . . . . . . 12 94 7. The NEGOEX Protocol . . . . . . . . . . . . . . . . . . . . . 12 95 7.1. High-level NEGOEX Message Flow . . . . . . . . . . . . . . 12 96 7.2. NEGOEX Supported Security Mechanisms . . . . . . . . . . . 13 97 7.3. ConversationID . . . . . . . . . . . . . . . . . . . . . . 13 98 7.4. Generation of the Initiator Initial Token . . . . . . . . 13 99 7.5. Receipt of the Initial Initiator Token and Generation 100 of the Initial Acceptor Response . . . . . . . . . . . . . 15 101 7.6. Receipt of the Acceptor Initial Response and 102 Completion of Authentication after the Negotiation 103 Phrase . . . . . . . . . . . . . . . . . . . . . . . . . . 16 104 7.7. Finalizing Negotiation . . . . . . . . . . . . . . . . . . 16 105 8. Supporting GSS-API Extensions . . . . . . . . . . . . . . . . 17 106 8.1. GSS_Query_meta_data . . . . . . . . . . . . . . . . . . . 17 107 8.2. GSS_Exchange_meta_data . . . . . . . . . . . . . . . . . . 18 108 8.3. GSS_Query_mechanism_info . . . . . . . . . . . . . . . . . 19 109 8.4. GSS_Inquire_context . . . . . . . . . . . . . . . . . . . 19 110 9. Security Considerations . . . . . . . . . . . . . . . . . . . 19 111 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 20 112 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 113 12. Normative References . . . . . . . . . . . . . . . . . . . . . 20 114 Appendix A. Protocol Data Structures and Constant Values . . . . 20 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 24 117 1. Introduction 119 If more than one GSS-API mechanism is shared between the initator and 120 the acceptor, the Simple and Protected (GSS-API) Negotiation 121 Mechanism (SPNEGO) as defined in [RFC4178] can be deployed to choose 122 a mutually preferred one. This pseudo mechanism does well in the 123 most basic scenarios but suffers from a couple of drawbacks, notably: 125 o Since the SPNEGO negotiation is based on purely on exchanging 126 security mechanism OIDs, security mechanisms can be selected which 127 cannot successfully authenticate the initator. Just because an 128 initator and acceptor support the same security mechanism does not 129 mean that they have a mutually trusted authentication authority. 130 In such cases, the authentication will fail with the preferred 131 security mechanism, but might succeed with another common 132 mechanism. 134 o Secondly, the SPNEGO negotiation model is inadequate when the 135 choice cannot be made by the acceptor in the initial response. In 136 SPNEGO, the negotiation information is sent one-way from the 137 initiator for the acceptor to make a choice, and the acceptor must 138 choose one when it makes the initial response. This negotiation 139 model is counter intuitive. The selection of a security mechanism 140 is typically the result of selecting one type of credentials from 141 the available set, and the initiator typically does not wish to 142 reveal credentials information often associated with user 143 identities. In practice, in order to operate in this model, the 144 Kerberos GSS-API mechanism [RFC4121] must acquire the context 145 establishment token in the initial call to GSS_Init_sec_context(). 146 If the initiator fails to acquire the initial Kerberos GSS-API 147 context token, it must not offer Kerberos; otherwise the SPNEGO 148 context negotiation will fail without being able to select the 149 next available mechanism that could work. Obtaining the initial 150 Kerberos GSS-API context token may require multiple round-trips of 151 network calls and the cost of the operation can be substantial. 152 It is suboptimal when multiple GSS-API mechanisms have to add the 153 extra cost that would not exist if the negotiated security 154 mechanism were selected based on configuration. 156 The SPNEGO Extended Negotiation (NEGOEX) Security Mechanism is 157 designed to address these concerns. NEGOEX is a security mechanism 158 that is negotiated by SPNEGO, and when negotiated, it can recursively 159 negotiate other security mechanisms. 161 Any security mechanism negotiated by NEGOEX MUST support integrity 162 protection and addition GSS-API interfaces specified in Section 8. 164 The basic form of NEGOEX works as follows: 166 1. The initiator proposes a list of mechanisms in decreasing 167 preference order. For each of these mechanism, NEGOEX OPTIONALLY 168 includes a mechanism specific meta-data token. GSS-API 169 extensions are defined later in this document for NEGOEX to query 170 the meta-data token for inclusion in the NEGOEX message. 172 2. The acceptor then passes the meta-data token from the initiator 173 to the intended security mechanism. A meta-data token for a 174 security mechanism not supported on the acceptor side is ignored. 175 New GSS-API extensions are defined later in this document for a 176 security mechanism to consume the meta-data token. When 177 processing the received meta-data tokens, a security mechanism 178 that reports a failure is removed from the set of mutually 179 supported mechanisms. The acceptor then responds with the list 180 of mutually supported mechanisms in decreasing preference order. 181 For each of these mechanism, NEGOEX again OPTIONALLY supplies a 182 mechanism specific meta-data token in the response which it 183 obtains from each remaining supported mechanism via the new GSS- 184 API extensions described in the initial step. 186 3. The initiator then passes the meta-data tokens to the intended 187 security mechanisms by invoking the new GSS-API extensions. When 188 processing the received meta-data token, a security mechanism 189 that reports a failure is removed from the set of mutually 190 supported mechanisms for this negotiation context. The initiator 191 then selects one from the set of mutually-supported mechanisms. 192 If more than one security mechanism is available, unless 193 otherwise specified, the highest one in the acceptor's preference 194 order SHOULD be selected. Later when the common security 195 mechanism is identified, the security mechanism may also 196 negotiate mechanism-specific options during its context 197 establishments. This will be inside the mechanism tokens, and 198 invisible to the NEGOEX protocol during step 5. 200 4. The selected security mechanism provides keying materials to 201 NEGOEX via new GSS-API extensions which defined later in this 202 document. NEGOEX signs and verifies the negotiation NEGOEX 203 messages to protect the negotiation. 205 5. The initiator and the acceptor proceed to exchange tokens until 206 the GSS-API context for selected security mechanism is 207 established. Once the security context is established, the per- 208 message tokens are generated and verified in accordance with the 209 selected security mechanism. 211 NEGOEX does not work outside of SPNEGO. When negotiated by SPNEGO, 212 NEGOEX uses the concepts developed in the GSS-API specification 213 [RFC2743]. The negotiation data is encapsulated in context-level 214 tokens. Therefore, callers of the GSS-API do not need to be aware of 215 the existence of the negotiation tokens but only of the SPNEGO 216 pseudo-security mechanism. 218 In its basic form NEGOEX requires at least one extra round-trip. 219 Network connection setup is a critical performance characteristic of 220 any network infrastructure and extra round trips over WAN links, 221 packet radio networks, etc. really make a difference. In order to 222 avoid such an extra round trip the initial security token of the 223 preferred mechanism for the initiator may be embedded in the initial 224 NEGOEX token. The optimistic mechanism token may be accompanied by 225 the meta-data tokens and the optimistic mechanism token MUST be that 226 of the first mechanism in the list of the mechanisms proposed by the 227 initiator. The NEGOEX MESSAGE_TYPE_INITIATOR_NEGO message that 228 contains signatures for protecting the NEGOEX negotiation may also 229 accompany the optimistic mechanism token. If the target preferred 230 mechanism matches the initiator's preferred mechanism, and when the 231 NEGOEX negotiation protection messages are included along with the 232 mechanism token, no additional round trips are incurred by using the 233 NEGOEX protocol with SPNEGO. 235 NEGOEX does not update the ASN.1 structures of SPNEGO [RFC4178] 236 because a widely deployed SPNEGO implementation does not have the 237 ASN.1 extensibility marker in the message definition. There is no 238 change to the SPNEGO messages. 240 NEGOEX uses a C-like definition language to describe message formats. 242 The rest of the document is organized as follows: 244 o Section 3 defines the encoding of NEGOEX data structures and all 245 the primitive data types. 246 o Section 6 describes the cryptographic framework required by the 247 NEGOEX for protecting the NEGOEX negotiation. 248 o Section 7 defines the NEGOEX messages and the NEGOEX protocol. 249 o Section 8 defines the new GSS-API extensions that a security 250 mechanism MUST support in order to be negotiated by NEGOEX. 251 o Section 9 contains the security considerations for NEGOEX. 252 o Appendix A contains all the protocol constructs and constants. 254 2. Requirements Terminology 256 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 257 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 258 document are to be interpreted as described in [RFC2119]. 260 3. Presentation Language and Primitive Data Types 262 The following very basic and somewhat casually defined presentation 263 syntax will be used in all NEGOEX messages. Although it resembles 264 the programming language "C" in its syntax, it would be risky to draw 265 too many parallels. The purpose of this presentation language is to 266 document NEGOEX only; it has no general application beyond that 267 particular goal. 269 This section also defines all the primitive data types. The 270 semantics of the data types is explained in the next section. 272 3.1. Basic Block Size 274 The representation of all data items is explicitly specified. The 275 basic data block size is one octet. Multiple octet data items are 276 concatenations of octets, from left to right, from top to bottom 277 Unless otherwise specific a multi-octet numeric is in little endian 278 order with the least significant octet first. 280 3.2. Miscellaneous 282 Comments start with "//"' and continue until the end of the line. 284 3.3. Constants 286 Constants are denoted using "#define" followed by the symbolic name 287 and then the constant value. 289 3.4. Numbers 291 UCHAR is the data type for a one-octet number. 293 ULONG is the data type for a 4-octet number encoded in little endian. 295 USHORT is the data type for a 2-octet number encoded in little 296 endian. 298 ULONG64 is the data type for a 8-octet number encoded in little 299 endian. 301 GUID is the data type for a 16-octet number encoded in little endian. 303 3.5. Enum Types 305 An enum type is the data type for a number with a small number of 306 permissible values. An instance of an enum type is a 4-octet number 307 encoded in little endian. 309 The definition of an enum type follows the simple "C" convention. 311 MESSAGE_TYPE is an enum type defined as follows: 313 enum 314 { 315 MESSAGE_TYPE_INITIATOR_NEGO = 0, 316 MESSAGE_TYPE_ACCEPTOR_NEGO, 317 MESSAGE_TYPE_INITIATOR_META_DATA, 318 MESSAGE_TYPE_ACCEPTOR_META_DATA, 319 MESSAGE_TYPE_CHALLENGE, 320 // an exchange message from the acceptor 321 MESSAGE_TYPE_AP_REQUEST, 322 // an exchange message from the initiator 323 MESSAGE_TYPE_VERIFY, 324 MESSAGE_TYPE_ALERT, 325 } MESSAGE_TYPE; 327 MESSAGE_TYPE_INITIATOR_NEGO has the value 0, and MESSAGE_TYPE_ALERT 328 has the value 7. 330 3.6. Typedef Declarations 332 A typedef creates a synonym for the type. This is used to create 333 more meaningful names for existing types. 335 The following two type synonyms are defined. 337 typedef GUID AUTH_SCHEME; 338 typedef GUID CONVERSATION_ID; 340 3.7. Array Types 342 Arrays are a data structure which holds multiple variables of the 343 same data type consecutively and the number of elements is fixed. An 344 array is declared using "C" convention. The following defines an 345 array of 32 octets. 347 UCHAR Random[32]; 349 3.8. Constructed Types 351 Structure types may be constructed from primitive types for 352 convenience. Each specification declares a new, unique type. The 353 syntax for definition is much like that of C. 355 struct { 356 T1 f1; 357 T2 f2; 358 ... 359 Tn fn; 360 } T; 362 Structure definitions may be embedded. 364 The following types are defined as constructed types: 366 struct 367 { 368 ULONG ExtensionType; // negative extensions are critical 369 BYTE_VECTOR ExtensionValue; 370 } EXTENSION; 372 An extension has two fields. The ExtensionType field indicates how 373 the extension data should be interpreted. The ExtensionValue field 374 contains the extension data. 376 // 377 // schemes defined for the checksum in the VERIFY message 378 // 380 struct 381 { 382 ULONG cbHeaderLength; 383 ULONG ChecksumScheme; 384 ULONG ChecksumType; // in the case of RFC3961 scheme, this is 385 // the RFC3961 checksum type 386 BYTE_VECTOR ChecksumValue; 387 } CHECKSUM; 389 The CHECKSUM structure contains 4 fields. The cbHeaderLength length 390 contains the length of the structure defintion in octets, and this 391 field has a value of 20. 393 The ChecksumScheme field describes how checksum is computed and 394 verified. Currently only one value is defined. 396 #define CHECKSUM_SCHEME_RFC3961 1 398 When the value of the ChecksumScheme field is 1 399 (CHECKSUM_SCHEME_RFC3961), the ChecksumValue field contains a 400 sequence of octets computed according to [RFC3961] and the 401 ChecksumType field contains the checksum type value defined according 402 to [RFC3961]. 404 4. Vector Types 406 Vectors are a data structure which holds multiple variables of the 407 same data type consecutively and the number of elements is not fixed. 408 A vector contains a fixed length header followed by a variable length 409 payload. The header of a vector structure contains the count of 410 elements and the offset to the payload. In this document all the 411 offset fields are relative to the beginning of the containing NEGOEX 412 message. The size of each element is specified by the vector type 413 definition. 415 The following vector types are defined. 417 struct 418 { 419 ULONG ByteArrayOffset; // each element contains an octet/byte 420 ULONG ByteArrayLength; 421 } BYTE_VECTOR; 423 BYTE_VECTOR encapsulates a variable length array of octets (or bytes) 424 that are stored consecutively. Each element in is a byte (8 bits). 426 struct 427 { 428 ULONG AuthSchemeArrayOffset; 429 // each element contains an AUTH_SCHEME 430 USHORT AuthSchemeCount; 431 } AUTH_SCHEME_VECTOR; 433 AUTH_SCHEME_VECTOR encapsulates a variable length array of 434 AUTH_SCHEMEs that are stored consecutively. Each element is a 435 structure of the type AUTH_SCHEME. 437 struct 438 { 439 ULONG ExtensionArrayOffset; 440 // each element contains an EXTENSION 441 USHORT ExtensionCount; 442 } EXTENSION_VECTOR; 444 EXTENSION_VECTOR encapsulates a variable length array of EXTENSIONs 445 that are stored consecutively. Each element is a structure of the 446 type EXTENSION. 448 5. NEGOEX Messages 450 The following structure is the MESSAGE_HEADER: 452 struct 453 { 454 ULONG64 Signature; // contains MESSAGE_SIGNATURE 455 MESSAGE_TYPE MessageType; 456 ULONG SequenceNum; // the message sequence number of this, 457 // conversation, starting with 0 and sequentially 458 // incremented 459 ULONG cbHeaderLength; // the header length of this message, 460 // including the message specific header, excluding the 461 // payload 462 ULONG cbMessageLength; // the length of this message 463 CONVERSATION_ID ConversationId; 464 } MESSAGE_HEADER; 466 The following structure is the NEGO_MESSAGE: 468 struct 469 { 470 MESSAGE_HEADER Header; 471 // MESSAGE_TYPE_INITIATOR_NEGO for the initiator, 472 // MESSAGE_TYPE_ACCEPTOR_NEGO for the acceptor 473 UCHAR Random[32]; 474 ULONG64 ProtocolVersion; 475 // version of the protocol, this contains 0 476 AUTH_SCHEME_VECTOR AuthSchemes; 477 EXTENSION_VECTOR Extensions; 478 } NEGO_MESSAGE; 480 The following structure is the EXCHANGE_MESSAGE: 482 struct 483 { 484 MESSAGE_HEADER Header; 485 // MESSAGE_TYPE_CHALLENGE for the acceptor, 486 // or MESSAGE_TYPE_AP_REQUEST for the initiator 487 // MESSAGE_TYPE_INITIATOR_META_DATA for 488 // the initiator metadata 489 // MESSAGE_TYPE_ACCEPTOR_META_DATA for 490 // the acceptor metadata 491 AUTH_SCHEME AuthScheme; 492 BYTE_VECTOR Exchange; 493 // contains the opaque handshake message for the 494 // authentication scheme 495 } EXCHANGE_MESSAGE; 497 6. Cryptographic Computations 499 The message signing and verification in NEGOEX is based on [RFC3961]. 500 [RFC3961] is used here as a generic framework and this application is 501 not Kerberos specific. 503 A security mechanism MUST support [RFC3961] in order to be negotiated 504 by NEGOEX. 506 7. The NEGOEX Protocol 508 This section describes the NEGOEX protocol and it defines NEGOEX 509 messages in the order that the messages can appear on the wire. The 510 enum type MESSAGE_TYPE defined in Section 3.5 lists all NEGOEX 511 message types. A GSS-API context token for NEGOEX consists of one or 512 more NEGOEX messages. If there is more than one NEGOEX message, 513 these messages are concatenated together. The smallest data unit for 514 NEGOEX to compute the checksum for negotiation protection is s NEGOEX 515 message. Note that NEGOEX is not a GSS-API mechanism itself and the 516 initial NEGOEX context establishment token does not follow the 517 mechanism-independent token format defined in Section 3.1 of 518 [RFC2743]. 520 The object identifier of the NEGOEX within SPNEGO is iso(1) 521 identified-organization(3) dod(6) internet(1) private(4) 522 enterprise(1) microsoft (311) security(2) mechanisms(2) negoex(30). 524 7.1. High-level NEGOEX Message Flow 526 The following text art summarizes the protocol message flow: 528 Initiator Acceptor 530 INITIATOR_NEGO 531 +*INITIATOR_META_DATA 532 *AP_REQUEST 533 ---------> 534 ACCEPTOR_NEGO 535 ACCEPTOR_META_DATA*+ 536 <--------- CHALLENGE* 538 . 539 . 541 *AP_REQUEST ---------> 542 <--------- CHALLENGE* 544 . 545 . 546 *AP_REQUEST 547 VERIFY ---------> 548 CHALLENGE* 549 <--------- VERIFY 550 * Indicates optional or situation-dependent messages that are 551 not always sent. 552 + Indicates there can be more than one instance. 554 7.2. NEGOEX Supported Security Mechanisms 556 NEGOEX maintains an ordered list of supported security mechanisms 557 names to determine priority of security mechanisms. A security 558 mechanism negotiable by NEGOEX is identified by a unique identifier 559 of data type AUTH_SCHEME defined in Section 3.5. Supported security 560 mechanisms are referenced by their corresponding authentication 561 scheme IDs. The authentication scheme ID of a security mechanism is 562 returned to NEGOEX by calling GSS_Query_mechanism_info() with the 563 name of the security mechnism as defined in Section 8.3. 565 7.3. ConversationID 567 Both initiator and acceptor must keep protocol state in the form of a 568 GUID, which will be referred to hereafter as the ConversationID. 570 7.4. Generation of the Initiator Initial Token 572 The GSS-API initiator makes the first call to GSS_Init_sec_context() 573 with no input token, and the output token will be a NEGO_MESSAGE 574 message with the MESSAGE_TYPE_INITIATOR_NEGO message followed by zero 575 or more EXCHANGE_MESSAGE messages containing meta-data tokens, 576 followed by zero or one AP_REQUEST messages containing an optimistic 577 initial context token. 579 The initiator generates a cryptographic strength random 16 byte 580 value, stores it as the ConversationID, then sets the MESSAGE_HEADER 581 header field with the same name to that value. The ConversationID in 582 subsequent NEGOEX messages MUST remain the same. The initiator also 583 fills the Random field using a secure random number generator. The 584 initiator fills the AuthSchemes with available security mechanisms 585 supported by the initiator in decreasing preference order. 587 The extensions field contains NEGOEX extensions for future 588 extensibility. There are no extensions defined in this document. 589 All negative extension types (the highest bit is set to 1) are 590 critical. If the receiver does not understand a critical extension, 591 the authentication attempt must be rejected. 593 The initiator can OPTIONALLY include a meta-data token, one for each 594 available security mechanism. 596 A meta-data token is returned to NEGOEX for a security mechanism 597 using GSS_Query_meta_data() extension as defined in Section 8.1. If 598 a non-empty meta-data token is returned, then the meta-data token is 599 encapsulated in an EXCHANGE message with the message type 600 MESSAGE_TYPE_INITIATOR_META_DATA. On GSS_Query_meta_data call 601 failure, NEGOEX SHOULD remove the security mechanism from the set of 602 authentication schemes to be negotiated. 604 The AuthScheme field signifies the security mechanism for which the 605 EXCHANGE message is targeted. If a security mechanism fails to 606 produce the metadata token, it should be removed from the list of 607 supported security mechanism for this negotiation context. 609 If there is more than one exchange message, the order in which the 610 exchange message is included bears no significance. In other words, 611 the exchange messages are in an unordered set. The NEGO_MESSAGE MAY 612 be followed by a set of MESSAGE_TYPE_INITIATOR_META_DATA messages as 613 described above, in which case all the NEGOEX messages concatenated 614 are returned as a single output token. 616 The first mechanism in the initiator proposed list can OPTIONALLY 617 include its initial context token in an AP_REQUEST message. 619 Both an AP_REQUEST(short for MESSAGE_TYPE_AP_REQUEST) message and a 620 INITIATOR_META_DATA(short for MESSAGE_TYPE_INITIATOR_META_DATA) 621 message are instances of the EXCHANGE_MESSAGE structure with 622 different message type values. An AP_REQUEST message contains the 623 type MESSAGE_TYPE_AP_REQUEST while an INITIATOR_META_DATA message 624 contains the type MESSAGE_TYPE_INITIATOR_META_DATA. 626 7.5. Receipt of the Initial Initiator Token and Generation of the 627 Initial Acceptor Response 629 Upon receipt of the NEGO_MESSAGE from the initiator, the acceptor 630 verifies the NEGO_MESSAGE to make sure it is well-formed. The 631 acceptor extracts the ConversationID from the NEGO_MESSAGE and stores 632 it as the ConversationID for the context handle. The acceptor then 633 computes the list of authentication schemes that are mutually 634 supported by examining the set of security mechanisms proposed by the 635 initiator and the meta-data tokens from the initiator. The meta-data 636 tokens are passed to the security mechanism via 637 GSS_Exchange_meta_data() as defined in Section 8.2. On 638 GSS_Exchange_meta_data call failure, NEGOEX SHOULD remove the 639 security mechanism from the set of authentication schemes to be 640 negotiated. 642 The acceptor MUST examine the NEGOEX extensions in the NEGO_MESSAGE. 643 If there is an unknown critical extension, the authentication must be 644 rejected. 646 The acceptor's output token is a NEGO_MESSAGE but with the the 647 Header.MessageType set to MESSAGE_TYPE_ACCEPTOR_NEGO followed by zero 648 or more EXCHANGE_MESSAGE containing meta-data tokens. The 649 AuthSchemes field contains the list of mutually supported security 650 mechanism in decreasing preference order of the acceptor. The 651 acceptor does not need to honor the preference order proposed by the 652 initiator when computing its preference list. 654 As with the initiator, the acceptor can OPTIONALLY include a meta- 655 data token, one for each available security mechanism. 657 A meta-data token is obtained by NEGOEX for a security mechanism 658 using GSS_Query_meta_data() extension as defined in Section 8.1. If 659 a non-empty meta-data token is returned, then the meta-data token is 660 encapsulated in an EXCHANGE message with the message type 661 MESSAGE_TYPE_ACCEPTOR_META_DATA. For a given security mechanism if a 662 meta-token is received from the initiator, GSS_Query_meta_data() MUST 663 be invoked on the acceptor side for that security mechanism, and the 664 output meta-data token, if present, MUST be included in the NEGOEX 665 reply. On GSS_Query_meta_data call failure, NEGOEX SHOULD remove the 666 security mechanism from the set of authentication schemes to be 667 negotiated. 669 7.6. Receipt of the Acceptor Initial Response and Completion of 670 Authentication after the Negotiation Phrase 672 Upon receipt of the initial response token from the acceptor, the 673 application calls GSS_Init_sec_context with the response token. The 674 initiator verifies the NEGOEX message received to make sure it is 675 well-formed. The initiator ensures the correct context handle by 676 verifying that the ConversationID of the context handle matches the 677 conversation ID in the NEGOEX message received. The initiator then 678 computes the list of authentication schemes that are mutually 679 supported by examining the set of security mechanisms returned by the 680 acceptor and the meta-data tokens from the acceptor The meta-data 681 tokens are passed to the security mechanism via 682 GSS_Exchange_meta_data() as defined in Section 8.2. On 683 GSS_Exchange_meta_data call failure, NEGOEX SHOULD remove the 684 security mechanism from the set of authentication schemes to be 685 negotiated. 687 The initiator MUST examine the NEGOEX extensions in the NEGO_MESSAGE. 688 If there is an unknown critical extension, the authentication must be 689 rejected. 691 After the initial exchange of NEGO_MESSAGE messages, the initiator 692 MUST choose the negotiated security mechanism. The negotiated 693 security mechanism cannot be changed once it is selected. 695 The initiator and the acceptor can then proceed to exchange handshake 696 messages by returning GSS_S_CONTINUE_NEEDED to the calling 697 application as determined by the negotiated security mechanism until 698 its authentication context is established. The context tokens of the 699 negotiated security mechanism are encapsulated in an 700 EXCHANGE_MESSAGE. If the context token is from the initiator, the 701 EXCHANGE_MESSAGE message has the message type 702 MESSAGE_TYPE_AP_REQUEST; otherwise, the message type is 703 MESSAGE_TYPE_CHALLENGE. 705 7.7. Finalizing Negotiation 707 After the security mechanism has been selected, the initiator and 708 acceptor can use GSS_Inquire_context to obtain the Negoex_Verify_key 709 as defined in Section 8.4 to determine if there is a shared key for 710 the VERIFY message. When there is a shared key established returned 711 by GSS_Inquire_context as defined in Section 8.4, a VERIFY message is 712 produced using the required checksum mechanism per RFC 3961 and 713 included in the output token. The returned protocol key is used as 714 the base key in the parlance of RFC3961 to sign all the NEGOEX 715 messages in the negotiation context. 717 A VERIFY message is a VERIFY_MESSAGE structure. The AuthScheme field 718 signifies from which security mechanism the protocol key was 719 obtained. The checksum is computed based on RFC3961 and the key 720 usage number is 23 for the message signed by the initiator, 25 721 otherwise. The checksum is performed over all the previous NEGOEX 722 messages in the context negotiation. 724 struct 725 { 726 MESSAGE_HEADER Header; // MESSAGE_TYPE_VERIFY 727 AUTH_SCHEME AuthScheme; 728 CHECKSUM Checksum; 729 // contains the checksum of all the previously 730 // exchanged messages in the order they were sent. 731 } VERIFY_MESSAGE; 733 Note that the VERIFY_MESSAGE message can be included before the 734 security context for the negotiated security mechanism is fully 735 established. 737 8. Supporting GSS-API Extensions 739 This section defined all the required GSS-API extensions required by 740 NEGOEX which must be supported by security mechanisms usable with 741 NEGOEX. 743 8.1. GSS_Query_meta_data 745 Inputs: 747 o input_context_handle CONTEXT HANDLE 748 o targ_name INTERNAL NAME, optional 749 o deleg_req_flag BOOLEAN, 750 o mutual_req_flag BOOLEAN, 751 o replay_det_req_flag BOOLEAN, 752 o sequence_req_flag BOOLEAN, 753 o conf_req_flag BOOLEAN, 754 o integ_req_flag BOOLEAN, 756 Outputs: 758 o metadata OCTET STRING, 759 o output_context_handle CONTEXT HANDLE 761 Return major_status codes: 763 o GSS_S_COMPLETE indicates that the context referenced by the 764 input_context_handle argument is valid, and that the output 765 metadata value represents the security mechanism's provided 766 metadata. A security mechanism may return empty metadata. 767 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 768 for the input context_handle provided. Return values other than 769 major_status and minor_status are undefined. 770 o GSS_S_NO_CRED indicates that no metadata could be returned about 771 the referenced credentials either because the input cred_handle 772 was invalid or the caller lacks authorization to access the 773 referenced credentials. 774 o GSS_S_UNAVAILABLE indicates that the authentication security 775 service does not support this operation. 776 o GSS_S_FAILURE indicates that the requested operation failed for 777 reasons unspecified at the GSS-API level. Return values other 778 than major_status and minor_status are undefined. 780 GSS_Query_meta_data is used to retrieve a security mechanism's 781 metadata. 783 8.2. GSS_Exchange_meta_data 785 Inputs: 787 o input_context_handle CONTEXT HANDLE 788 o cred_handle CREDENTIAL HANDLE, optional 789 o targ_name INTERNAL NAME, optional 790 o deleg_req_flag BOOLEAN, 791 o mutual_req_flag BOOLEAN, 792 o replay_det_req_flag BOOLEAN, 793 o sequence_req_flag BOOLEAN, 794 o conf_req_flag BOOLEAN, 795 o integ_req_flag BOOLEAN, 796 o metadata OCTET STRING, 798 Outputs: 800 o output_context_handle CONTEXT HANDLE 802 Return major_status codes: 804 o GSS_S_COMPLETE indicates that the metadata was provided to the 805 security mechanism. 806 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 807 for the input context_handle provided. Return values other than 808 major_status and minor_status are undefined. 810 o GSS_S_NO_CRED indicates that the metadata passed requested 811 credentials not available via this credential handle. 812 o GSS_S_UNAVAILABLE indicates that the security mechanism does not 813 support this operation. 814 o GSS_S_FAILURE indicates that the requested operation failed for 815 reasons unspecified at the GSS-API level. Return values other 816 than major_status and minor_status are undefined. 818 GSS_Exchange_meta_data is used to provide the metadata to each 819 security mechanism. 821 8.3. GSS_Query_mechanism_info 823 Inputs: 825 o SecMechName STRING, 827 Outputs: 829 o AuthScheme AUTH_SCHEME 831 Return major_status codes: 833 o GSS_S_COMPLETE indicates that the authentication scheme value 834 represents the security mechanism's AUTH_SCHEME. 835 o GSS_S_FAILURE indicates that the security mechanism does not 836 support NEGOEX. Return values other than major_status and 837 minor_status are undefined. 839 GSS_Query_mechanism_info returns a security mechanism's 840 authentication scheme value. 842 8.4. GSS_Inquire_context 844 The following output is added to GSS_Inquire_context as defined in 845 [RFC2743]. 847 Outputs: 849 o Negoex_Verify_key OCTET STRING 851 This new output is the key to be used by NEGOEX for the VERIFY 852 message. 854 9. Security Considerations 856 Security mechanism SHOULD support providing VERIFY key material. 858 This ensures that VERIFY messages are generated to make NEGOEX safe 859 from downgrade attacks. 861 10. Acknowledgements 863 TBD. 865 11. IANA Considerations 867 There is no action required for IANA. 869 12. Normative References 871 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 872 Requirement Levels", BCP 14, RFC 2119, March 1997. 874 [RFC2743] Linn, J., "Generic Security Service Application Program 875 Interface Version 2, Update 1", RFC 2743, January 2000. 877 [RFC3961] Raeburn, K., "Encryption and Checksum Specifications for 878 Kerberos 5", RFC 3961, February 2005. 880 [RFC4120] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The 881 Kerberos Network Authentication Service (V5)", RFC 4120, 882 July 2005. 884 [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos 885 Version 5 Generic Security Service Application Program 886 Interface (GSS-API) Mechanism: Version 2", RFC 4121, 887 July 2005. 889 [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The 890 Simple and Protected Generic Security Service Application 891 Program Interface (GSS-API) Negotiation Mechanism", 892 RFC 4178, October 2005. 894 Appendix A. Protocol Data Structures and Constant Values 896 This section compiles all the protocol data structures and constant 897 values. 899 #define MESSAGE_SIGNATURE 0x535458454f47454ei64 900 // "NEGOEXTS" 902 struct 903 { 904 ULONG ByteArrayOffset; // each element contains a byte 905 ULONG ByteArrayLength; 906 } BYTE_VECTOR; 908 struct 909 { 910 ULONG AuthSchemeArrayOffset; 911 // each element contains an AUTH_SCHEME 912 USHORT AuthSchemeCount; 913 } AUTH_SCHEME_VECTOR; 915 struct 916 { 917 ULONG ExtensionArrayOffset; 918 // each element contains an EXTENSION 919 USHORT ExtensionCount; 920 } EXTENSION_VECTOR; 922 struct 923 { 924 ULONG ExtensionType; // negative extensions are critical 925 BYTE_VECTOR ExtensionValue; 926 } EXTENSION; 928 // 929 // schemes defined for the checksum in the VERIFY message 930 // 932 #define CHECKSUM_SCHEME_RFC3961 1 934 struct 935 { 936 ULONG cbHeaderLength; 937 ULONG ChecksumScheme; 938 ULONG ChecksumType; // in the case of RFC3961 scheme, this is 939 // the RFC3961 checksum type 940 BYTE_VECTOR ChecksumValue; 941 } CHECKSUM; 943 typedef GUID AUTH_SCHEME; 944 typedef GUID CONVERSATION_ID; 946 enum 947 { 948 MESSAGE_TYPE_INITIATOR_NEGO = 0, 949 MESSAGE_TYPE_ACCEPTOR_NEGO, 950 MESSAGE_TYPE_INITIATOR_META_DATA, 951 MESSAGE_TYPE_ACCEPTOR_META_DATA, 952 MESSAGE_TYPE_CHALLENGE, 953 // an exchange message from the acceptor 954 MESSAGE_TYPE_AP_REQUEST, 955 // an exchange message from the initiator 956 MESSAGE_TYPE_VERIFY, 957 MESSAGE_TYPE_ALERT, 958 } MESSAGE_TYPE; 960 struct 961 { 962 ULONG64 Signature; // contains MESSAGE_SIGNATURE 963 MESSAGE_TYPE MessageType; 964 ULONG SequenceNum; // the message sequence number of this, 965 // conversation, starting with 0 and sequentially 966 // incremented 967 ULONG cbHeaderLength; // the header length of this message, 968 // including the message specific header, excluding the 969 // payload 970 ULONG cbMessageLength; // the length of this message 971 CONVERSATION_ID ConversationId; 972 } MESSAGE_HEADER; 974 struct 975 { 976 MESSAGE_HEADER Header; 977 // MESSAGE_TYPE_INITIATOR_NEGO for the initiator, 978 // MESSAGE_TYPE_ACCEPTOR_NEGO for the acceptor 979 UCHAR Random[32]; 980 ULONG64 ProtocolVersion; 981 // version of the protocol, this contains 0 982 AUTH_SCHEME_VECTOR AuthSchemes; 983 EXTENSION_VECTOR Extensions; 984 } NEGO_MESSAGE; 986 struct 987 { 988 MESSAGE_HEADER Header; 989 // MESSAGE_TYPE_CHALLENGE for the acceptor, 990 // or MESSAGE_TYPE_AP_REQUEST for the initiator 991 // MESSAGE_TYPE_INITiATOR_META_DATA for 992 // the initiator metadata 993 // MESSAGE_TYPE_ACCEPTOR_META_DATA for 994 // the acceptor metadata 995 AUTH_SCHEME AuthScheme; 996 BYTE_VECTOR Exchange; 997 // contains the opaque handshake message for the 998 // authentication scheme 999 } EXCHANGE_MESSAGE; 1001 struct 1002 { 1003 MESSAGE_HEADER Header; // MESSAGE_TYPE_VERIFY 1004 AUTH_SCHEME AuthScheme; 1005 CHECKSUM Checksum; 1006 // contains the checksum of all the previously 1007 // exchanged messages in the order they were sent. 1008 } VERIFY_MESSAGE; 1010 struct 1011 { 1012 ULONG AlertType; 1013 BYTE_VECTOR AlertValue; 1014 } ALERT; 1016 // 1017 // alert types 1018 // 1020 #define ALERT_TYPE_PULSE 1 1022 // 1023 // reason codes for the heartbeat message 1024 // 1026 #define ALERT_VERIFY_NO_KEY 1 1028 struct 1029 { 1030 ULONG cbHeaderLength; 1031 ULONG Reason; 1032 } ALERT_PULSE; 1034 struct 1035 { 1036 ULONG AlertArrayOffset; // the element is an ALERT 1037 USHORT AlertCount; // contains the number of alerts 1038 } ALERT_VECTOR; 1040 struct 1041 { 1042 MESSAGE_HEADER Header; 1043 AUTH_SCHEME AuthScheme; 1044 ULONG ErrorCode; // an NTSTATUS code 1045 ALERT_VECTOR Alerts; 1047 } ALERT_MESSAGE; 1049 Authors' Addresses 1051 Michiko Short 1052 Microsoft Corporation 1053 One Microsoft Way 1054 Redmond, WA 98052 1055 US 1057 Email: michikos@microsoft.com 1059 Larry Zhu 1060 Microsoft Corporation 1061 One Microsoft Way 1062 Redmond, WA 98052 1063 US 1065 Email: lzhu@microsoft.com 1067 Kevin Damour 1068 Microsoft Corporation 1069 One Microsoft Way 1070 Redmond, WA 98052 1071 US 1073 Email: kdamour@microsoft.com 1075 Dave McPherson 1076 Microsoft Corporation 1077 One Microsoft Way 1078 Redmond, WA 98052 1079 US 1081 Email: davemm@microsoft.com