idnits 2.17.1 draft-ietf-dnsext-gss-tsig-00.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 (January 2001) is 8495 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 462, but not defined == Unused Reference: 'RFC2137' is defined on line 905, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2845 (Obsoleted by RFC 8945) -- No information found for draft-ietf-dnsext-tkey- - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'TKEY' ** 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'. Summary: 5 errors (**), 0 flaws (~~), 7 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Stuart Kwan 3 Praerit Garg 4 James Gilroy 5 Levon Esibov 6 Microsoft Corp. 7 July 2000 8 Expires January 2001 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 4: Server Protocol Details...........................................9 53 4.1: Negotiating Context...........................................9 54 4.1.1: Receive TKEY Query from Client...........................10 55 4.1.2: Call GSS_Accept_sec_context..............................10 56 4.1.3: Send TKEY Query-Response to Client.......................11 57 4.2: Context Established..........................................12 58 4.2.1: Terminating a Context....................................12 59 5: Sending and Verifying Signed Messages............................12 60 5.1: Sending a Signed Message - Call GSS_GetMIC...................12 61 5.2: Verifying a Signed Message - Call GSS_VerifyMIC..............13 62 6: Example usage of GSS-TSIG algorithm..............................14 63 7: Security Considerations..........................................18 64 8: IANA Considerations..............................................18 65 9: Conformance......................................................18 66 10:Acknowledgements.................................................18 67 11:References.......................................................19 69 1. Introduction 71 The Secret Key Transaction Signature for DNS (TSIG) [RFC2845] protocol 72 was developed to provide a lightweight end to end authentication and 73 integrity off messages between two DNS entities, such as client and 74 server or server and server. TSIG can be used to protect dynamic update 75 messages, authenticate regular message or to off-load complicated 76 DNSSEC [RFC2535] processing from a client to a server and still allow 77 the client to be assured of the integrity off the answers. 79 The TSIG protocol [RFC2845] is extensible through the definition of new 80 algorithms. This document specifies an algorithm based on the Generic 81 Security Service Application Program Interface (GSS-API) [RFC2743]. 82 GSS-API is a framework that provides an abstraction of security to the 83 application protocol developer. The security services offered can 84 include authentication, integrity, and confidentiality. 86 The GSS-API framework has several benefits: 87 * Mechanism and protocol independence. The underlying mechanisms that 88 realize the security services can be negotiated on the fly and varied 89 over time. For example, a client and server may use Kerberos [RFC1964] 90 for one transaction, whereas that same server may use SPKM [RFC2025] 91 with a different client. 93 * The protocol developer is removed from the responsibility of 94 creating and managing a security infrastructure. For example, the 95 developer does not need to create new key distribution or key 96 management systems. Instead the developer relies on the security 97 service mechanism to manage this on its behalf. 99 The scope of this document is limited to the description of an 100 authentication mechanism only. It does not discuss and/or propose an 101 authorization mechanism. Readers that are unfamiliar with GSS-API 102 concepts are encouraged to read the characteristics and concepts section 103 of [RFC2743] before examining this protocol in detail. It is also 104 assumed that the reader is familiar with [RFC2845], [TKEY], [RFC1034] 105 and [RFC1035]. 107 The key words "MUST", "REQUIRED", "SHOULD", "RECOMMENDED", and 108 "MAY" in this document are to be interpreted as described in RFC 2119 109 [RFC2119]. 111 2. Algorithm Overview 113 In GSS, client and server interact to create a "security context". 114 The security context can be used to create and verify transaction 115 signatures on messages between the two parties. A unique security 116 context is required for each unique connection between client and 117 server. 119 Creating a security context involves a negotiation between client and 120 server. Once a context has been established, it has a finite lifetime 121 for which it can be used to secure messages. Thus there are three 122 states of a context associated with a connection: 124 +----------+ 125 | | 126 V | 127 +---------------+ | 128 | Uninitialized | | 129 | | | 130 +---------------+ | 131 | | 132 V | 133 +---------------+ | 134 | Negotiating | | 135 | Context | | 136 +---------------+ | 137 | | 138 V | 139 +---------------+ | 140 | Context | | 141 | Established | | 142 +---------------+ | 143 | | 144 +----------+ 146 Every connection begins in the uninitialized state. 148 2.1 GSS Details 150 Client and server MUST be locally authenticated and have acquired 151 default credentials before using this protocol as specified in 152 Section 1.1.1 "Credentials" in RFC 2743 [RFC2743]. 154 The GSS-TSIG algorithm consists of two stages: 156 I. Establish security context. The Client and Server use the 157 GSS_Init_sec_context and GSS_Accept_sec_context APIs to generate the 158 tokens that they pass to each other using [TKEY] as a transport 159 mechanism. 161 II. Once the security context is established it is used to generate and 162 verify signatures using GSS_GetMIC and GSS_VerifyMIC APIs. These 163 signatures are exchanged by the Client and Server as a part of the TSIG 164 records exchanged in DNS messages sent between the Client and Server, 165 as described in [RFC2845]. 167 3. Client Protocol Details 169 A unique context is required for each server to which the client sends 170 secure messages. A context is identified by a context handle. A 171 client maintains a mapping of servers to handles, 173 (target_name, key_name, context_handle) 175 The value key_name also identifies a context handle. The key_name is 176 the owner name of the TKEY and TSIG records sent between a client and a 177 server to indicate to each other which context MUST be used to process 178 the current request. 180 3.1 Negotiating Context 182 In GSS, establishing a security context involves the passing of opaque 183 tokens between the client and the server. The client generates the 184 initial token and sends it to the server. The server processes the 185 token and if necessary, returns a subsequent token to the client. The 186 client processes this token, and so on, until the negotiation is 187 complete. The number of times the client and server exchange tokens 188 depends on the underlying security mechanism. A completed negotiation 189 results in a context handle. 191 The TKEY resource record [TKEY] is used as the vehicle to transfer 192 tokens between client and server. The TKEY record is a general 193 mechanism for establishing secret keys for use with TSIG. For more 194 information, see [TKEY]. 196 3.1.1 Call GSS_Init_sec_context 198 To obtain the first token to be sent to a server, a client MUST call 199 GSS_Init_sec_context API. 200 The following input parameters MUST be used. The outcome of the call is 201 indicated with the output values below. Consult Sections 2.2.1 202 "GSS_Init_sec_context call" of [RFC2743] for syntax definitions. 204 INPUTS 205 CREDENTIAL HANDLE claimant_cred_handle = NULL (NULL specifies "use 206 default"). Client MAY instead specify some other valid handle 207 to its credentials. 208 CONTEXT HANDLE input_context_handle = 0 209 INTERNAL NAME targ_name = "DNS/" 210 OBJECT IDENTIFIER mech_type = Underlying security 211 mechanism chosen by implementers. To guarantee 212 interoperability of the implementations of the GSS-TSIG 213 mechanism client MUST specify a valid underlying security 214 mechanism that enables use of Kerberos v5. 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 [TKEY]. 291 TKEY Record 292 NAME = client-generated globally unique domain name string 293 (as described in [TKEY]) 294 RDATA 295 Algorithm Name = gss-tsig 296 Mode = 3 (GSS-API negotiation - per [TKEY]) 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 [TKEY]. 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 [RFC2734] 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 [TKEY]) 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 [TKEY]. 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" [TKEY]. 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 [TKEY]) 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 [TKEY]) 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 provides maximum flexibility to choose the underlying 874 security mechanisms that enables security context negotiation. GSS API 875 enables client and server to negotiate and choose such underlying 876 security mechanisms on the fly. At the same time, in order to guarantee 877 interoperability between clients and servers that support GSS-TSIG it is 878 required that a GSS APIs called by such client and server MUST support 879 Kerberos v5 as an underlying security mechanisms. In addition to this, 880 GSS APIs used by client and server MAY also support other underlying 881 security mechanisms. 883 10. Acknowledgements 885 The authors of this document would like to thank the following people 886 for their contribution to this specification: Chuck Chan, Mike Swift, 887 Ram Viswanathan, Olafur Gudmundsson and Donald E. Eastlake 3rd. 889 11. References 891 [RFC2743] J. Linn, "Generic Security Service Application Program 892 Interface, Version 2 , Update 1", RFC 2743, RSA Laboratories, 893 January 2000. 895 [RFC2845] P. Vixie, O. Gudmundsson, D. Eastlake, B. Wellington, 896 "Secret Key Transaction Signatures for DNS (TSIG)," RFC 2845, 897 ISC, NAI Labs, Motorola, Nominum, May, 2000, 899 [TKEY] D. Eastlake 3rd, "Secret Key Establishment for DNS (TKEY 900 RR)," draft-ietf-dnsext-tkey-*.txt. 902 [RFC2535] D. Eastlake 3rd, "Domain Name System Security Extensions," 903 RFC 2535, IBM, March 1999. 905 [RFC2137] D. Eastlake 3rd, "Secure Domain Name System Dynamic Update," 906 RFC 2137, CyberCash, April 1997. 908 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 909 Requirement Levels", BCP 14, RFC 2119, March 1997. 911 [RFC1034] Mockapetris, P., "Domain Names - Concepts and Facilities", 912 STD 13, RFC 1034, November 1987. 914 [RFC1035] Mockapetris, P., "Domain Names - Implementation and 915 Specification", STD 13, RFC 1034, November 1987. 917 [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", 918 RFC 1964, OpenVision Technologies, June 1996. 920 [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)", 921 RFC 2025, Bell-Northern Research, October 1996. 923 12. Author's Addresses 925 Stuart Kwan Praerit Garg 926 Microsoft Corporation Microsoft Corporation 927 One Microsoft Way One Microsoft Way 928 Redmond, WA 98052 Redmond, WA 98052 929 USA USA 930 skwan@microsoft.com 932 James Gilroy Levon Esibov 933 Microsoft Corporation Microsoft Corporation 934 One Microsoft Way One Microsoft Way 935 Redmond, WA 98052 Redmond, WA 98052 936 USA USA 937 levone@microsoft.com