idnits 2.17.1 draft-zhu-negoex-03.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 (December 1, 2010) is 4896 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: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '32' on line 965 == Unused Reference: 'RFC4120' is defined on line 867, 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: Informational D. McPherson 6 Expires: June 4, 2011 Microsoft Corporation 7 December 1, 2010 9 SPNEGO Extended Negotiation (NEGOEX) Security Mechanism 10 draft-zhu-negoex-03 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 June 4, 2011. 63 Copyright Notice 65 Copyright (c) 2010 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 . . . . . . . . . . . . . 14 101 7.6. Receipt of the Acceptor Initial Response and 102 Completion of Authentication after the Negotiation 103 Phrase . . . . . . . . . . . . . . . . . . . . . . . . . . 15 104 7.7. Finalizing Negotiation . . . . . . . . . . . . . . . . . . 16 105 8. Supporting GSS-API Extensions . . . . . . . . . . . . . . . . 16 106 8.1. GSS_Query_meta_data . . . . . . . . . . . . . . . . . . . 17 107 8.2. GSS_Exchange_meta_data . . . . . . . . . . . . . . . . . . 17 108 8.3. GSS_Query_mechanism_info . . . . . . . . . . . . . . . . . 18 109 8.4. GSS_Inquire_context . . . . . . . . . . . . . . . . . . . 19 110 9. Security Considerations . . . . . . . . . . . . . . . . . . . 19 111 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 19 112 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 113 12. Normative References . . . . . . . . . . . . . . . . . . . . . 19 114 Appendix A. Protocol Data Structures and Constant Values . . . . 20 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 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 text art summarizes 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 text art summarizes 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 text art summarizes 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_NEGO 529 +*INITIATOR_META_DATA 530 *AP_REQUEST 531 ---------> 532 ACCEPTOR_NEGO 533 ACCEPTOR_META_DATA*+ 534 <--------- CHALLENGE* 536 . 537 . 538 *AP_REQUEST 539 VERIFY ---------> 540 CHALLENGE* 541 <-------- VERIFY 542 * Indicates optional or situation-dependent messages that are 543 not always sent. 544 + Indicates there can be more than one instance. 546 7.2. NEGOEX Supported Security Mechanisms 548 NEGOEX maintains an ordered list of supported security mechanisms 549 names to determine priority of security mechanisms. A security 550 mechanism negotiable by NEGOEX is identified by a unique identifier 551 of data type AUTH_SCHEME defined in Section 3.5. Supported security 552 mechanisms are referenced by their corresponding authentication 553 scheme IDs. The authentication scheme ID of a security mechanism is 554 returned to NEGOEX by calling GSS_Query_mechanism_info() with the 555 name of the security mechnism as defined in Section 8.3. 557 7.3. ConversationID 559 A GUID is randomly generated by the initiator to identify the 560 conversation. This GUID is referred to as a ConversationID and must 561 be maintained by both the initiator and acceptor until the 562 conversation has ended as it is included in the header of all NEGOEX 563 messages. 565 7.4. Generation of the Initiator Initial Token 567 The GSS-API initiator makes the first call to GSS_Init_sec_context() 568 with no input token, and the output token will be a NEGO_MESSAGE 569 message with the MESSAGE_TYPE_INITIATOR_NEGO message followed by zero 570 or more EXCHANGE_MESSAGE messages containing meta-data tokens, 571 followed by zero or one AP_REQUEST messages containing an optimistic 572 initial context token. 574 The initiator randomly generates a ConversationID and fills the 575 MESSAGE_HEADER header. The ConversationID in subsequent NEGOEX 576 messages MUST remain the same. The initiator also fills the Random 577 field using a secure random number generator. The initiator fills 578 the AuthSchemes with available security mechanisms supported by the 579 initiator in decreasing preference order. 581 The extensions field contains NEGOEX extensions for future 582 extensibility. There are no extensions defined in this document. 583 All negative extension types (the highest bit is set to 1) are 584 critical. If the receiver does not understand a critical extension, 585 the authentication attempt must be rejected. 587 The initiator can OPTIONALLY include a meta-data token, one for each 588 available security mechanism. 590 A meta-data token is returned to NEGOEX for a security mechanism 591 using GSS_Query_meta_data() extension as defined in Section 8.1. If 592 a non-empty meta-data token is returned, then the meta-data token is 593 encapsulated in an EXCHANGE message with the message type 594 MESSAGE_TYPE_INITIATOR_META_DATA. On GSS_Query_meta_data call 595 failure, NEGOEX SHOULD remove the security mechanism from the set of 596 authentication schemes to be negotiated. 598 The AuthScheme field signifies the security mechanism for which the 599 EXCHANGE message is targeted. If a security mechanism fails to 600 produce the metadata token, it should be removed from the list of 601 supported security mechanism for this negotiation context. 603 If there is more than one exchange message, the order in which the 604 exchange message is included bears no significance. In other words, 605 the exchange messages are in an unordered set. The NEGO_MESSAGE MAY 606 be followed by a set of MESSAGE_TYPE_INITIATOR_META_DATA messages as 607 described above, in which case all the NEGOEX messages concatenated 608 are returned as a single output token. 610 The first mechanism in the initiator proposed list can OPTIONALLY 611 include its initial context token in an AP_REQUEST message. 613 Both an AP_REQUEST(short for MESSAGE_TYPE_AP_REQUEST) message and a 614 INITIATOR_META_DATA(short for MESSAGE_TYPE_INITIATOR_META_DATA) 615 message are instances of the EXCHANGE_MESSAGE structure with 616 different message type values. An AP_REQUEST message contains the 617 type MESSAGE_TYPE_AP_REQUEST while an INITIATOR_META_DATA message 618 contains the type MESSAGE_TYPE_INITIATOR_META_DATA. 620 7.5. Receipt of the Initial Initiator Token and Generation of the 621 Initial Acceptor Response 623 Upon receipt of the NEGO_MESSAGE from the initiator, the acceptor 624 verifies the NEGO_MESSAGE to make sure it is well-formed. The 625 acceptor then computes the list of authentication schemes that are 626 mutually supported by examining the set of security mechanisms 627 proposed by the initiator and the meta-data tokens from the 628 initiator. The meta-data tokens are passed to the security mechanism 629 via GSS_Exchange_meta_data() as defined in Section 8.2. On 630 GSS_Exchange_meta_data call failure, NEGOEX SHOULD remove the 631 security mechanism from the set of authentication schemes to be 632 negotiated. 634 The acceptor MUST examine the NEGOEX extensions in the NEGO_MESSAGE. 635 If there is an unknown critical extension, the authentication must be 636 rejected. 638 The acceptor's output token is a NEGO_MESSAGE but with the the 639 Header.MessageType set to MESSAGE_TYPE_ACCEPTOR_NEGO followed by zero 640 or more EXCHANGE_MESSAGE containing meta-data tokens. The 641 AuthSchemes field contains the list of mutually supported security 642 mechanism in decreasing preference order of the acceptor. The 643 acceptor does not need to honor the preference order proposed by the 644 initiator when computing its preference list. 646 As with the initiator, the acceptor can OPTIONALLY include a meta- 647 data token, one for each available security mechanism. 649 A meta-data token is obtained by NEGOEX for a security mechanism 650 using GSS_Query_meta_data() extension as defined in Section 8.1. If 651 a non-empty meta-data token is returned, then the meta-data token is 652 encapsulated in an EXCHANGE message with the message type 653 MESSAGE_TYPE_ACCEPTOR_META_DATA. For a given security mechanism if a 654 meta-token is received from the initiator, GSS_Query_meta_data() MUST 655 be invoked on the acceptor side for that security mechanism, and the 656 output meta-data token, if present, MUST be included in the NEGOEX 657 reply. On GSS_Query_meta_data call failure, NEGOEX SHOULD remove the 658 security mechanism from the set of authentication schemes to be 659 negotiated. 661 7.6. Receipt of the Acceptor Initial Response and Completion of 662 Authentication after the Negotiation Phrase 664 Upon receipt of the initial response token from the acceptor, the 665 application calls GSS_Init_sec_context with the response token. The 666 initiator verifies the NEGO_MESSAGE to make sure it is well-formed. 667 The initiator then computes the list of authentication schemes that 668 are mutually supported by examining the set of security mechanisms 669 returned by the acceptor and the meta-data tokens from the acceptor 670 The meta-data tokens are passed to the security mechanism via 671 GSS_Exchange_meta_data() as defined in Section 8.2. On 672 GSS_Exchange_meta_data call failure, NEGOEX SHOULD remove the 673 security mechanism from the set of authentication schemes to be 674 negotiated. 676 The initiator MUST examine the NEGOEX extensions in the NEGO_MESSAGE. 677 If there is an unknown critical extension, the authentication must be 678 rejected. 680 After the initial exchange of NEGO_MESSAGE messages, the initiator 681 MUST choose the negotiated security mechanism. The negotiated 682 security mechanism cannot be changed once it is selected. 684 The initiator and the acceptor can then proceed to exchange handshake 685 messages by returning GSS_S_CONTINUE_NEEDED to the calling 686 application as determined by the negotiated security mechanism until 687 its authentication context is established. The context tokens of the 688 negotiated security mechanism are encapsulated in an 689 EXCHANGE_MESSAGE. If the context token is from the initiator, the 690 EXCHANGE_MESSAGE message has the message type 691 MESSAGE_TYPE_AP_REQUEST; otherwise, the message type is 692 MESSAGE_TYPE_CHALLENGE. 694 7.7. Finalizing Negotiation 696 After the security mechanism has been selected, the initiator and 697 acceptor can use GSS_Inquire_context to obtain the Negoex_Verify_key 698 as defined in Section 8.4 to determine if there is a shared key for 699 the VERIFY message. When there is a shared key established returned 700 by GSS_Inquire_context as defined in Section 8.4, a VERIFY message is 701 produced using the required checksum mechanism per RFC 3961 and 702 included in the output token. The returned protocol key is used as 703 the base key in the parlance of RFC3961 to sign all the NEGOEX 704 messages in the negotiation context. 706 A VERIFY message is a VERIFY_MESSAGE structure. The AuthScheme field 707 signifies from which security mechanism the protocol key was 708 obtained. The checksum is computed based on RFC3961 and the key 709 usage number is 23 for the message signed by the initiator, 25 710 otherwise. The checksum is performed over all the previous NEGOEX 711 messages in the context negotiation. 713 struct 714 { 715 MESSAGE_HEADER Header; // MESSAGE_TYPE_VERIFY 716 AUTH_SCHEME AuthScheme; 717 CHECKSUM Checksum; 718 // contains the checksum of all the previously 719 // exchanged messages in the order they were sent. 720 } VERIFY_MESSAGE; 722 Note that the VERIFY_MESSAGE message can be included before the 723 security context for the negotiated security mechanism is fully 724 established. 726 8. Supporting GSS-API Extensions 728 This section defined all the required GSS-API extensions required by 729 NEGOEX which must be supported by security mechanisms usable with 730 NEGOEX. 732 8.1. GSS_Query_meta_data 734 Inputs: 736 o input_context_handle CONTEXT HANDLE 737 o targ_name INTERNAL NAME, optional 738 o deleg_req_flag BOOLEAN, 739 o mutual_req_flag BOOLEAN, 740 o replay_det_req_flag BOOLEAN, 741 o sequence_req_flag BOOLEAN, 742 o conf_req_flag BOOLEAN, 743 o integ_req_flag BOOLEAN, 745 Outputs: 747 o metadata OCTET STRING, 748 o output_context_handle CONTEXT HANDLE 750 Return major_status codes: 752 o GSS_S_COMPLETE indicates that the context referenced by the 753 input_context_handle argument is valid, and that the output 754 metadata value represents the security mechanism's provided 755 metadata. A security mechanism may return empty metadata. 756 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 757 for the input context_handle provided. Return values other than 758 major_status and minor_status are undefined. 759 o GSS_S_NO_CRED indicates that no metadata could be returned about 760 the referenced credentials either because the input cred_handle 761 was invalid or the caller lacks authorization to access the 762 referenced credentials. 763 o GSS_S_UNAVAILABLE indicates that the authentication security 764 service does not support this operation. 765 o GSS_S_FAILURE indicates that the requested operation failed for 766 reasons unspecified at the GSS-API level. Return values other 767 than major_status and minor_status are undefined. 769 GSS_Query_meta_data is used to retrieve a security mechanism's 770 metadata. 772 8.2. GSS_Exchange_meta_data 774 Inputs: 776 o input_context_handle CONTEXT HANDLE 777 o cred_handle CREDENTIAL HANDLE, optional 778 o targ_name INTERNAL NAME, optional 779 o deleg_req_flag BOOLEAN, 780 o mutual_req_flag BOOLEAN, 781 o replay_det_req_flag BOOLEAN, 782 o sequence_req_flag BOOLEAN, 783 o conf_req_flag BOOLEAN, 784 o integ_req_flag BOOLEAN, 785 o metadata OCTET STRING, 787 Outputs: 789 o output_context_handle CONTEXT HANDLE 791 Return major_status codes: 793 o GSS_S_COMPLETE indicates that the metadata was provided to the 794 security mechanism. 795 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 796 for the input context_handle provided. Return values other than 797 major_status and minor_status are undefined. 798 o GSS_S_NO_CRED indicates that the metadata passed requested 799 credentials not available via this credential handle. 800 o GSS_S_UNAVAILABLE indicates that the security mechanism does not 801 support this operation. 802 o GSS_S_FAILURE indicates that the requested operation failed for 803 reasons unspecified at the GSS-API level. Return values other 804 than major_status and minor_status are undefined. 806 GSS_Exchange_meta_data is used to provide the metadata to each 807 security mechanism. 809 8.3. GSS_Query_mechanism_info 811 Inputs: 813 o SecMechName STRING, 815 Outputs: 817 o AuthScheme AUTH_SCHEME 819 Return major_status codes: 821 o GSS_S_COMPLETE indicates that the authentication scheme value 822 represents the security mechanism's AUTH_SCHEME. 823 o GSS_S_FAILURE indicates that the security mechanism does not 824 support NEGOEX. Return values other than major_status and 825 minor_status are undefined. 827 GSS_Query_mechanism_info returns a security mechanism's 828 authentication scheme value. 830 8.4. GSS_Inquire_context 832 The following output is added to GSS_Inquire_context as defined in 833 [RFC2743]. 835 Outputs: 837 o Negoex_Verify_key OCTET STRING 839 This new output is the key to be used by NEGOEX for the VERIFY 840 message. 842 9. Security Considerations 844 Security mechanism SHOULD support providing VERIFY key material. 845 This ensures that VERIFY messages are generated to make NEGOEX safe 846 from downgrade attacks. 848 10. Acknowledgements 850 TBD. 852 11. IANA Considerations 854 There is no action required for IANA. 856 12. Normative References 858 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 859 Requirement Levels", BCP 14, RFC 2119, March 1997. 861 [RFC2743] Linn, J., "Generic Security Service Application Program 862 Interface Version 2, Update 1", RFC 2743, January 2000. 864 [RFC3961] Raeburn, K., "Encryption and Checksum Specifications for 865 Kerberos 5", RFC 3961, February 2005. 867 [RFC4120] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The 868 Kerberos Network Authentication Service (V5)", RFC 4120, 869 July 2005. 871 [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos 872 Version 5 Generic Security Service Application Program 873 Interface (GSS-API) Mechanism: Version 2", RFC 4121, 874 July 2005. 876 [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The 877 Simple and Protected Generic Security Service Application 878 Program Interface (GSS-API) Negotiation Mechanism", 879 RFC 4178, October 2005. 881 Appendix A. Protocol Data Structures and Constant Values 883 This section compiles all the protocol data structures and constant 884 values. 886 #define MESSAGE_SIGNATURE 0x535458454f47454ei64 887 // "NEGOEXTS" 889 struct 890 { 891 ULONG ByteArrayOffset; // each element contains a byte 892 ULONG ByteArrayLength; 893 } BYTE_VECTOR; 895 struct 896 { 897 ULONG AuthSchemeArrayOffset; 898 // each element contains an AUTH_SCHEME 899 USHORT AuthSchemeCount; 900 } AUTH_SCHEME_VECTOR; 902 struct 903 { 904 ULONG ExtensionArrayOffset; 905 // each element contains an EXTENSION 906 USHORT ExtensionCount; 907 } EXTENSION_VECTOR; 909 struct 910 { 911 ULONG ExtensionType; // negative extensions are critical 912 BYTE_VECTOR ExtensionValue; 913 } EXTENSION; 915 // 916 // schemes defined for the checksum in the VERIFY message 917 // 918 #define CHECKSUM_SCHEME_RFC3961 1 920 struct 921 { 922 ULONG cbHeaderLength; 923 ULONG ChecksumScheme; 924 ULONG ChecksumType; // in the case of RFC3961 scheme, this is 925 // the RFC3961 checksum type 926 BYTE_VECTOR ChecksumValue; 927 } CHECKSUM; 929 typedef GUID AUTH_SCHEME; 930 typedef GUID CONVERSATION_ID; 932 enum 933 { 934 MESSAGE_TYPE_INITIATOR_NEGO = 0, 935 MESSAGE_TYPE_ACCEPTOR_NEGO, 936 MESSAGE_TYPE_INITIATOR_META_DATA, 937 MESSAGE_TYPE_ACCEPTOR_META_DATA, 938 MESSAGE_TYPE_CHALLENGE, 939 // an exchange message from the acceptor 940 MESSAGE_TYPE_AP_REQUEST, 941 // an exchange message from the initiator 942 MESSAGE_TYPE_VERIFY, 943 MESSAGE_TYPE_ALERT, 944 } MESSAGE_TYPE; 946 struct 947 { 948 ULONG64 Signature; // contains MESSAGE_SIGNATURE 949 MESSAGE_TYPE MessageType; 950 ULONG SequenceNum; // the message sequence number of this, 951 // conversation, starting with 0 and sequentially 952 // incremented 953 ULONG cbHeaderLength; // the header length of this message, 954 // including the message specific header, excluding the 955 // payload 956 ULONG cbMessageLength; // the length of this message 957 CONVERSATION_ID ConversationId; 958 } MESSAGE_HEADER; 960 struct 961 { 962 MESSAGE_HEADER Header; 963 // MESSAGE_TYPE_INITIATOR_NEGO for the initiator, 964 // MESSAGE_TYPE_ACCEPTOR_NEGO for the acceptor 965 UCHAR Random[32]; 966 ULONG64 ProtocolVersion; 967 // version of the protocol, this contains 0 968 AUTH_SCHEME_VECTOR AuthSchemes; 969 EXTENSION_VECTOR Extensions; 970 } NEGO_MESSAGE; 972 struct 973 { 974 MESSAGE_HEADER Header; 975 // MESSAGE_TYPE_CHALLENGE for the acceptor, 976 // or MESSAGE_TYPE_AP_REQUEST for the initiator 977 // MESSAGE_TYPE_INITiATOR_META_DATA for 978 // the initiator metadata 979 // MESSAGE_TYPE_ACCEPTOR_META_DATA for 980 // the acceptor metadata 981 AUTH_SCHEME AuthScheme; 982 BYTE_VECTOR Exchange; 983 // contains the opaque handshake message for the 984 // authentication scheme 985 } EXCHANGE_MESSAGE; 987 struct 988 { 989 MESSAGE_HEADER Header; // MESSAGE_TYPE_VERIFY 990 AUTH_SCHEME AuthScheme; 991 CHECKSUM Checksum; 992 // contains the checksum of all the previously 993 // exchanged messages in the order they were sent. 994 } VERIFY_MESSAGE; 996 struct 997 { 998 ULONG AlertType; 999 BYTE_VECTOR AlertValue; 1000 } ALERT; 1002 // 1003 // alert types 1004 // 1006 #define ALERT_TYPE_PULSE 1 1008 // 1009 // reason codes for the heartbeat message 1010 // 1012 #define ALERT_VERIFY_NO_KEY 1 1013 struct 1014 { 1015 ULONG cbHeaderLength; 1016 ULONG Reason; 1017 } ALERT_PULSE; 1019 struct 1020 { 1021 ULONG AlertArrayOffset; // the element is an ALERT 1022 USHORT AlertCount; // contains the number of alerts 1023 } ALERT_VECTOR; 1025 struct 1026 { 1027 MESSAGE_HEADER Header; 1028 AUTH_SCHEME AuthScheme; 1029 ULONG ErrorCode; // an NTSTATUS code 1030 ALERT_VECTOR Alerts; 1031 } ALERT_MESSAGE; 1033 Authors' Addresses 1035 Michiko Short 1036 Microsoft Corporation 1037 One Microsoft Way 1038 Redmond, WA 98052 1039 US 1041 Email: michikos@microsoft.com 1043 Larry Zhu 1044 Microsoft Corporation 1045 One Microsoft Way 1046 Redmond, WA 98052 1047 US 1049 Email: lzhu@microsoft.com 1050 Kevin Damour 1051 Microsoft Corporation 1052 One Microsoft Way 1053 Redmond, WA 98052 1054 US 1056 Email: kdamour@microsoft.com 1058 Dave McPherson 1059 Microsoft Corporation 1060 One Microsoft Way 1061 Redmond, WA 98052 1062 US 1064 Email: davemm@microsoft.com