idnits 2.17.1 draft-ietf-dnsext-gss-tsig-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard == It seems as if not all pages are separated by form feeds - found 0 form feeds but 21 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 356 has weird spacing: '...erified the c...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: If major_status is GSS_S_COMPLETE, the signature is authentic and the message was delivered intact. Per [RFC2845], the timer values of the TSIG record MUST also be valid before considering the message to be authentic. The caller MUST not act on the request or response in the message until these checks are verified. -- 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.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'ISO11578' is mentioned on line 303, but not defined == Unused Reference: 'RFC2137' is defined on line 976, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2845 (Obsoleted by RFC 8945) ** Obsolete normative reference: RFC 2535 (Obsoleted by RFC 4033, RFC 4034, RFC 4035) ** Obsolete normative reference: RFC 2137 (Obsoleted by RFC 3007) -- Duplicate reference: RFC1034, mentioned in 'RFC1035', was also mentioned in 'RFC1034'. ** Obsolete normative reference: RFC 2478 (Obsoleted by RFC 4178) Summary: 6 errors (**), 0 flaws (~~), 7 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Stuart Kwan 2 Praerit Garg 3 January 30, 2002 James Gilroy 4 Expires July 30, 2002 Levon Esibov 5 Jeff Westhead 6 Microsoft Corp. 7 Randy Hall 8 Lucent Technologies 10 GSS Algorithm for TSIG (GSS-TSIG) 12 Status of this Memo 14 This document is an Internet-Draft and is in full conformance 15 with all provisions of Section 10 of RFC2026. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as 20 Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six 23 months and may be updated, replaced, or obsoleted by other 24 documents at any time. It is inappropriate to use Internet- 25 Drafts as reference material or to cite them other than as 26 "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 Abstract 36 The TSIG protocol provides transaction level authentication for DNS. 37 TSIG is extensible through the definition of new algorithms. This 38 document specifies an algorithm based on the Generic Security Service 39 Application Program Interface (GSS-API) (RFC2743). 41 Table of Contents 43 1: Introduction......................................................2 44 2: Algorithm Overview................................................3 45 2.1: GSS Details...................................................4 46 3: Client Protocol Details...........................................4 47 3.1: Negotiating Context...........................................4 48 3.1.1: Call GSS_Init_sec_context.................................5 49 3.1.2: Send TKEY Query to Server.................................6 50 3.1.3: Receive TKEY Query-Response from Server...................7 51 3.2: Context Established...........................................9 52 3.2.1: Terminating a Context....................................10 53 4: Server Protocol Details..........................................10 54 4.1: Negotiating Context..........................................10 55 4.1.1: Receive TKEY Query from Client...........................10 56 4.1.2: Call GSS_Accept_sec_context..............................11 57 4.1.3: Send TKEY Query-Response to Client.......................11 58 4.2: Context Established..........................................13 59 4.2.1: Terminating a Context....................................13 60 5: Sending and Verifying Signed Messages............................13 61 5.1: Sending a Signed Message - Call GSS_GetMIC...................13 62 5.2: Verifying a Signed Message - Call GSS_VerifyMIC..............14 63 6: Example usage of GSS-TSIG algorithm..............................15 64 7: Security Considerations..........................................19 65 8: IANA Considerations..............................................19 66 9: Conformance......................................................19 67 10:Acknowledgements.................................................20 68 11:References.......................................................20 70 1. Introduction 72 The Secret Key Transaction Authentication for DNS (TSIG) [RFC2845] 73 protocol was developed to provide a lightweight authentication and 74 integrity of messages between two DNS entities, such as client and 75 server or server and server. TSIG can be used to protect dynamic 76 update messages, authenticate regular message or to off-load 77 complicated DNSSEC [RFC2535] processing from a client to a server and 78 still allow the client to be assured of the integrity of the answers. 80 The TSIG protocol [RFC2845] is extensible through the definition of new 81 algorithms. This document specifies an algorithm based on the Generic 82 Security Service Application Program Interface (GSS-API) [RFC2743]. 83 GSS-API is a framework that provides an abstraction of security to the 84 application protocol developer. The security services offered can 85 include authentication, integrity, and confidentiality. 87 The GSS-API framework has several benefits: 88 * Mechanism and protocol independence. The underlying mechanisms that 89 realize the security services can be negotiated on the fly and varied 90 over time. For example, a client and server MAY use Kerberos [RFC1964] 91 for one transaction, whereas that same server MAY use SPKM [RFC2025] 92 with a different client. 94 * The protocol developer is removed from the responsibility of 95 creating and managing a security infrastructure. For example, the 96 developer does not need to create new key distribution or key 97 management systems. Instead the developer relies on the security 98 service mechanism to manage this on its behalf. 100 The scope of this document is limited to the description of an 101 authentication mechanism only. It does not discuss and/or propose an 102 authorization mechanism. Readers that are unfamiliar with GSS-API 103 concepts are encouraged to read the characteristics and concepts section 104 of [RFC2743] before examining this protocol in detail. It is also 105 assumed that the reader is familiar with [RFC2845], [RFC2930], [RFC1034] 106 and [RFC1035]. 108 The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", 109 "RECOMMENDED", and "MAY" in this document are to be interpreted as 110 described in RFC 2119 [RFC2119]. 112 2. Algorithm Overview 114 In GSS, client and server interact to create a "security context". 115 The security context can be used to create and verify transaction 116 signatures on messages between the two parties. A unique security 117 context is required for each unique connection between client and 118 server. 120 Creating a security context involves a negotiation between client and 121 server. Once a context has been established, it has a finite lifetime 122 for which it can be used to secure messages. Thus there are three 123 states of a context associated with a connection: 125 +----------+ 126 | | 127 V | 128 +---------------+ | 129 | Uninitialized | | 130 | | | 131 +---------------+ | 132 | | 133 V | 134 +---------------+ | 135 | Negotiating | | 136 | Context | | 137 +---------------+ | 138 | | 139 V | 140 +---------------+ | 141 | Context | | 142 | Established | | 143 +---------------+ | 144 | | 145 +----------+ 147 Every connection begins in the uninitialized state. 149 2.1 GSS Details 151 Client and server MUST be locally authenticated and have acquired 152 default credentials before using this protocol as specified in 153 Section 1.1.1 "Credentials" in RFC 2743 [RFC2743]. 155 The GSS-TSIG algorithm consists of two stages: 157 I. Establish security context. The Client and Server use the 158 GSS_Init_sec_context and GSS_Accept_sec_context APIs to generate the 159 tokens that they pass to each other using [RFC2930] as a transport 160 mechanism. 162 II. Once the security context is established it is used to generate and 163 verify signatures using GSS_GetMIC and GSS_VerifyMIC APIs. These 164 signatures are exchanged by the Client and Server as a part of the TSIG 165 records exchanged in DNS messages sent between the Client and Server, 166 as described in [RFC2845]. 168 3. Client Protocol Details 170 A unique context is required for each server to which the client sends 171 secure messages. A context is identified by a context handle. A 172 client maintains a mapping of servers to handles, 174 (target_name, key_name, context_handle) 176 The value key_name also identifies a context handle. The key_name is 177 the owner name of the TKEY and TSIG records sent between a client and a 178 server to indicate to each other which context MUST be used to process 179 the current request. 181 DNS client and server MAY use various underlying security mechanisms to 182 establish security context as described in sections 3 and 4. At the 183 same time, in order to guarantee interoperability between DNS clients 184 and servers that support GSS-TSIG it is REQUIRED that security 185 mechanism used by client enables use of Kerberos v5 (see Section 9 186 for more information). 188 3.1 Negotiating Context 190 In GSS, establishing a security context involves the passing of opaque 191 tokens between the client and the server. The client generates the 192 initial token and sends it to the server. The server processes the 193 token and if necessary, returns a subsequent token to the client. The 194 client processes this token, and so on, until the negotiation is 195 complete. The number of times the client and server exchange tokens 196 depends on the underlying security mechanism. A completed negotiation 197 results in a context handle. 199 The TKEY resource record [RFC2930] is used as the vehicle to transfer 200 tokens between client and server. The TKEY record is a general 201 mechanism for establishing secret keys for use with TSIG. For more 202 information, see [RFC2930]. 204 3.1.1 Call GSS_Init_sec_context 206 To obtain the first token to be sent to a server, a client MUST call 207 GSS_Init_sec_context API. 208 The following input parameters MUST be used. The outcome of the call is 209 indicated with the output values below. Consult Sections 2.2.1 210 "GSS_Init_sec_context call" of [RFC2743] for syntax definitions. 212 INPUTS 213 CREDENTIAL HANDLE claimant_cred_handle = NULL (NULL specifies "use 214 default"). Client MAY instead specify some other valid handle 215 to its credentials. 216 CONTEXT HANDLE input_context_handle = 0 217 INTERNAL NAME targ_name = "DNS@" 218 OBJECT IDENTIFIER mech_type = Underlying security 219 mechanism chosen by implementers. To guarantee 220 interoperability of the implementations of the GSS-TSIG 221 mechanism client MUST specify a valid underlying security 222 mechanism that enables use of Kerberos v5 (see Section 9 for 223 more information). 224 OCTET STRING input_token = NULL 225 BOOLEAN replay_det_req_flag = TRUE 226 BOOLEAN mutual_req_flag = TRUE 227 BOOLEAN deleg_req_flag = TRUE 228 BOOLEAN sequence_req_flag = TRUE 229 BOOLEAN anon_req_flag = FALSE 230 BOOLEAN integ_req_flag = TRUE 231 INTEGER lifetime_req = 0 (0 requests a default 232 value). Client MAY instead specify another upper bound for the 233 lifetime of the context to be established in seconds. 234 OCTET STRING chan_bindings = Any valid channel bindings 235 as specified in Section 1.1.6 "Channel Bindings" in [RFC2743] 237 OUTPUTS 238 INTEGER major_status 239 CONTEXT HANDLE output_context_handle 240 OCTET STRING output_token 241 BOOLEAN replay_det_state 242 BOOLEAN mutual_state 243 INTEGER minor_status 244 OBJECT IDENTIFIER mech_type 245 BOOLEAN deleg_state 246 BOOLEAN sequence_state 247 BOOLEAN anon_state 248 BOOLEAN trans_state 249 BOOLEAN prot_ready_state 250 BOOLEAN conf_avail 251 BOOLEAN integ_avail 252 INTEGER lifetime_rec 254 If returned major_status is set to one of the following errors 256 GSS_S_DEFECTIVE_TOKEN 257 GSS_S_DEFECTIVE_CREDENTIAL 258 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 259 GSS_S_NO_CRED 260 GSS_S_CREDENTIALS_EXPIRED 261 GSS_S_BAD_BINDINGS 262 GSS_S_OLD_TOKEN 263 GSS_S_DUPLICATE_TOKEN 264 GSS_S_NO_CONTEXT 265 GSS_S_BAD_NAMETYPE 266 GSS_S_BAD_NAME 267 GSS_S_BAD_MECH 268 GSS_S_FAILURE 270 then the the client MUST abandon the algorithm and MUST NOT use the 271 GSS-TSIG algorithm to establish this security contex. This document 272 does not prescribe which other mechanism could be used to establish 273 a security context. Next time when this client needs to establish 274 security context, the client MAY use GSS-TSIG algorithm. 276 Success values of major_status are GSS_S_CONTINUE_NEEDED and 277 GSS_S_COMPLETE. The exact success code is important during later 278 processing. 280 The values of replay_det_state and mutual_state indicate if the 281 security package provides replay detection and mutual authentication, 282 respectively. If returned major_status is GSS_S_COMPLETE AND one or both 283 of these values are FALSE, the client MUST abandon this algorithm. 285 Client's behavior MAY depend on other OUTPUT parameters according 286 to the policy local to the client. 288 The handle output_context_handle is unique to this negotiation and 289 is stored in the client's mapping table as the context_handle that 290 maps to target_name. 292 3.1.2 Send TKEY Query to Server 294 An opaque output_token returned by GSS_Init_sec_context is transmitted 295 to the server in a query request with QTYPE=TKEY. The token itself 296 will be placed in a Key Data field of the RDATA field in the TKEY 297 resource record in the additional records section of the query. The 298 owner name of the TKEY resource record set queried for and the owner 299 name of the supplied TKEY resource record in the additional records 300 section MUST be the same. This name uniquely identifies the security 301 context to both the client and server, and thus the client SHOULD use 302 a value which is globally unique as described in [RFC2930]. To achieve 303 global uniqueness, the name MAY contain a UUID/GUID [ISO11578]. 305 TKEY Record 306 NAME = client-generated globally unique domain name string 307 (as described in [RFC2930]) 308 RDATA 309 Algorithm Name = gss-tsig 310 Mode = 3 (GSS-API negotiation - per [RFC2930]) 311 Key Size = size of output_token in octets 312 Key Data = output_token 314 The remaining fields in the TKEY RDATA, i.e. Inception, Expiration, 315 Error, Other Size and Data Fields, MUST be set according to [RFC2930]. 317 The query is transmitted to the server. 319 Note: if the original client call to GSS_Init_sec_context returned any 320 major_status other than GSS_S_CONTINUE_NEEDED or GSS_S_COMPLETE, then 321 the client MUST NOT send TKEY query. Client's behavior in this case is 322 described above in Section 3.1.1. 324 3.1.3 Receive TKEY Query-Response from Server 326 Upon the reception of the TKEY query DNS server MUST respond according 327 to the description in Section 4. This Section specifies the behavior 328 of the client after it receives the matching response to its query. 330 The next processing step depends on the value of major_status from the 331 most recent call that client performed to GSS_Init_sec_context: either 332 GSS_S_COMPLETE or GSS_S_CONTINUE. 334 3.1.3.1 Value of major_status == GSS_S_COMPLETE 336 If the last call to GSS_Init_sec_context yielded a major_status value 337 of GSS_S_COMPLETE and a non-NULL output_token was sent to the server, 338 then the client side component of the negotiation is complete and the 339 client is awaiting confirmation from the server. 341 Confirmation is in the form of a query response with RCODE=NOERROR 342 and with the last client supplied TKEY record in the answer section 343 of the query. The response MUST be signed with a TSIG record. The 344 signature in the TSIG record MUST be verified using the procedure 345 detailed in section 5, Sending and Verifying Signed Messages. If the 346 response is not signed, OR if the response is signed but signature is 347 invalid, then an attacker has tampered with the message in transit or 348 has attempted to send the client a false response. In this case the 349 client MAY continue waiting for a response to its last TKEY query until 350 the time period since the client sent last TKEY query expires. Such a 351 time period is specified by the policy local to the client. This is a 352 new option that allows DNS client to accept multiple answers for one 353 query ID and select one (not necessarily the first one) based on some 354 criteria. 356 If the signature is verified the context state is advanced to Context 357 Established. Proceed to section 3.2 for usage of the security context. 359 3.1.3.2 Value of major_status == GSS_S_CONTINUE 361 If the last call to GSS_Init_sec_context yielded a major_status value 362 of GSS_S_CONTINUE, then the negotiation is not yet complete. The server 363 will return to the client a query-response with a TKEY record in the 364 Answer section. If the DNS message error is not NO_ERROR or error field 365 in the TKEY record is not 0 (i.e. no error), then the client MUST 366 abandon this negotiation sequence. The client MUST delete an active 367 context by calling GSS_Delete_sec_context providing the associated 368 context_handle. The client MAY repeat the negotiation sequence starting 369 with the uninitialized state as described in section 3.1. To prevent 370 infinite looping the number of attempts to establish a security context 371 MUST be limited to ten or less. 373 If the DNS message error is NO_ERROR and error filed in the TKEY record 374 is 0 (i.e. no error), then the client MUST pass a token specified in the 375 Key Data field in the TKEY resource record to GSS_Init_sec_context 376 using the same parameters values as in previous call except values for 377 CONTEXT HANDLE input_context_handle and OCTET STRING input_token as 378 described below: 380 INPUTS 381 CONTEXT HANDLE input_context_handle = context_handle (this is the 382 context_handle corresponding to the key_name which is the 383 owner name of the TKEY record in the answer section in the 384 TKEY query response) 385 OCTET STRING input_token = token from Key field of 386 TKEY record 388 Depending on the following OUTPUT values of GSS_Init_sec_context 389 INTEGER major_status 390 OCTET STRING output_token 391 the client MUST take one of the following actions: 393 If OUTPUT major_status is set to one of the following values 394 GSS_S_DEFECTIVE_TOKEN 395 GSS_S_DEFECTIVE_CREDENTIAL 396 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 397 GSS_S_NO_CRED 398 GSS_S_CREDENTIALS_EXPIRED 399 GSS_S_BAD_BINDINGS 400 GSS_S_OLD_TOKEN 401 GSS_S_DUPLICATE_TOKEN 402 GSS_S_NO_CONTEXT 403 GSS_S_BAD_NAMETYPE 404 GSS_S_BAD_NAME 405 GSS_S_BAD_MECH 406 GSS_S_FAILURE 408 the client MUST abandon this negotiation sequence. This means that the 409 client MUST delete an active context by calling GSS_Delete_sec_context 410 providing the associated context_handle. The client MAY repeat the 411 negotiation sequence starting with the uninitialized state as described 412 in section 3.1. To prevent infinite looping the number of attempts to 413 establish a security context MUST be limited to ten or less. 415 If OUTPUT major_status is GSS_S_CONTINUE_NEEDED OR GSS_S_COMPLETE then 416 client MUST act as described below. 418 If the response from the server was signed, and the OUTPUT major_status 419 is GSS_S_COMPLETE,then the signature in the TSIG record MUST be verified 420 using the procedure detailed in section 5, Sending and Verifying Signed 421 Messages. If the signature is invalid, then the client MUST abandon this 422 negotiation sequence. This means that the client MUST delete an active 423 context by calling GSS_Delete_sec_context providing the associated 424 context_handle. The client MAY repeat the negotiation sequence starting 425 with the uninitialized state as described in section 3.1. To prevent 426 infinite looping the number of attempts to establish a security context 427 MUST be limited to ten or less. 429 If major_status is GSS_S_CONTINUE_NEEDED the negotiation is not yet 430 finished. The token output_token MUST be passed to the server in a TKEY 431 record by repeating the negotiation sequence beginning with section 432 3.1.2. The client MUST place a limit on the number of continuations in 433 a context negotiation to prevent endless looping. Such limit SHOULD NOT 434 exceed value of 10. 436 If major_status is GSS_S_COMPLETE and output_token is non-NULL, the 437 client-side component of the negotiation is complete but the token 438 output_token MUST be passed to the server by repeating the negotiation 439 sequence beginning with section 3.1.2. 441 If major_status is GSS_S_COMPLETE and output_token is NULL, context 442 negotiation is complete. The context state is advanced to Context 443 Established. Proceed to section 3.2 for usage of the security context. 445 3.2 Context Established 447 When context negotiation is complete, the handle context_handle MUST be 448 used for the generation and verification of transaction signatures. 450 The procedures for sending and receiving signed messages are described 451 in section 5, Sending and Verifying Signed Messages. 453 3.2.1 Terminating a Context 455 When the client is not intended to continue using the established 456 security context, the client SHOULD delete an active context by 457 calling GSS_Delete_sec_context providing the associated context_handle, 458 AND client SHOULD delete the established context on the DNS server 459 by using TKEY RR with the Mode field set to 5, i.e. "key deletion" 460 [RFC2930]. 462 4. Server Protocol Details 464 As on the client-side, the result of a successful context negotiation 465 is a context handle used in future generation and verification of the 466 transaction signatures. 468 A server MAY be managing several contexts with several clients. 469 Clients identify their contexts by providing a key name in their 470 request. The server maintains a mapping of key names to handles: 472 (key_name, context_handle) 474 4.1 Negotiating Context 476 A server MUST recognize TKEY queries as security context negotiation 477 messages. 479 4.1.1 Receive TKEY Query from Client 481 Upon receiving a query with QTYPE = TKEY, the server MUST examine 482 whether the Mode and Algorithm Name fields of the TKEY record in the 483 additional records section of the message contain values of 3 and 484 gss-tsig, respectively. If they do, then the (key_name, context_handle) 485 mapping table is searched for the key_name matching the owner name of 486 the TKEY record in the additional records section of the query. If the 487 name is found in the table and the security context for this name is 488 established and not expired, then the server MUST respond to the query 489 with BADNAME error in the TKEY error field. If the name is found in the 490 table and the security context is not established, the corresponding 491 context_handle is used in subsequent GSS operations. If the name is 492 found but the security context is expired, then the server deletes this 493 security context, as described in Section 4.2.1, and interprets this 494 query as a start of new security context negotiation and performs 495 operations described in Section 4.1.2 and 4.1.3. If the name is not 496 found, then the server interprets this query as a start of new security 497 context negotiation and performs operations described in Section 4.1.2 498 and 4.1.3. 500 4.1.2 Call GSS_Accept_sec_context 502 The server performs its side of a context negotiation by calling 503 GSS_Accept_sec_context. The following input parameters MUST be used. The 504 outcome of the call is indicated with the output values below. Consult 505 Sections 2.2.2 "GSS_Accept_sec_context call" of the RFC 2743[RFC2743] 506 for syntax definitions. 508 INPUTS 509 CONTEXT HANDLE input_context_handle = 0 if new negotiation, 510 context_handle matching 511 key_name if ongoing negotiation 512 OCTET STRING input_token = token specified in the Key 513 field from TKEY RR (from Additional records Section of 514 the client's query) 515 CREDENTIAL HANDLE acceptor_cred_handle = NULL (NULL specifies "use 516 default"). Server MAY instead specify some other valid handle 517 to its credentials. 518 OCTET STRING chan_bindings = Any valid channel bindings 519 as specified in Section 1.1.6 "Channel Bindings" in [RFC2743] 521 OUTPUTS 522 INTEGER major_status 523 CONTEXT_HANDLE output_context_handle 524 OCTET STRING output_token 525 INTEGER minor_status 526 INTERNAL NAME src_name 527 OBJECT IDENTIFIER mech_type 528 BOOLEAN deleg_state 529 BOOLEAN mutual_state 530 BOOLEAN replay_det_state 531 BOOLEAN sequence_state 532 BOOLEAN anon_state 533 BOOLEAN trans_state 534 BOOLEAN prot_ready_state 535 BOOLEAN conf_avail 536 BOOLEAN integ_avail 537 INTEGER lifetime_rec 538 CONTEXT_HANDLE delegated_cred_handle 540 If this is the first call to GSS_Accept_sec_context in a new 541 negotiation, then output_context_handle is stored in the server's 542 key-mapping table as the context_handle that maps to the name of the 543 TKEY record. 545 4.1.3 Send TKEY Query-Response to Client 547 The server MUST respond to the client with a TKEY query response with 548 RCODE = NOERROR, that contains a TKEY record in the answer section. 550 If OUTPUT major_status is one of the following errors the error field 551 in the TKEY record set to BADKEY. 553 GSS_S_DEFECTIVE_TOKEN 554 GSS_S_DEFECTIVE_CREDENTIAL 555 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 556 GSS_S_DUPLICATE_TOKEN 557 GSS_S_OLD_TOKEN 558 GSS_S_NO_CRED 559 GSS_S_CREDENTIALS_EXPIRED 560 GSS_S_BAD_BINDINGS 561 GSS_S_NO_CONTEXT 562 GSS_S_BAD_MECH 563 GSS_S_FAILURE 565 If OUTPUT major_status is set to GSS_S_COMPLETE or 566 GSS_S_CONTINUE_NEEDED then server MUST act as described below. 568 If major_status is GSS_S_COMPLETE the server component of the 569 negotiation is finished. If output_token is non-NULL, then it MUST be 570 returned to the client in a Key Data field of the RDATA in TKEY. The 571 error field in the TKEY record is set to NOERROR. The message MUST be 572 signed with a TSIG record as described in section 5, Sending and 573 Verifying Signed Messages. The context state is advanced to Context 574 Established. Section 4.2 discusses the usage of the security context. 576 If major_status is GSS_S_COMPLETE and output_token is NULL, then the 577 TKEY record received from the client MUST be returned in the Answer 578 section of the response. The message MUST be signed with a TSIG record 579 as described in section 5, Sending and Verifying Signed Messages. The 580 context state is advanced to Context Established. Section 4.2 discusses 581 the usage of the security context. 583 If major_status is GSS_S_CONTINUE, the server component of the 584 negotiation is not yet finished. The server responds to the TKEY 585 query with a standard query response, placing in the answer section a 586 TKEY record containing output_token in the Key Data RDATA field. The 587 error field in the TKEY record is set to NOERROR. The server MUST limit 588 the number of times that a given context is allowed to repeat, to 589 prevent endless looping. Such limit SHOULD NOT exceed value of 10. 591 In all cases except if major_status is GSS_S_COMPLETE and output_token 592 is NULL other TKEY record fields MUST contain the following values: 593 NAME = key_name 594 RDATA 595 Algorithm Name = gss-tsig 596 Mode = 3 (GSS-API negotiation - per [RFC2930]) 597 Key Size = size of output_token in octets 599 The remaining fields in the TKEY RDATA, i.e. Inception, Expiration, 600 Error, Other Size and Data Fields, MUST be set according to [RFC2930]. 602 4.2 Context Established 604 When context negotiation is complete, the handle context_handle 605 is used for the generation and verification of transaction signatures. 606 The handle is valid for a finite amount of time determined by the 607 underlying security mechanism. A server MAY unilaterally terminate 608 a context at any time (see section 4.2.1). 610 Server SHOULD limit the amount of memory used to cache established 611 contexts. 613 The procedures for sending and receiving signed messages are given in 614 section 5, Sending and Verifying Signed Messages. 616 4.2.1 Terminating a Context 618 A server can terminate any established context at any time. The 619 server MAY hint to the client that the context is being deleted by 620 including a TKEY RR in a response with the Mode field set to 5, i.e. 621 "key deletion" [RFC2930]. 622 An active context is deleted by calling GSS_Delete_sec_context 623 providing the associated context_handle. 625 5. Sending and Verifying Signed Messages 627 5.1 Sending a Signed Message - Call GSS_GetMIC 629 The procedure for sending a signature-protected message is specified 630 in [RFC2845]. The data to be passed to the signature routine includes 631 the whole DNS message with specific TSIG variables appended. For the 632 exact format, see [RFC2845]. For this protocol, use the following 633 TSIG variable values: 635 TSIG Record 636 NAME = key_name that identifies this context 637 RDATA 638 Algorithm Name = gss-tsig 640 Assign the remaining fields in the TSIG RDATA appropriate values 641 as described in [RFC2845]. 643 The signature is generated by calling GSS_GetMIC. The following input 644 parameters MUST be used. The outcome of the call is indicated with the 645 output values specified below. Consult Sections 2.3.1 "GSS_GetMIC 646 call" of the RFC 2743[RFC2743] for syntax definitions. 648 INPUTS 649 CONTEXT HANDLE context_handle = context_handle for key_name 650 OCTET STRING message = outgoing message plus TSIG 651 variables (per [RFC2845]) 652 INTEGER qop_req = 0 (0 requests a default 653 value). Caller MAY instead specify other valid value (for 654 details see Section 1.2.4 in [RFC2743]) 656 OUTPUTS 657 INTEGER major_status 658 INTEGER minor_status 659 OCTET STRING per_msg_token 661 If major_status is GSS_S_COMPLETE, then signature generation 662 succeeded. The signature in per_msg_token is inserted into the 663 Signature field of the TSIG RR and the message is transmitted. 665 If major_status is GSS_S_CONTEXT_EXPIRED, GSS_S_CREDENTIALS_EXPIRED or 666 GSS_S_FAILURE the caller MUST delete the security context, return to the 667 uninitialized state and SHOULD negotiate a new security context, as 668 described above in Section 3.1 670 If major_status is GSS_S_NO_CONTEXT, the caller MUST remove the entry 671 for key_name from the (target_ name, key_name, context_handle) mapping 672 table, return to the uninitialized state and SHOULD negotiate a new 673 security context, as described above in Section 3.1 675 If major_status is GSS_S_BAD_QOP, the caller SHOULD repeat the 676 GSS_GetMIC call with allowed QOP value. The number of such repetitions 677 MUST be limited to prevent infinite loops. 679 5.2 Verifying a Signed Message - Call GSS_VerifyMIC 681 The procedure for verifying a signature-protected message is specified 682 in [RFC2845]. 683 The NAME of the TSIG record determines which context_handle maps to 684 the context that MUST be used to verify the signature. If the NAME 685 does not map to an established context, the server MUST send a 686 standard TSIG error response to the client indicating BADKEY in the 687 TSIG error field (as described in [RFC2845]). 689 For the GSS algorithm, a signature is verified by using GSS_VerifyMIC: 690 INPUTS 691 CONTEXT HANDLE context_handle = context_handle for key_name 692 OCTET STRING message = incoming message plus TSIG 693 variables (per [RFC2845]) 694 OCTET STRING per_msg_token = Signature field from TSIG RR 696 OUTPUTS 697 INTEGER major_status 698 INTEGER minor_status 699 INTEGER qop_state 701 If major_status is GSS_S_COMPLETE, the signature is authentic and the 702 message was delivered intact. Per [RFC2845], the timer values of the 703 TSIG record MUST also be valid before considering the message to be 704 authentic. The caller MUST not act on the request or response in the 705 message until these checks are verified. 707 When a server is processing a client request, 708 the server MUST send a standard TSIG error response to the client 709 indicating BADKEY in the TSIG error field as described in [RFC2845], 710 if major_status is set to one of the following values 711 GSS_S_DEFECTIVE_TOKEN 712 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 713 GSS_S_DUPLICATE_TOKEN 714 GSS_S_OLD_TOKEN 715 GSS_S_UNSEQ_TOKEN 716 GSS_S_GAP_TOKEN 717 GSS_S_CONTEXT_EXPIRED 718 GSS_S_NO_CONTEXT 719 GSS_S_FAILURE 721 If the timer values of the TSIG record are invalid, the message MUST 722 NOT be considered authentic. If this error checking fails when a server 723 is processing a client request, the appropriate error response MUST be 724 sent to the client according to [RFC2845]. 726 6. Example usage of GSS-TSIG algorithm 728 This Section describes an example where a Client, client.example.com, 729 and a Server, server.example.com, establish a security context according 730 to the algorithm described above. 732 I. Client initializes security context negotiation 733 To establish a security context with a server, server.example.com, the 734 Client calls GSS_Init_sec_context with the following parameters 735 (Note that some INPUT and OUTPUT parameters not critical for this 736 algorithm are not described in this example) 737 CONTEXT HANDLE input_context_handle = 0 738 INTERNAL NAME targ_name = "DNS@server.example.com" 739 OCTET STRING input_token = NULL 740 BOOLEAN replay_det_req_flag = TRUE 741 BOOLEAN mutual_req_flag = TRUE 743 The OUTPUTS parameters returned by GSS_Init_sec_context include 744 INTEGER major_status = GSS_S_CONTINUE_NEEDED 745 CONTEXT HANDLE output_context_handle context_handle 746 OCTET STRING output_token output_token 747 BOOLEAN replay_det_state = TRUE 748 BOOLEAN mutual_state = TRUE 750 Client verifies that replay_det_state and mutual_state values are 751 TRUE. Since the major_status is GSS_S_CONTINUE_NEEDED, which is a 752 success OUTPUT major_status value, client stores context_handle that 753 maps to "DNS@server.example.com" and proceeds to the next step. 755 II. Client sends a query with QTYPE = TKEY to server 756 Client sends a query with QTYPE = TKEY for a client-generated globally 757 unique domain name string, 789.client.example.com.server.example.com. 758 Query contains a TKEY record in its Additional records section with 759 the following fields (Note that some fields not specific to this 760 algorithm are not specified) 762 NAME = 789.client.example.com.server.example.com. 763 RDATA 764 Algorithm Name = gss-tsig 765 Mode = 3 (GSS-API negotiation - per [RFC2930]) 766 Key Size = size of output_token in octets 767 Key Data = output_token 769 After the key_name 789.client.example.com.server.example.com. 770 is generated it is stored in the client's (target_name, key_name, 771 context_handle) mapping table. 773 III. Server receives a query with QTYPE = TKEY 774 When server receives a query with QTYPE = TKEY, the server verifies 775 that Mode and Algorithm fields in the TKEY record in the Additional 776 records section of the query are set to 3 and "gss-tsig" respectively. 777 It finds that the key_name 789.client.example.com.server.example.com. 778 is not listed in its (key_name, context_handle) mapping table. 780 IV. Server calls GSS_Accept_sec_context 781 To continue security context negotiation server calls 782 GSS_Accept_sec_context with the following parameters (Note that some 783 INPUT and OUTPUT parameters not critical for this algorithm are not 784 described in this example) 785 INPUTS 786 CONTEXT HANDLE input_context_handle = 0 787 OCTET STRING input_token = token specified in the Key 788 field from TKEY RR (from Additional 789 records section of the client's query) 790 The OUTPUTS parameters returned by GSS_Accept_sec_context include 791 INTEGER major_status = GSS_S_CONTINUE_NEEDED 792 CONTEXT_HANDLE output_context_handle context_handle 793 OCTET STRING output_token output_token 795 Server stores the mapping of the 796 789.client.example.com.server.example.com. to OUTPUT context_handle 797 in its (key_name, context_handle) mapping table. 799 V. Server responds to the TKEY query 800 Since the major_status = GSS_S_CONTINUE_NEEDED in the last server's 801 call to GSS_Accept_sec_context, the server responds to the TKEY query 802 placing in the answer section a TKEY record containing output_token in 803 the Key Data RDATA field. The error field in the TKEY record is set to 804 0. The RCODE in the query response is set to NOERROR. 806 VI. Client processes token returned by server 807 When the client receives the TKEY query response from the server, the 808 client calls GSS_Init_sec_context with the following parameters (Note 809 that some INPUT and OUTPUT parameters not critical for this algorithm 810 are not described in this example) 811 CONTEXT HANDLE input_context_handle = the context_handle stored 812 in the client's mapping table entry (DNS@server.example.com., 813 789.client.example.com.server.example.com., context_handle) 814 INTERNAL NAME targ_name = "DNS@server.example.com" 815 OCTET STRING input_token = token from Key field of TKEY 816 record from the Answer section of the server's response 817 BOOLEAN replay_det_req_flag = TRUE 818 BOOLEAN mutual_req_flag = TRUE 820 The OUTPUTS parameters returned by GSS_Init_sec_context include 821 INTEGER major_status = GSS_S_COMPLETE 822 CONTEXT HANDLE output_context_handle = context_handle 823 OCTET STRING output_token = output_token 824 BOOLEAN replay_det_state = TRUE 825 BOOLEAN mutual_state = TRUE 827 Since the major_status is set to GSS_S_COMPLETE the client side 828 security context is established, but since the output_token is not 829 NULL client MUST send a TKEY query to the server as described below. 831 VII. Client sends a query with QTYPE = TKEY to server 832 Client sends to the server a TKEY query for the 833 789.client.example.com.server.example.com. name. Query contains a TKEY 834 record in its Additional records section with the following fields 835 (Note that some INPUT and OUTPUT parameters not critical to this 836 algorithm are not described in this example) 837 NAME = 789.client.example.com.server.example.com. 838 RDATA 839 Algorithm Name = gss-tsig 840 Mode = 3 (GSS-API negotiation - per [RFC2930]) 841 Key Size = size of output_token in octets 842 Key Data = output_token 844 VIII. Server receives a TKEY query 845 When the server receives a TKEY query, the server verifies that Mode 846 and Algorithm fields in the TKEY record in the Additional records 847 section of the query are set to 3 and gss-tsig, repectively. It 848 finds that the key_name 789.client.example.com.server.example.com. is 849 listed in its (key_name, context_handle) mapping table. 851 IX. Server calls GSS_Accept_sec_context 852 To continue security context negotiation server calls 853 GSS_Accept_sec_context with the following parameters (Note that some 854 INPUT and OUTPUT parameters not critical for this algorithm are not 855 described in this example) 856 INPUTS 857 CONTEXT HANDLE input_context_handle = context_handle from the 858 (789.client.example.com.server.example.com., context_handle) 859 entry in the server's mapping table 860 OCTET STRING input_token = token specified in the Key 861 field of TKEY RR (from Additional records Section of 862 the client's query) 864 The OUTPUTS parameters returned by GSS_Accept_sec_context include 865 INTEGER major_status = GSS_S_COMPLETE 866 CONTEXT_HANDLE output_context_handle = context_handle 867 OCTET STRING output_token = NULL 869 Since major_status = GSS_S_COMPLETE, the security context on the 870 server side is established, but the server still needs to respond to 871 the client's TKEY query, as described below. The security context 872 state is advanced to Context Established. 874 X. Server responds to the TKEY query 875 Since the major_status = GSS_S_COMPLETE in the last server's call to 876 GSS_Accept_sec_context and the output_token is NULL, the server 877 responds to the TKEY query placing in the answer section a TKEY record 878 that was sent by the client in the Additional records section of the 879 client's latest TKEY query. In addition to this server places a 880 TSIG record in additional records section of its response. Server 881 calls GSS_GetMIC to generate a signature to include it in the TSIG 882 record. The server specifies the following GSS_GetMIC INPUT 883 parameters: 884 CONTEXT HANDLE context_handle = context_handle from the 885 (789.client.example.com.server.example.com., context_handle) 886 entry in the server's mapping table 887 OCTET STRING message = outgoing message plus TSIG 888 variables (as described in [RFC2845]) 890 The OUTPUTS parameters returned by GSS_GetMIC include 891 INTEGER major_status = GSS_S_COMPLETE 892 OCTET STRING per_msg_token 894 Signature field in the TSIG record is set to per_msg_token. 896 XI. Client processes token returned by server 897 Client receives the TKEY query response from the server. Since the 898 major_status was GSS_S_COMPLETE in the last client's call to 899 GSS_Init_sec_context, the client verifies that the server's response 900 is signed. To validate the signature client calls GSS_VerifyMIC with 901 the following parameters: 903 INPUTS 904 CONTEXT HANDLE context_handle = context_handle for 905 789.client.example.com.server.example.com. key_name 906 OCTET STRING message = incoming message plus TSIG 907 variables (as described in [RFC2845]) 908 OCTET STRING per_msg_token = Signature field from TSIG RR 909 included in the server's query response 911 Since the OUTPUTS parameter major_status = GSS_S_COMPLETE, the 912 signature is validated, security negotiation is complete and the 913 security context state is advanced to Context Established. These 914 client and server will use the established security context to sign 915 and validate the signatures when they exchange packets with each 916 other until the context expires. 918 7. Security Considerations 920 This document describes a protocol for DNS security using GSS-API. 921 The security provided by this protocol is only as effective as the 922 security provided by the underlying GSS mechanisms. 924 All the security considerations from RFC2845, RFC2930 and RFC 2743 925 apply to the protocol described in this document. 927 8. IANA Considerations 929 The authors request that the IANA reserve the TSIG Algorithm name 930 gss-tsig for the use in the Algorithm fields of TKEY and TSIG resource 931 records. This Algorithm name refers to the algorithm described in this 932 document. The requirement to have this name registered with IANA is 933 specified in RFC 2845. 935 9. Conformance 937 The GSS API using SPNEGO [RFC2478] provides maximum flexibility to 938 choose the underlying security mechanisms that enables security context 939 negotiation. GSS API using SPNEGO [RFC2478] enables client and server to 940 negotiate and choose such underlying security mechanisms on the fly. To 941 support such flexibility, DNS clients and servers SHOULD specify SPNEGO 942 mech_type in their GSS API calls. At the same time, in order to 943 guarantee interoperability between DNS clients and servers that support 944 GSS-TSIG it is required that 945 - DNS servers specify SPNEGO mech_type 946 - GSS APIs called by DNS client support Kerberos v5 947 - GSS APIs called by DNS server support SPNEGO [RFC2478] and 948 Kerberos v5. 950 In addition to these, GSS APIs used by DNS client and server MAY also 951 support other underlying security mechanisms. 953 10. Acknowledgements 955 The authors of this document would like to thank the following people 956 for their contribution to this specification: Chuck Chan, Mike Swift, 957 Ram Viswanathan, Olafur Gudmundsson, Donald E. Eastlake 3rd and Erik 958 Nordmark. 960 11. References 962 [RFC2743] J. Linn, "Generic Security Service Application Program 963 Interface, Version 2 , Update 1", RFC 2743, RSA Laboratories, 964 January 2000. 966 [RFC2845] P. Vixie, O. Gudmundsson, D. Eastlake, B. Wellington, 967 "Secret Key Transaction Authentication for DNS (TSIG)", 968 RFC 2845, ISC, NAI Labs, Motorola, Nominum, May, 2000, 970 [RFC2930] D. Eastlake 3rd, "Secret Key Establishment for DNS (TKEY RR)", 971 RFC 2930, Motorola, September 2000. 973 [RFC2535] D. Eastlake 3rd, "Domain Name System Security Extensions," 974 RFC 2535, IBM, March 1999. 976 [RFC2137] D. Eastlake 3rd, "Secure Domain Name System Dynamic Update," 977 RFC 2137, CyberCash, April 1997. 979 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 980 Requirement Levels", BCP 14, RFC 2119, March 1997. 982 [RFC1034] Mockapetris, P., "Domain Names - Concepts and Facilities", 983 STD 13, RFC 1034, November 1987. 985 [RFC1035] Mockapetris, P., "Domain Names - Implementation and 986 Specification", STD 13, RFC 1034, November 1987. 988 [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", 989 RFC 1964, OpenVision Technologies, June 1996. 991 [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)", 992 RFC 2025, Bell-Northern Research, October 1996. 994 [RFC2478] Baize, E., Pinkas, D., "The Simple and Protected GSS-API 995 Negotiation Mechanism", RFC 2478, Bull, December 1998. 997 [ISO11578]"Information technology", "Open Systems 998 Interconnection", "Remote Procedure Call", 999 ISO/IEC 11578:1996, http://www.iso.ch/cate/d2229.html. 1001 12. Author's Addresses 1003 Stuart Kwan Praerit Garg 1004 Microsoft Corporation Microsoft Corporation 1005 One Microsoft Way One Microsoft Way 1006 Redmond, WA 98052 Redmond, WA 98052 1007 USA USA 1008 skwan@microsoft.com praeritg@microsoft.com 1010 James Gilroy Levon Esibov 1011 Microsoft Corporation Microsoft Corporation 1012 One Microsoft Way One Microsoft Way 1013 Redmond, WA 98052 Redmond, WA 98052 1014 USA USA 1015 jamesg@microsoft.com levone@microsoft.com 1017 Randy Hall Jeff Westhead 1018 Lucent Technologies Microsoft Corporation 1019 400 Lapp Road One Microsoft Way 1020 Malvern PA 19355 Redmond, WA 98052 1021 USA USA 1022 randyhall@lucent.com jwesth@microsoft.com