idnits 2.17.1 draft-ietf-dnsext-gss-tsig-01.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 20 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 338 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. (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.) -- The document date (May 22, 2001) is 8347 days in the past. Is this intentional? 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: 'RFC2734' is mentioned on line 227, but not defined == Unused Reference: 'RFC2137' is defined on line 911, 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 James Gilroy 4 Levon Esibov 5 Microsoft Corp. 6 November 22, 2000 7 Expires May 22, 2001 9 GSS Algorithm for TSIG (GSS-TSIG) 11 Status of this Memo 13 This document is an Internet-Draft and is in full conformance 14 with all provisions of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as 19 Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six 22 months and may be updated, replaced, or obsoleted by other 23 documents at any time. It is inappropriate to use Internet- 24 Drafts as reference material or to cite them other than as 25 "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 Abstract 35 The TSIG protocol provides transaction level authentication for DNS. 36 TSIG is extensible through the definition of new algorithms. This 37 document specifies an algorithm based on the Generic Security Service 38 Application Program Interface (GSS-API) (RFC2743). 40 Table of Contents 42 1: Introduction......................................................2 43 2: Algorithm Overview................................................3 44 2.1: GSS Details...................................................4 45 3: Client Protocol Details...........................................4 46 3.1: Negotiating Context...........................................4 47 3.1.1: Call GSS_Init_sec_context.................................5 48 3.1.2: Send TKEY Query to Server.................................6 49 3.1.3: Receive TKEY Query-Response from Server...................7 50 3.2: Context Established...........................................9 51 4: Server Protocol Details...........................................9 52 4.1: Negotiating Context...........................................9 53 4.1.1: Receive TKEY Query from Client...........................10 54 4.1.2: Call GSS_Accept_sec_context..............................10 55 4.1.3: Send TKEY Query-Response to Client.......................11 56 4.2: Context Established..........................................12 57 4.2.1: Terminating a Context....................................12 58 5: Sending and Verifying Signed Messages............................12 59 5.1: Sending a Signed Message - Call GSS_GetMIC...................12 60 5.2: Verifying a Signed Message - Call GSS_VerifyMIC..............13 61 6: Example usage of GSS-TSIG algorithm..............................14 62 7: Security Considerations..........................................18 63 8: IANA Considerations..............................................18 64 9: Conformance......................................................18 65 10:Acknowledgements.................................................18 66 11:References.......................................................19 68 1. Introduction 70 The Secret Key Transaction Signature for DNS (TSIG) [RFC2845] protocol 71 was developed to provide a lightweight end to end authentication and 72 integrity of messages between two DNS entities, such as client and 73 server or server and server. TSIG can be used to protect dynamic update 74 messages, authenticate regular message or to off-load complicated 75 DNSSEC [RFC2535] processing from a client to a server and still allow 76 the client to be assured of the integrity off the answers. 78 The TSIG protocol [RFC2845] is extensible through the definition of new 79 algorithms. This document specifies an algorithm based on the Generic 80 Security Service Application Program Interface (GSS-API) [RFC2743]. 81 GSS-API is a framework that provides an abstraction of security to the 82 application protocol developer. The security services offered can 83 include authentication, integrity, and confidentiality. 85 The GSS-API framework has several benefits: 86 * Mechanism and protocol independence. The underlying mechanisms that 87 realize the security services can be negotiated on the fly and varied 88 over time. For example, a client and server may use Kerberos [RFC1964] 89 for one transaction, whereas that same server may use SPKM [RFC2025] 90 with a different client. 92 * The protocol developer is removed from the responsibility of 93 creating and managing a security infrastructure. For example, the 94 developer does not need to create new key distribution or key 95 management systems. Instead the developer relies on the security 96 service mechanism to manage this on its behalf. 98 The scope of this document is limited to the description of an 99 authentication mechanism only. It does not discuss and/or propose an 100 authorization mechanism. Readers that are unfamiliar with GSS-API 101 concepts are encouraged to read the characteristics and concepts section 102 of [RFC2743] before examining this protocol in detail. It is also 103 assumed that the reader is familiar with [RFC2845], [RFC2930], [RFC1034] 104 and [RFC1035]. 106 The key words "MUST", "REQUIRED", "SHOULD", "RECOMMENDED", and 107 "MAY" in this document are to be interpreted as described in RFC 2119 108 [RFC2119]. 110 2. Algorithm Overview 112 In GSS, client and server interact to create a "security context". 113 The security context can be used to create and verify transaction 114 signatures on messages between the two parties. A unique security 115 context is required for each unique connection between client and 116 server. 118 Creating a security context involves a negotiation between client and 119 server. Once a context has been established, it has a finite lifetime 120 for which it can be used to secure messages. Thus there are three 121 states of a context associated with a connection: 123 +----------+ 124 | | 125 V | 126 +---------------+ | 127 | Uninitialized | | 128 | | | 129 +---------------+ | 130 | | 131 V | 132 +---------------+ | 133 | Negotiating | | 134 | Context | | 135 +---------------+ | 136 | | 137 V | 138 +---------------+ | 139 | Context | | 140 | Established | | 141 +---------------+ | 142 | | 143 +----------+ 145 Every connection begins in the uninitialized state. 147 2.1 GSS Details 149 Client and server MUST be locally authenticated and have acquired 150 default credentials before using this protocol as specified in 151 Section 1.1.1 "Credentials" in RFC 2743 [RFC2743]. 153 The GSS-TSIG algorithm consists of two stages: 155 I. Establish security context. The Client and Server use the 156 GSS_Init_sec_context and GSS_Accept_sec_context APIs to generate the 157 tokens that they pass to each other using [RFC2930] as a transport 158 mechanism. 160 II. Once the security context is established it is used to generate and 161 verify signatures using GSS_GetMIC and GSS_VerifyMIC APIs. These 162 signatures are exchanged by the Client and Server as a part of the TSIG 163 records exchanged in DNS messages sent between the Client and Server, 164 as described in [RFC2845]. 166 3. Client Protocol Details 168 A unique context is required for each server to which the client sends 169 secure messages. A context is identified by a context handle. A 170 client maintains a mapping of servers to handles, 172 (target_name, key_name, context_handle) 174 The value key_name also identifies a context handle. The key_name is 175 the owner name of the TKEY and TSIG records sent between a client and a 176 server to indicate to each other which context MUST be used to process 177 the current request. 179 3.1 Negotiating Context 181 In GSS, establishing a security context involves the passing of opaque 182 tokens between the client and the server. The client generates the 183 initial token and sends it to the server. The server processes the 184 token and if necessary, returns a subsequent token to the client. The 185 client processes this token, and so on, until the negotiation is 186 complete. The number of times the client and server exchange tokens 187 depends on the underlying security mechanism. A completed negotiation 188 results in a context handle. 190 The TKEY resource record [RFC2930] is used as the vehicle to transfer 191 tokens between client and server. The TKEY record is a general 192 mechanism for establishing secret keys for use with TSIG. For more 193 information, see [RFC2930]. 195 3.1.1 Call GSS_Init_sec_context 197 To obtain the first token to be sent to a server, a client MUST call 198 GSS_Init_sec_context API. 199 The following input parameters MUST be used. The outcome of the call is 200 indicated with the output values below. Consult Sections 2.2.1 201 "GSS_Init_sec_context call" of [RFC2743] for syntax definitions. 203 INPUTS 204 CREDENTIAL HANDLE claimant_cred_handle = NULL (NULL specifies "use 205 default"). Client MAY instead specify some other valid handle 206 to its credentials. 207 CONTEXT HANDLE input_context_handle = 0 208 INTERNAL NAME targ_name = "DNS@" 209 OBJECT IDENTIFIER mech_type = Underlying security 210 mechanism chosen by implementers. To guarantee 211 interoperability of the implementations of the GSS-TSIG 212 mechanism client MUST specify a valid underlying security 213 mechanism that enables use of Kerberos v5 (see Section 9 for 214 more information). 215 OCTET STRING input_token = NULL 216 BOOLEAN replay_det_req_flag = TRUE 217 BOOLEAN mutual_req_flag = TRUE 218 BOOLEAN deleg_req_flag = TRUE 219 BOOLEAN sequence_req_flag = TRUE 220 BOOLEAN anon_req_flag = FALSE 221 BOOLEAN conf_req_flag = TRUE 222 BOOLEAN integ_req_flag = TRUE 223 INTEGER lifetime_req = 0 (0 requests a default 224 value). Client MAY instead specify another upper bound for the 225 lifetime of the context to be established in seconds. 226 OCTET STRING chan_bindings = Any valid channel bindings 227 as specified in Section 1.1.6 "Channel Bindings" in [RFC2734] 229 OUTPUTS 230 INTEGER major_status 231 CONTEXT HANDLE output_context_handle 232 OCTET STRING output_token 233 BOOLEAN replay_det_state 234 BOOLEAN mutual_state 235 INTEGER minor_status 236 OBJECT IDENTIFIER mech_type 237 BOOLEAN deleg_state 238 BOOLEAN sequence_state 239 BOOLEAN anon_state 240 BOOLEAN trans_state 241 BOOLEAN prot_ready_state 242 BOOLEAN conf_avail 243 BOOLEAN integ_avail 244 INTEGER lifetime_rec 246 The client MUST abandon the algorithm if returned major_status is set to 247 one of the following errors: 249 GSS_S_DEFECTIVE_TOKEN 250 GSS_S_DEFECTIVE_CREDENTIAL 251 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 252 GSS_S_NO_CRED 253 GSS_S_CREDENTIALS_EXPIRED 254 GSS_S_BAD_BINDINGS 255 GSS_S_OLD_TOKEN 256 GSS_S_DUPLICATE_TOKEN 257 GSS_S_NO_CONTEXT 258 GSS_S_BAD_NAMETYPE 259 GSS_S_BAD_NAME 260 GSS_S_BAD_MECH 261 GSS_S_FAILURE 263 Success values of major_status are GSS_S_CONTINUE_NEEDED and 264 GSS_S_COMPLETE. The exact success code is important during later 265 processing. 267 The values of replay_det_state and mutual_state indicate if the 268 security package provides replay detection and mutual 269 authentication, respectively. If one or both of these values 270 are FALSE, the client MUST abandon this algorithm. 272 Client's behavior MAY depend on other OUTPUT parameters according 273 to the policy local to the client. 275 The handle output_context_handle is unique to this negotiation and 276 is stored in the client's mapping table as the context_handle that 277 maps to target_name. 279 3.1.2 Send TKEY Query to Server 281 An opaque output_token returned by GSS_Init_sec_context is transmitted 282 to the server in a query request with QTYPE=TKEY. The token itself 283 will be placed in a Key Data field of the RDATA field in the TKEY 284 resource record in the additional records section of the query. The 285 owner name of the TKEY resource record set queried for and the owner 286 name of the supplied TKEY resource record in the additional records 287 section MUST be the same. This name uniquely identifies the security 288 context to both the client and server, and thus the client SHOULD use 289 a value which is globally unique as described in [RFC2930]. 291 TKEY Record 292 NAME = client-generated globally unique domain name string 293 (as described in [RFC2930]) 294 RDATA 295 Algorithm Name = gss-tsig 296 Mode = 3 (GSS-API negotiation - per [RFC2930]) 297 Key Size = size of output_token in octets 298 Key Data = output_token 300 The remaining fields in the TKEY RDATA, i.e. Inception, Expiration, 301 Error, Other Size and Data Fields, MUST be set according to [RFC2930]. 303 The query is transmitted to the server. 305 Note: if the original client call to GSS_Init_sec_context returned any 306 major_status other than GSS_S_CONTINUE_NEEDED or GSS_S_COMPLETE, then 307 the client MUST NOT send TKEY query. 309 3.1.3 Receive TKEY Query-Response from Server 311 Upon the reception of the TKEY query DNS server MUST respond according 312 to the description in Section 4. This Section specifies the behavior 313 of the client after it receives the matching response to its query. 315 The next processing step depends on the value of major_status from the 316 most recent call that client performed to GSS_Init_sec_context: either 317 GSS_S_COMPLETE or GSS_S_CONTINUE. 319 3.1.3.1 Value of major_status == GSS_S_COMPLETE 321 If the last call to GSS_Init_sec_context yielded a major_status value 322 of GSS_S_COMPLETE and a non-NULL output_token was sent to the server, 323 then the client side component of the negotiation is complete and the 324 client is awaiting confirmation from the server. 326 Confirmation is in the form of a query response with RCODE=NOERROR 327 and with the last client supplied TKEY record in the answer section 328 of the query. The response MUST be signed with a TSIG record. The 329 signature in the TSIG record MUST be verified using the procedure 330 detailed in section 5, Sending and Verifying Signed Messages. If the 331 response is not signed, OR if the response is signed but signature is 332 invalid, then an attacker has tampered with the message in transit or 333 has attempted to send the client a false response. The client MUST 334 continue waiting for a response to its last TKEY query until the time 335 period since the client sent last TKEY query expires. Such a time period 336 is specified by the policy local to the client. 338 If the signature is verified the context state is advanced to Context 339 Established. Proceed to section 3.2 for usage of the security context. 341 3.1.3.2 Value of major_status == GSS_S_CONTINUE 343 If the last call to GSS_Init_sec_context yielded a major_status value 344 of GSS_S_CONTINUE, then the negotiation is not yet complete. The server 345 will return to the client a query-response with a TKEY record in the 346 Answer section. Since the message is not signed, the client MUST 347 disregard the error code of the DNS message and the TKEY record. The 348 client MUST pass a token specified in the Key Data field in the TKEY 349 resource record to GSS_Init_sec_context using the same parameters values 350 as in previous call except values for CONTEXT HANDLE 351 input_context_handle and OCTET STRING input_token as described below: 353 INPUTS 354 CONTEXT HANDLE input_context_handle = context_handle (this is the 355 context_handle corresponding to the key_name which is the 356 owner name of the TKEY record in the answer section in the 357 TKEY query response) 358 OCTET STRING input_token = token from Key field of 359 TKEY record 361 Depending on the following OUTPUT values of GSS_Init_sec_context 362 INTEGER major_status 363 OCTET STRING output_token 364 the client MUST take one of the following actions: 366 If OUTPUT major_status is set to one of the following values 367 GSS_S_DEFECTIVE_TOKEN 368 GSS_S_DEFECTIVE_CREDENTIAL 369 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 370 GSS_S_NO_CRED 371 GSS_S_CREDENTIALS_EXPIRED 372 GSS_S_BAD_BINDINGS 373 GSS_S_OLD_TOKEN 374 GSS_S_DUPLICATE_TOKEN 375 GSS_S_NO_CONTEXT 376 GSS_S_BAD_NAMETYPE 377 GSS_S_BAD_NAME 378 GSS_S_BAD_MECH 379 GSS_S_FAILURE 381 then client MUST abandon this negotiation sequence. The client MAY 382 repeat the negotiation sequence starting with the uninitialized state as 383 described in section 3.1. To prevent infinite looping the number of 384 attempts to establish a security context must be limited. 386 If OUTPUT major_status is GSS_S_CONTINUE_NEEDED OR GSS_S_COMPLETE then 387 client MUST act as described below. 389 If major_status is GSS_S_CONTINUE_NEEDED the negotiation is not yet 390 finished. The token output_token MUST be passed to the server in a TKEY 391 record by repeating the negotiation sequence beginning with section 392 3.1.2. The client MUST place a limit on the number of continuations in 393 a context negotiation to prevent endless looping. Such limit SHOULD NOT 394 exceed value of 10. 396 If major_status is GSS_S_COMPLETE and output_token is non-NULL, the 397 client-side component of the negotiation is complete but the token 398 output_token MUST be passed to the server by repeating the negotiation 399 sequence beginning with section 3.1.2. 401 If major_status is GSS_S_COMPLETE and output_token is NULL, context 402 negotiation is complete. The context state is advanced to Context 403 Established. Proceed to section 3.2 for usage of the security context. 405 3.2 Context Established 407 When context negotiation is complete, the handle context_handle MUST be 408 used for the generation and verification of transaction signatures. 410 The procedures for sending and receiving signed messages are described 411 in section 5, Sending and Verifying Signed Messages. 413 4. Server Protocol Details 415 As on the client-side, the result of a successful context negotiation 416 is a context handle used in future generation and verification of the 417 transaction signatures. 419 A server MAY be managing several contexts with several clients. 420 Clients identify their contexts by providing a key name in their 421 request. The server maintains a mapping of key names to handles: 423 (key_name, context_handle) 425 4.1 Negotiating Context 427 A server MUST recognize TKEY queries as security context negotiation 428 messages. 430 4.1.1 Receive TKEY Query from Client 432 Upon receiving a query with QTYPE = TKEY, the server MUST examine 433 whether the Mode and Algorithm Name fields of the TKEY record in the 434 additional records section of the message contain values of 3 and 435 gss-tsig, respectively. If they do, then the (key_name, context_handle) 436 mapping table is searched for the key_name matching the owner name of 437 the TKEY record in the additional records section of the query. If the 438 name is found in the table, the corresponding context_handle is used in 439 subsequent GSS operations. If the name is not found, then the server 440 interprets this as a start of new security context negotiation. 442 4.1.2 Call GSS_Accept_sec_context 444 The server performs its side of a context negotiation by calling 445 GSS_Accept_sec_context. The following input parameters MUST be used. The 446 outcome of the call is indicated with the output values below. Consult 447 Sections 2.2.2 "GSS_Accept_sec_context call" of the RFC 2743[RFC2743] 448 for syntax definitions. 450 INPUTS 451 CONTEXT HANDLE input_context_handle = 0 if new negotiation, 452 context_handle matching 453 key_name if ongoing negotiation 454 OCTET STRING input_token = token specified in the Key 455 field from TKEY RR (from Additional records Section of 456 the client's query) 458 CREDENTIAL HANDLE acceptor_cred_handle = NULL (NULL specifies "use 459 default"). Server MAY instead specify some other valid handle 460 to its credentials. 461 OCTET STRING chan_bindings = Any valid channel bindings 462 as specified in Section 1.1.6 "Channel Bindings" in [RFC2743] 464 OUTPUTS 465 INTEGER major_status 466 CONTEXT_HANDLE output_context_handle 467 OCTET STRING output_token 468 INTEGER minor_status 469 INTERNAL NAME src_name 470 OBJECT IDENTIFIER mech_type 471 BOOLEAN deleg_state 472 BOOLEAN mutual_state 473 BOOLEAN replay_det_state 474 BOOLEAN sequence_state 475 BOOLEAN anon_state 476 BOOLEAN trans_state 477 BOOLEAN prot_ready_state 478 BOOLEAN conf_avail 479 BOOLEAN integ_avail 480 INTEGER lifetime_rec 481 CONTEXT_HANDLE delegated_cred_handle 483 If this is the first call to GSS_Accept_sec_context in a new 484 negotiation, then output_context_handle is stored in the server's 485 key-mapping table as the context_handle that maps to the name of the 486 TKEY record. 488 4.1.3 Send TKEY Query-Response to Client 490 The server MUST respond to the client with a TKEY query response with 491 RCODE = NOERROR, that contains a TKEY record in the answer section. 493 If OUTPUT major_status is one of the following errors the error field 494 in the TKEY record set to BADKEY. 496 GSS_S_DEFECTIVE_TOKEN 497 GSS_S_DEFECTIVE_CREDENTIAL 498 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 499 GSS_S_DUPLICATE_TOKEN 500 GSS_S_OLD_TOKEN 501 GSS_S_NO_CRED 502 GSS_S_CREDENTIALS_EXPIRED 503 GSS_S_BAD_BINDINGS 504 GSS_S_NO_CONTEXT 505 GSS_S_BAD_MECH 506 GSS_S_FAILURE 508 If OUTPUT major_status is set to GSS_S_COMPLETE or 509 GSS_S_CONTINUE_NEEDED then server MUST act as described below. 511 If major_status is GSS_S_COMPLETE the server component of the 512 negotiation is finished. If output_token is non-NULL, then it MUST be 513 returned to the client in a Key Data field of the RDATA in TKEY. The 514 error field in the TKEY record is set to NOERROR. 516 If major_status is GSS_S_COMPLETE and output_token is NULL, then the 517 TKEY record received from the client MUST be returned in the Answer 518 section of the response. The message MUST be signed with a TSIG record 519 as described in section 5, Sending and Verifying Signed Messages. The 520 context state is advanced to Context Established. Section 4.2 discusses 521 the usage of the security context. 523 If major_status is GSS_S_CONTINUE, the server component of the 524 negotiation is not yet finished. The server responds to the TKEY 525 query with a standard query response, placing in the answer section a 526 TKEY record containing output_token in the Key Data RDATA field. The 527 error field in the TKEY record is set to NOERROR. The server MUST limit 528 the number of times that a given context is allowed to repeat, to 529 prevent endless looping. Such limit SHOULD NOT exceed value of 10. 531 In all cases except if major_status is GSS_S_COMPLETE and output_token 532 is NULL other TKEY record fields MUST contain the following values: 533 NAME = key_name 534 RDATA 535 Algorithm Name = gss-tsig 536 Mode = 3 (GSS-API negotiation - per [RFC2930]) 537 Key Size = size of output_token in octets 539 The remaining fields in the TKEY RDATA, i.e. Inception, Expiration, 540 Error, Other Size and Data Fields, MUST be set according to [RFC2930]. 542 4.2 Context Established 544 When context negotiation is complete, the handle context_handle 545 is used for the generation and verification of transaction signatures. 546 The handle is valid for a finite amount of time determined by the 547 underlying security mechanism. A server MAY unilaterally terminate 548 a context at any time (see section 4.2.1). 550 The procedures for sending and receiving signed messages are given in 551 section 5, Sending and Verifying Signed Messages. 553 4.2.1 Terminating a Context 555 A server can terminate any established context at any time. The 556 server MAY hint to the client that the context is being deleted 557 by including a TKEY RR in a response with the Mode field set to 5, i.e. 558 "key deletion" [RFC2930]. 559 An active context is deleted by calling GSS_Delete_sec_context 560 providing the associated context_handle. 562 5. Sending and Verifying Signed Messages 564 5.1 Sending a Signed Message - Call GSS_GetMIC 566 The procedure for sending a signature-protected message is specified 567 in [RFC2845]. The data to be passed to the signature routine includes 568 the whole DNS message with specific TSIG variables appended. For the 569 exact format, see [RFC2845]. For this protocol, use the following 570 TSIG variable values: 572 TSIG Record 573 NAME = key_name that identifies this context 574 RDATA 575 Algorithm Name = gss-tsig 577 Assign the remaining fields in the TSIG RDATA appropriate values 578 as described in [RFC2845]. 580 The signature is generated by calling GSS_GetMIC. The following input 581 parameters MUST be used. The outcome of the call is indicated with the 582 output values specified below. Consult Sections 2.3.1 "GSS_GetMIC 583 call" of the RFC 2743[RFC2743] for syntax definitions. 585 INPUTS 586 CONTEXT HANDLE context_handle = context_handle for key_name 587 OCTET STRING message = outgoing message plus TSIG 588 variables (per [RFC2845]) 589 INTEGER qop_req = 0 (0 requests a default 590 value). Caller MAY instead specify other valid value (for 591 details see Section 1.2.4 in [RFC2743]) 593 OUTPUTS 594 INTEGER major_status 595 INTEGER minor_status 596 OCTET STRING per_msg_token 598 If major_status is GSS_S_COMPLETE, then signature generation 599 succeeded. The signature in per_msg_token is inserted into the 600 Signature field of the TSIG RR and the message is transmitted. 602 If major_status is GSS_S_CONTEXT_EXPIRED, GSS_S_CREDENTIALS_EXPIRED or 603 GSS_S_FAILURE the caller MUST delete the security context, return to the 604 uninitialized state and SHOULD negotiate a new security context, as 605 described above in Section 3.1 607 If major_status is GSS_S_NO_CONTEXT, the caller MUST remove the entry 608 for key_name from the (target_ name, key_name, context_handle) mapping 609 table, return to the uninitialized state and SHOULD negotiate a new 610 security context, as described above in Section 3.1 612 If major_status is GSS_S_BAD_QOP, the caller SHOULD repeat the 613 GSS_GetMIC call with allowed QOP value. The number of such repetitions 614 MUST be limited to prevent infinite loops. 616 5.2 Verifying a Signed Message - Call GSS_VerifyMIC 618 The procedure for verifying a signature-protected message is specified 619 in [RFC2845]. 620 The NAME of the TSIG record determines which context_handle maps to 621 the context that MUST be used to verify the signature. If the NAME 622 does not map to an established context, the server MUST send a 623 standard TSIG error response to the client indicating BADKEY in the 624 TSIG error field (as described in [RFC2845]). 626 For the GSS algorithm, a signature is verified by using GSS_VerifyMIC: 628 INPUTS 629 CONTEXT HANDLE context_handle = context_handle for key_name 630 OCTET STRING message = incoming message plus TSIG 631 variables (per [RFC2845]) 632 OCTET STRING per_msg_token = Signature field from TSIG RR 634 OUTPUTS 635 INTEGER major_status 636 INTEGER minor_status 637 INTEGER qop_state 639 If major_status is GSS_S_COMPLETE, the signature is authentic and the 640 message was delivered intact. Per [RFC2845], the timer values of the 641 TSIG record MUST also be valid before considering the message to be 642 authentic. The caller MUST not act on the request or response in the 643 message until these checks are verified. 645 If major_status is set to one of the following values, the negotiated 646 context is no longer valid. 647 GSS_S_DEFECTIVE_TOKEN 648 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 649 GSS_S_DUPLICATE_TOKEN 650 GSS_S_OLD_TOKEN 651 GSS_S_UNSEQ_TOKEN 652 GSS_S_GAP_TOKEN 653 GSS_S_CONTEXT_EXPIRED 654 GSS_S_NO_CONTEXT 655 GSS_S_FAILURE 657 If this failure occurs when a server is processing a client request, 658 the server MUST send a standard TSIG error response to the client 659 indicating BADKEY in the TSIG error field as described in [RFC2845]. 661 If the timer values of the TSIG record are invalid, the message MUST 662 NOT be considered authentic. If this error checking fails when a server 663 is processing a client request, the appropriate error response MUST be 664 sent to the client according to [RFC2845]. 666 6. Example usage of GSS-TSIG algorithm 668 This Section describes an example where a Client, client.example.com, 669 and a Server, server.example.com, establish a security context according 670 to the algorithm described above. 672 I. Client initializes security context negotiation 673 To establish a security context with a server, server.example.com, the 674 Client calls GSS_Init_sec_context with the following parameters 675 (Note that some INPUT and OUTPUT parameters not critical for this 676 algorithm are not described in this example) 677 CONTEXT HANDLE input_context_handle = 0 678 INTERNAL NAME targ_name = "DNS/ server.example.com" 679 OCTET STRING input_token = NULL 680 BOOLEAN replay_det_req_flag = TRUE 681 BOOLEAN mutual_req_flag = TRUE 683 The OUTPUTS parameters returned by GSS_Init_sec_context include 684 INTEGER major_status = GSS_S_CONTINUE_NEEDED 685 CONTEXT HANDLE output_context_handle context_handle 686 OCTET STRING output_token output_token 687 BOOLEAN replay_det_state = TRUE 688 BOOLEAN mutual_state = TRUE 690 Client verifies that replay_det_state and mutual_state values are 691 TRUE. Since the major_status is GSS_S_CONTINUE_NEEDED, which is a 692 success OUTPUT major_status value, client stores context_handle that 693 maps to "DNS/server.example.com" and proceeds to the next step. 695 II. Client sends a query with QTYPE = TKEY to server 696 Client sends a query with QTYPE = TKEY for a client-generated globally 697 unique domain name string, 789.client.example.com.server.example.com. 698 Query contains a TKEY record in its Additional records section with 699 the following fields (Note that some fields not specific to this 700 algorithm are not specified) 701 NAME = 789.client.example.com.server.example.com. 702 RDATA 703 Algorithm Name = gss-tsig 704 Mode = 3 (GSS-API negotiation - per [RFC2930]) 705 Key Size = size of output_token in octets 706 Key Data = output_token 708 After the key_name 789.client.example.com.server.example.com. 709 is generated it is stored in the client's (target_name, key_name, 710 context_handle) mapping table. 712 III. Server receives a query with QTYPE = TKEY 713 When server receives a query with QTYPE = TKEY, the server verifies 714 that Mode and Algorithm fields in the TKEY record in the Additional 715 records section of the query are set to 3 and "gss-tsig" respectively. 716 It finds that the key_name 789.client.example.com.server.example.com. 717 is not listed in its (key_name, context_handle) mapping table. 719 IV. Server calls GSS_Accept_sec_context 720 To continue security context negotiation server calls 721 GSS_Accept_sec_context with the following parameters (Note that some 722 INPUT and OUTPUT parameters not critical for this algorithm are not 723 described in this example) 724 INPUTS 725 CONTEXT HANDLE input_context_handle = 0 726 OCTET STRING input_token = token specified in the Key 727 field from TKEY RR (from Additional 728 records section of the client's query) 729 The OUTPUTS parameters returned by GSS_Accept_sec_context include 730 INTEGER major_status = GSS_S_CONTINUE_NEEDED 731 CONTEXT_HANDLE output_context_handle context_handle 732 OCTET STRING output_token output_token 734 Server stores the mapping of the 735 789.client.example.com.server.example.com. to OUTPUT context_handle 736 in its (key_name, context_handle) mapping table. 738 V. Server responds to the TKEY query 739 Since the major_status = GSS_S_CONTINUE_NEEDED in the last server's 740 call to GSS_Accept_sec_context, the server responds to the TKEY query 741 placing in the answer section a TKEY record containing output_token in 742 the Key Data RDATA field. The error field in the TKEY record is set to 743 0. The RCODE in the query response is set to NOERROR. 745 VI. Client processes token returned by server 746 When the client receives the TKEY query response from the server, the 747 client calls GSS_Init_sec_context with the following parameters (Note 748 that some INPUT and OUTPUT parameters not critical for this algorithm 749 are not described in this example) 750 CONTEXT HANDLE input_context_handle = the context_handle stored 751 in the client's mapping table entry (DNS/server.example.com., 752 789.client.example.com.server.example.com., context_handle) 753 INTERNAL NAME targ_name = "DNS/server.example.com" 754 OCTET STRING input_token = token from Key field of TKEY 755 record from the Answer section of the server's response 756 BOOLEAN replay_det_req_flag = TRUE 757 BOOLEAN mutual_req_flag = TRUE 759 The OUTPUTS parameters returned by GSS_Init_sec_context include 760 INTEGER major_status = GSS_S_COMPLETE 761 CONTEXT HANDLE output_context_handle = context_handle 762 OCTET STRING output_token = output_token 763 BOOLEAN replay_det_state = TRUE 764 BOOLEAN mutual_state = TRUE 766 Since the major_status is set to GSS_S_COMPLETE the client side 767 security context is established, but since the output_token is not 768 NULL client MUST send a TKEY query to the server as described below. 770 VII. Client sends a query with QTYPE = TKEY to server 771 Client sends to the server a TKEY query for the 772 789.client.example.com.server.example.com. name. Query contains a TKEY 773 record in its Additional records section with the following fields 774 (Note that some INPUT and OUTPUT parameters not critical to this 775 algorithm are not described in this example) 776 NAME = 789.client.example.com.server.example.com. 777 RDATA 778 Algorithm Name = gss-tsig 779 Mode = 3 (GSS-API negotiation - per [RFC2930]) 780 Key Size = size of output_token in octets 781 Key Data = output_token 783 VIII. Server receives a TKEY query 784 When the server receives a TKEY query, the server verifies that Mode 785 and Algorithm fields in the TKEY record in the Additional records 786 section of the query are set to 3 and gss-tsig, repectively. It 787 finds that the key_name 789.client.example.com.server.example.com. is 788 listed in its (key_name, context_handle) mapping table. 790 IX. Server calls GSS_Accept_sec_context 791 To continue security context negotiation server calls 792 GSS_Accept_sec_context with the following parameters (Note that some 793 INPUT and OUTPUT parameters not critical for this algorithm are not 794 described in this example) 795 INPUTS 796 CONTEXT HANDLE input_context_handle = context_handle from the 797 (789.client.example.com.server.example.com., context_handle) 798 entry in the server's mapping table 799 OCTET STRING input_token = token specified in the Key 800 field of TKEY RR (from Additional records Section of 801 the client's query) 803 The OUTPUTS parameters returned by GSS_Accept_sec_context include 804 INTEGER major_status = GSS_S_COMPLETE 805 CONTEXT_HANDLE output_context_handle = context_handle 806 OCTET STRING output_token = NULL 808 Since major_status = GSS_S_COMPLETE, the security context on the 809 server side is established, but the server still needs to respond to 810 the client's TKEY query, as described below. The security context 811 state is advanced to Context Established. 813 X. Server responds to the TKEY query 814 Since the major_status = GSS_S_COMPLETE in the last server's call to 815 GSS_Accept_sec_context and the output_token is NULL, the server 816 responds to the TKEY query placing in the answer section a TKEY record 817 that was sent by the client in the Additional records section of the 818 client's latest TKEY query. In addition to this server places a 819 TSIG record in additional records section of its response. Server 820 calls GSS_GetMIC to generate a signature to include it in the TSIG 821 record. The server specifies the following GSS_GetMIC INPUT 822 parameters: 823 CONTEXT HANDLE context_handle = context_handle from the 824 (789.client.example.com.server.example.com., context_handle) 825 entry in the server's mapping table 826 OCTET STRING message = outgoing message plus TSIG 827 variables (as described in [RFC2845]) 829 The OUTPUTS parameters returned by GSS_GetMIC include 830 INTEGER major_status = GSS_S_COMPLETE 831 OCTET STRING per_msg_token 833 Signature field in the TSIG record is set to per_msg_token. 835 XI. Client processes token returned by server 836 Client receives the TKEY query response from the server. Since the 837 major_status was GSS_S_COMPLETE in the last client's call to 838 GSS_Init_sec_context, the client verifies that the server's response 839 is signed. To validate the signature client calls GSS_VerifyMIC with 840 the following parameters: 842 INPUTS 843 CONTEXT HANDLE context_handle = context_handle for 844 789.client.example.com.server.example.com. key_name 845 OCTET STRING message = incoming message plus TSIG 846 variables (as described in [RFC2845]) 847 OCTET STRING per_msg_token = Signature field from TSIG RR 848 included in the server's query response 850 Since the OUTPUTS parameter major_status = GSS_S_COMPLETE, the 851 signature is validated, security negotiation is complete and the 852 security context state is advanced to Context Established. These 853 client and server will use the established security context to sign 854 and validate the signatures when they exchange packets with each 855 other until the context expires. 857 7. Security Considerations 859 This document describes a protocol for DNS security using GSS-API. 860 The security provided by this protocol is only as effective as the 861 security provided by the underlying GSS mechanisms. 863 8. IANA Considerations 865 The authors request that the IANA reserve the TSIG Algorithm name 866 gss-tsig for the use in the Algorithm fields of TKEY and TSIG resource 867 records. This Algorithm name refers to the algorithm described in this 868 document. The requirement to have this name registered with IANA is 869 specified in RFC 2845. 871 9. Conformance 873 The GSS API using SPNEGO [RFC2478] provides maximum flexibility to 874 choose the underlying security mechanisms that enables security context 875 negotiation. GSS API using SPNEGO [RFC2478] enables client and server to 876 negotiate and choose such underlying security mechanisms on the fly. To 877 support such flexibility, DNS clients and servers SHOULD specify SPNEGO 878 mech_type in their GSS API calls. At the same time, in order to 879 guarantee interoperability between DNS clients and servers that support 880 GSS-TSIG it is required that 881 - DNS servers specify SPNEGO mech_type 882 - GSS APIs called by DNS client support Kerberos v5 883 - GSS APIs called by DNS server support SPNEGO [RFC2478] and 884 Kerberos v5. 886 In addition to these, GSS APIs used by DNS client and server MAY also 887 support other underlying security mechanisms. 889 10. Acknowledgements 891 The authors of this document would like to thank the following people 892 for their contribution to this specification: Chuck Chan, Mike Swift, 893 Ram Viswanathan, Olafur Gudmundsson and Donald E. Eastlake 3rd. 895 11. References 897 [RFC2743] J. Linn, "Generic Security Service Application Program 898 Interface, Version 2 , Update 1", RFC 2743, RSA Laboratories, 899 January 2000. 901 [RFC2845] P. Vixie, O. Gudmundsson, D. Eastlake, B. Wellington, 902 "Secret Key Transaction Signatures for DNS (TSIG)", RFC 2845, 903 ISC, NAI Labs, Motorola, Nominum, May, 2000, 905 [RFC2930] D. Eastlake 3rd, "Secret Key Establishment for DNS (TKEY RR)", 906 RFC 2930, Motorola, September 2000. 908 [RFC2535] D. Eastlake 3rd, "Domain Name System Security Extensions," 909 RFC 2535, IBM, March 1999. 911 [RFC2137] D. Eastlake 3rd, "Secure Domain Name System Dynamic Update," 912 RFC 2137, CyberCash, April 1997. 914 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 915 Requirement Levels", BCP 14, RFC 2119, March 1997. 917 [RFC1034] Mockapetris, P., "Domain Names - Concepts and Facilities", 918 STD 13, RFC 1034, November 1987. 920 [RFC1035] Mockapetris, P., "Domain Names - Implementation and 921 Specification", STD 13, RFC 1034, November 1987. 923 [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", 924 RFC 1964, OpenVision Technologies, June 1996. 926 [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)", 927 RFC 2025, Bell-Northern Research, October 1996. 929 [RFC2478] Baize, E., Pinkas, D., "The Simple and Protected GSS-API 930 Negotiation Mechanism", RFC 2478, Bull, December 1998. 932 12. Author's Addresses 934 Stuart Kwan Praerit Garg 935 Microsoft Corporation Microsoft Corporation 936 One Microsoft Way One Microsoft Way 937 Redmond, WA 98052 Redmond, WA 98052 938 USA USA 939 skwan@microsoft.com 941 James Gilroy Levon Esibov 942 Microsoft Corporation Microsoft Corporation 943 One Microsoft Way One Microsoft Way 944 Redmond, WA 98052 Redmond, WA 98052 945 USA USA 946 levone@microsoft.com