idnits 2.17.1 draft-ietf-dnsext-gss-tsig-04.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 349 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 298, but not defined == Unused Reference: 'RFC2137' is defined on line 963, 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 November 19, 2001 James Gilroy 4 Expires May 19, 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 Signature for DNS (TSIG) [RFC2845] protocol 73 was developed to provide a lightweight authentication and integrity of 74 messages between two DNS entities, such as client and server or server 75 and server. TSIG can be used to protect dynamic update messages, 76 authenticate regular message or to off-load complicated DNSSEC 77 [RFC2535] processing from a client to a server and still allow the 78 client to be assured of the integrity off 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 The client MUST abandon the algorithm if returned major_status is set to 255 one of the following errors: 257 GSS_S_DEFECTIVE_TOKEN 258 GSS_S_DEFECTIVE_CREDENTIAL 259 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 260 GSS_S_NO_CRED 261 GSS_S_CREDENTIALS_EXPIRED 262 GSS_S_BAD_BINDINGS 263 GSS_S_OLD_TOKEN 264 GSS_S_DUPLICATE_TOKEN 265 GSS_S_NO_CONTEXT 266 GSS_S_BAD_NAMETYPE 267 GSS_S_BAD_NAME 268 GSS_S_BAD_MECH 269 GSS_S_FAILURE 271 Success values of major_status are GSS_S_CONTINUE_NEEDED and 272 GSS_S_COMPLETE. The exact success code is important during later 273 processing. 275 The values of replay_det_state and mutual_state indicate if the 276 security package provides replay detection and mutual authentication, 277 respectively. If returned major_status is GSS_S_COMPLETE AND one or both 278 of these values are FALSE, the client MUST abandon this algorithm. 280 Client's behavior MAY depend on other OUTPUT parameters according 281 to the policy local to the client. 283 The handle output_context_handle is unique to this negotiation and 284 is stored in the client's mapping table as the context_handle that 285 maps to target_name. 287 3.1.2 Send TKEY Query to Server 289 An opaque output_token returned by GSS_Init_sec_context is transmitted 290 to the server in a query request with QTYPE=TKEY. The token itself 291 will be placed in a Key Data field of the RDATA field in the TKEY 292 resource record in the additional records section of the query. The 293 owner name of the TKEY resource record set queried for and the owner 294 name of the supplied TKEY resource record in the additional records 295 section MUST be the same. This name uniquely identifies the security 296 context to both the client and server, and thus the client SHOULD use 297 a value which is globally unique as described in [RFC2930]. To achieve 298 global uniqueness, the name MAY contain a UUID/GUID [ISO11578]. 300 TKEY Record 301 NAME = client-generated globally unique domain name string 302 (as described in [RFC2930]) 303 RDATA 304 Algorithm Name = gss-tsig 305 Mode = 3 (GSS-API negotiation - per [RFC2930]) 306 Key Size = size of output_token in octets 307 Key Data = output_token 309 The remaining fields in the TKEY RDATA, i.e. Inception, Expiration, 310 Error, Other Size and Data Fields, MUST be set according to [RFC2930]. 312 The query is transmitted to the server. 314 Note: if the original client call to GSS_Init_sec_context returned any 315 major_status other than GSS_S_CONTINUE_NEEDED or GSS_S_COMPLETE, then 316 the client MUST NOT send TKEY query. 318 3.1.3 Receive TKEY Query-Response from Server 320 Upon the reception of the TKEY query DNS server MUST respond according 321 to the description in Section 4. This Section specifies the behavior 322 of the client after it receives the matching response to its query. 324 The next processing step depends on the value of major_status from the 325 most recent call that client performed to GSS_Init_sec_context: either 326 GSS_S_COMPLETE or GSS_S_CONTINUE. 328 3.1.3.1 Value of major_status == GSS_S_COMPLETE 330 If the last call to GSS_Init_sec_context yielded a major_status value 331 of GSS_S_COMPLETE and a non-NULL output_token was sent to the server, 332 then the client side component of the negotiation is complete and the 333 client is awaiting confirmation from the server. 335 Confirmation is in the form of a query response with RCODE=NOERROR 336 and with the last client supplied TKEY record in the answer section 337 of the query. The response MUST be signed with a TSIG record. The 338 signature in the TSIG record MUST be verified using the procedure 339 detailed in section 5, Sending and Verifying Signed Messages. If the 340 response is not signed, OR if the response is signed but signature is 341 invalid, then an attacker has tampered with the message in transit or 342 has attempted to send the client a false response. The client MAY 343 continue waiting for a response to its last TKEY query until the time 344 period since the client sent last TKEY query expires. Such a time period 345 is specified by the policy local to the client. This is a new option 346 that allows DNS client to accept multiple answers for one query ID and 347 select one (not necessarily the first one) based on some criteria. 349 If the signature is verified the context state is advanced to Context 350 Established. Proceed to section 3.2 for usage of the security context. 352 3.1.3.2 Value of major_status == GSS_S_CONTINUE 354 If the last call to GSS_Init_sec_context yielded a major_status value 355 of GSS_S_CONTINUE, then the negotiation is not yet complete. The server 356 will return to the client a query-response with a TKEY record in the 357 Answer section. If the DNS message error is not NO_ERROR or error field 358 in the TKEY record is not 0 (i.e. no error), then the client MUST 359 abandon this negotiation sequence. The client MUST delete an active 360 context by calling GSS_Delete_sec_context providing the associated 361 context_handle. The client MAY repeat the negotiation sequence starting 362 with the uninitialized state as described in section 3.1. To prevent 363 infinite looping the number of attempts to establish a security context 364 MUST be limited to ten or less. 366 If the DNS message error is NO_ERROR and error filed in the TKEY record 367 is 0 (i.e. no error), then the client MUST pass a token specified in the 368 Key Data field in the TKEY resource record to GSS_Init_sec_context 369 using the same parameters values as in previous call except values for 370 CONTEXT HANDLE input_context_handle and OCTET STRING input_token as 371 described below: 373 INPUTS 374 CONTEXT HANDLE input_context_handle = context_handle (this is the 375 context_handle corresponding to the key_name which is the 376 owner name of the TKEY record in the answer section in the 377 TKEY query response) 378 OCTET STRING input_token = token from Key field of 379 TKEY record 381 Depending on the following OUTPUT values of GSS_Init_sec_context 382 INTEGER major_status 383 OCTET STRING output_token 384 the client MUST take one of the following actions: 386 If OUTPUT major_status is set to one of the following values 387 GSS_S_DEFECTIVE_TOKEN 388 GSS_S_DEFECTIVE_CREDENTIAL 389 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 390 GSS_S_NO_CRED 391 GSS_S_CREDENTIALS_EXPIRED 392 GSS_S_BAD_BINDINGS 393 GSS_S_OLD_TOKEN 394 GSS_S_DUPLICATE_TOKEN 395 GSS_S_NO_CONTEXT 396 GSS_S_BAD_NAMETYPE 397 GSS_S_BAD_NAME 398 GSS_S_BAD_MECH 399 GSS_S_FAILURE 401 the client MUST abandon this negotiation sequence. The client MUST 402 delete an active context by calling GSS_Delete_sec_context providing 403 the associated context_handle. The client MAY repeat the negotiation 404 sequence starting with the uninitialized state as described in section 405 3.1. To prevent infinite looping the number of attempts to establish a 406 security context MUST be limited to ten or less. 408 If OUTPUT major_status is GSS_S_CONTINUE_NEEDED OR GSS_S_COMPLETE then 409 client MUST act as described below. 411 If the response from the server was signed, and the OUTPUT major_status 412 is GSS_S_COMPLETE,then the signature in the TSIG record MUST be verified 413 using the procedure detailed in section 5, Sending and Verifying Signed 414 Messages. If the signature is invalid, then the client MUST abandon this 415 negotiation sequence. The client MUST delete an active context by 416 calling GSS_Delete_sec_context providing the associated context_handle. 417 The client MAY repeat the negotiation sequence starting with the 418 uninitialized state as described in section 3.1. To prevent infinite 419 looping the number of attempts to establish a security context MUST be 420 limited to ten or less. 422 If major_status is GSS_S_CONTINUE_NEEDED the negotiation is not yet 423 finished. The token output_token MUST be passed to the server in a TKEY 424 record by repeating the negotiation sequence beginning with section 425 3.1.2. The client MUST place a limit on the number of continuations in 426 a context negotiation to prevent endless looping. Such limit SHOULD NOT 427 exceed value of 10. 429 If major_status is GSS_S_COMPLETE and output_token is non-NULL, the 430 client-side component of the negotiation is complete but the token 431 output_token MUST be passed to the server by repeating the negotiation 432 sequence beginning with section 3.1.2. 434 If major_status is GSS_S_COMPLETE and output_token is NULL, context 435 negotiation is complete. The context state is advanced to Context 436 Established. Proceed to section 3.2 for usage of the security context. 438 3.2 Context Established 440 When context negotiation is complete, the handle context_handle MUST be 441 used for the generation and verification of transaction signatures. 443 The procedures for sending and receiving signed messages are described 444 in section 5, Sending and Verifying Signed Messages. 446 3.2.1 Terminating a Context 448 When the client is not intended to continue using the established 449 security context, the client SHOULD delete an active context by 450 calling GSS_Delete_sec_context providing the associated context_handle, 451 AND client SHOULD delete the established context on the DNS server 452 by using TKEY RR with the Mode field set to 5, i.e. "key deletion" 453 [RFC2930]. 455 4. Server Protocol Details 457 As on the client-side, the result of a successful context negotiation 458 is a context handle used in future generation and verification of the 459 transaction signatures. 461 A server MAY be managing several contexts with several clients. 462 Clients identify their contexts by providing a key name in their 463 request. The server maintains a mapping of key names to handles: 465 (key_name, context_handle) 467 4.1 Negotiating Context 469 A server MUST recognize TKEY queries as security context negotiation 470 messages. 472 4.1.1 Receive TKEY Query from Client 474 Upon receiving a query with QTYPE = TKEY, the server MUST examine 475 whether the Mode and Algorithm Name fields of the TKEY record in the 476 additional records section of the message contain values of 3 and 477 gss-tsig, respectively. If they do, then the (key_name, context_handle) 478 mapping table is searched for the key_name matching the owner name of 479 the TKEY record in the additional records section of the query. If the 480 name is found in the table and the security context for this name is 481 established and not expired, then the server MUST respond to the query 482 with BADNAME error in the TKEY error field. If the name is found in the 483 table and the security context is not established, the corresponding 484 context_handle is used in subsequent GSS operations. If the name is not 485 found, then the server interprets this query as a start of new security 486 context negotiation. 488 4.1.2 Call GSS_Accept_sec_context 490 The server performs its side of a context negotiation by calling 491 GSS_Accept_sec_context. The following input parameters MUST be used. The 492 outcome of the call is indicated with the output values below. Consult 493 Sections 2.2.2 "GSS_Accept_sec_context call" of the RFC 2743[RFC2743] 494 for syntax definitions. 496 INPUTS 497 CONTEXT HANDLE input_context_handle = 0 if new negotiation, 498 context_handle matching 499 key_name if ongoing negotiation 500 OCTET STRING input_token = token specified in the Key 501 field from TKEY RR (from Additional records Section of 502 the client's query) 503 CREDENTIAL HANDLE acceptor_cred_handle = NULL (NULL specifies "use 504 default"). Server MAY instead specify some other valid handle 505 to its credentials. 506 OCTET STRING chan_bindings = Any valid channel bindings 507 as specified in Section 1.1.6 "Channel Bindings" in [RFC2743] 509 OUTPUTS 510 INTEGER major_status 511 CONTEXT_HANDLE output_context_handle 512 OCTET STRING output_token 513 INTEGER minor_status 514 INTERNAL NAME src_name 515 OBJECT IDENTIFIER mech_type 516 BOOLEAN deleg_state 517 BOOLEAN mutual_state 518 BOOLEAN replay_det_state 519 BOOLEAN sequence_state 520 BOOLEAN anon_state 521 BOOLEAN trans_state 522 BOOLEAN prot_ready_state 523 BOOLEAN conf_avail 524 BOOLEAN integ_avail 525 INTEGER lifetime_rec 526 CONTEXT_HANDLE delegated_cred_handle 528 If this is the first call to GSS_Accept_sec_context in a new 529 negotiation, then output_context_handle is stored in the server's 530 key-mapping table as the context_handle that maps to the name of the 531 TKEY record. 533 4.1.3 Send TKEY Query-Response to Client 535 The server MUST respond to the client with a TKEY query response with 536 RCODE = NOERROR, that contains a TKEY record in the answer section. 538 If OUTPUT major_status is one of the following errors the error field 539 in the TKEY record set to BADKEY. 541 GSS_S_DEFECTIVE_TOKEN 542 GSS_S_DEFECTIVE_CREDENTIAL 543 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 544 GSS_S_DUPLICATE_TOKEN 545 GSS_S_OLD_TOKEN 546 GSS_S_NO_CRED 547 GSS_S_CREDENTIALS_EXPIRED 548 GSS_S_BAD_BINDINGS 549 GSS_S_NO_CONTEXT 550 GSS_S_BAD_MECH 551 GSS_S_FAILURE 553 If OUTPUT major_status is set to GSS_S_COMPLETE or 554 GSS_S_CONTINUE_NEEDED then server MUST act as described below. 556 If major_status is GSS_S_COMPLETE the server component of the 557 negotiation is finished. If output_token is non-NULL, then it MUST be 558 returned to the client in a Key Data field of the RDATA in TKEY. The 559 error field in the TKEY record is set to NOERROR. The message MUST be 560 signed with a TSIG record as described in section 5, Sending and 561 Verifying Signed Messages. The context state is advanced to Context 562 Established. Section 4.2 discusses the usage of the security context. 564 If major_status is GSS_S_COMPLETE and output_token is NULL, then the 565 TKEY record received from the client MUST be returned in the Answer 566 section of the response. The message MUST be signed with a TSIG record 567 as described in section 5, Sending and Verifying Signed Messages. The 568 context state is advanced to Context Established. Section 4.2 discusses 569 the usage of the security context. 571 If major_status is GSS_S_CONTINUE, the server component of the 572 negotiation is not yet finished. The server responds to the TKEY 573 query with a standard query response, placing in the answer section a 574 TKEY record containing output_token in the Key Data RDATA field. The 575 error field in the TKEY record is set to NOERROR. The server MUST limit 576 the number of times that a given context is allowed to repeat, to 577 prevent endless looping. Such limit SHOULD NOT exceed value of 10. 579 In all cases except if major_status is GSS_S_COMPLETE and output_token 580 is NULL other TKEY record fields MUST contain the following values: 581 NAME = key_name 582 RDATA 583 Algorithm Name = gss-tsig 584 Mode = 3 (GSS-API negotiation - per [RFC2930]) 585 Key Size = size of output_token in octets 587 The remaining fields in the TKEY RDATA, i.e. Inception, Expiration, 588 Error, Other Size and Data Fields, MUST be set according to [RFC2930]. 590 4.2 Context Established 592 When context negotiation is complete, the handle context_handle 593 is used for the generation and verification of transaction signatures. 594 The handle is valid for a finite amount of time determined by the 595 underlying security mechanism. A server MAY unilaterally terminate 596 a context at any time (see section 4.2.1). 598 Server SHOULD limit the amount of memory used to cache established 599 contexts. 601 The procedures for sending and receiving signed messages are given in 602 section 5, Sending and Verifying Signed Messages. 604 4.2.1 Terminating a Context 606 A server can terminate any established context at any time. The 607 server MAY hint to the client that the context is being deleted by 608 including a TKEY RR in a response with the Mode field set to 5, i.e. 609 "key deletion" [RFC2930]. 610 An active context is deleted by calling GSS_Delete_sec_context 611 providing the associated context_handle. 613 5. Sending and Verifying Signed Messages 615 5.1 Sending a Signed Message - Call GSS_GetMIC 617 The procedure for sending a signature-protected message is specified 618 in [RFC2845]. The data to be passed to the signature routine includes 619 the whole DNS message with specific TSIG variables appended. For the 620 exact format, see [RFC2845]. For this protocol, use the following 621 TSIG variable values: 623 TSIG Record 624 NAME = key_name that identifies this context 625 RDATA 626 Algorithm Name = gss-tsig 628 Assign the remaining fields in the TSIG RDATA appropriate values 629 as described in [RFC2845]. 631 The signature is generated by calling GSS_GetMIC. The following input 632 parameters MUST be used. The outcome of the call is indicated with the 633 output values specified below. Consult Sections 2.3.1 "GSS_GetMIC 634 call" of the RFC 2743[RFC2743] for syntax definitions. 636 INPUTS 637 CONTEXT HANDLE context_handle = context_handle for key_name 638 OCTET STRING message = outgoing message plus TSIG 639 variables (per [RFC2845]) 640 INTEGER qop_req = 0 (0 requests a default 641 value). Caller MAY instead specify other valid value (for 642 details see Section 1.2.4 in [RFC2743]) 644 OUTPUTS 645 INTEGER major_status 646 INTEGER minor_status 647 OCTET STRING per_msg_token 649 If major_status is GSS_S_COMPLETE, then signature generation 650 succeeded. The signature in per_msg_token is inserted into the 651 Signature field of the TSIG RR and the message is transmitted. 653 If major_status is GSS_S_CONTEXT_EXPIRED, GSS_S_CREDENTIALS_EXPIRED or 654 GSS_S_FAILURE the caller MUST delete the security context, return to the 655 uninitialized state and SHOULD negotiate a new security context, as 656 described above in Section 3.1 658 If major_status is GSS_S_NO_CONTEXT, the caller MUST remove the entry 659 for key_name from the (target_ name, key_name, context_handle) mapping 660 table, return to the uninitialized state and SHOULD negotiate a new 661 security context, as described above in Section 3.1 663 If major_status is GSS_S_BAD_QOP, the caller SHOULD repeat the 664 GSS_GetMIC call with allowed QOP value. The number of such repetitions 665 MUST be limited to prevent infinite loops. 667 5.2 Verifying a Signed Message - Call GSS_VerifyMIC 669 The procedure for verifying a signature-protected message is specified 670 in [RFC2845]. 671 The NAME of the TSIG record determines which context_handle maps to 672 the context that MUST be used to verify the signature. If the NAME 673 does not map to an established context, the server MUST send a 674 standard TSIG error response to the client indicating BADKEY in the 675 TSIG error field (as described in [RFC2845]). 677 For the GSS algorithm, a signature is verified by using GSS_VerifyMIC: 678 INPUTS 679 CONTEXT HANDLE context_handle = context_handle for key_name 680 OCTET STRING message = incoming message plus TSIG 681 variables (per [RFC2845]) 682 OCTET STRING per_msg_token = Signature field from TSIG RR 684 OUTPUTS 685 INTEGER major_status 686 INTEGER minor_status 687 INTEGER qop_state 689 If major_status is GSS_S_COMPLETE, the signature is authentic and the 690 message was delivered intact. Per [RFC2845], the timer values of the 691 TSIG record MUST also be valid before considering the message to be 692 authentic. The caller MUST not act on the request or response in the 693 message until these checks are verified. 695 When a server is processing a client request, 696 the server MUST send a standard TSIG error response to the client 697 indicating BADKEY in the TSIG error field as described in [RFC2845], 698 if major_status is set to one of the following values 699 GSS_S_DEFECTIVE_TOKEN 700 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 701 GSS_S_DUPLICATE_TOKEN 702 GSS_S_OLD_TOKEN 703 GSS_S_UNSEQ_TOKEN 704 GSS_S_GAP_TOKEN 705 GSS_S_CONTEXT_EXPIRED 706 GSS_S_NO_CONTEXT 707 GSS_S_FAILURE 709 If the timer values of the TSIG record are invalid, the message MUST 710 NOT be considered authentic. If this error checking fails when a server 711 is processing a client request, the appropriate error response MUST be 712 sent to the client according to [RFC2845]. 714 6. Example usage of GSS-TSIG algorithm 716 This Section describes an example where a Client, client.example.com, 717 and a Server, server.example.com, establish a security context according 718 to the algorithm described above. 720 I. Client initializes security context negotiation 721 To establish a security context with a server, server.example.com, the 722 Client calls GSS_Init_sec_context with the following parameters 723 (Note that some INPUT and OUTPUT parameters not critical for this 724 algorithm are not described in this example) 725 CONTEXT HANDLE input_context_handle = 0 726 INTERNAL NAME targ_name = "DNS@server.example.com" 727 OCTET STRING input_token = NULL 728 BOOLEAN replay_det_req_flag = TRUE 729 BOOLEAN mutual_req_flag = TRUE 731 The OUTPUTS parameters returned by GSS_Init_sec_context include 732 INTEGER major_status = GSS_S_CONTINUE_NEEDED 733 CONTEXT HANDLE output_context_handle context_handle 734 OCTET STRING output_token output_token 735 BOOLEAN replay_det_state = TRUE 736 BOOLEAN mutual_state = TRUE 738 Client verifies that replay_det_state and mutual_state values are 739 TRUE. Since the major_status is GSS_S_CONTINUE_NEEDED, which is a 740 success OUTPUT major_status value, client stores context_handle that 741 maps to "DNS@server.example.com" and proceeds to the next step. 743 II. Client sends a query with QTYPE = TKEY to server 744 Client sends a query with QTYPE = TKEY for a client-generated globally 745 unique domain name string, 789.client.example.com.server.example.com. 746 Query contains a TKEY record in its Additional records section with 747 the following fields (Note that some fields not specific to this 748 algorithm are not specified) 750 NAME = 789.client.example.com.server.example.com. 751 RDATA 752 Algorithm Name = gss-tsig 753 Mode = 3 (GSS-API negotiation - per [RFC2930]) 754 Key Size = size of output_token in octets 755 Key Data = output_token 757 After the key_name 789.client.example.com.server.example.com. 758 is generated it is stored in the client's (target_name, key_name, 759 context_handle) mapping table. 761 III. Server receives a query with QTYPE = TKEY 762 When server receives a query with QTYPE = TKEY, the server verifies 763 that Mode and Algorithm fields in the TKEY record in the Additional 764 records section of the query are set to 3 and "gss-tsig" respectively. 765 It finds that the key_name 789.client.example.com.server.example.com. 766 is not listed in its (key_name, context_handle) mapping table. 768 IV. Server calls GSS_Accept_sec_context 769 To continue security context negotiation server calls 770 GSS_Accept_sec_context with the following parameters (Note that some 771 INPUT and OUTPUT parameters not critical for this algorithm are not 772 described in this example) 773 INPUTS 774 CONTEXT HANDLE input_context_handle = 0 775 OCTET STRING input_token = token specified in the Key 776 field from TKEY RR (from Additional 777 records section of the client's query) 778 The OUTPUTS parameters returned by GSS_Accept_sec_context include 779 INTEGER major_status = GSS_S_CONTINUE_NEEDED 780 CONTEXT_HANDLE output_context_handle context_handle 781 OCTET STRING output_token output_token 783 Server stores the mapping of the 784 789.client.example.com.server.example.com. to OUTPUT context_handle 785 in its (key_name, context_handle) mapping table. 787 V. Server responds to the TKEY query 788 Since the major_status = GSS_S_CONTINUE_NEEDED in the last server's 789 call to GSS_Accept_sec_context, the server responds to the TKEY query 790 placing in the answer section a TKEY record containing output_token in 791 the Key Data RDATA field. The error field in the TKEY record is set to 792 0. The RCODE in the query response is set to NOERROR. 794 VI. Client processes token returned by server 795 When the client receives the TKEY query response from the server, the 796 client calls GSS_Init_sec_context with the following parameters (Note 797 that some INPUT and OUTPUT parameters not critical for this algorithm 798 are not described in this example) 799 CONTEXT HANDLE input_context_handle = the context_handle stored 800 in the client's mapping table entry (DNS@server.example.com., 801 789.client.example.com.server.example.com., context_handle) 802 INTERNAL NAME targ_name = "DNS@server.example.com" 803 OCTET STRING input_token = token from Key field of TKEY 804 record from the Answer section of the server's response 805 BOOLEAN replay_det_req_flag = TRUE 806 BOOLEAN mutual_req_flag = TRUE 808 The OUTPUTS parameters returned by GSS_Init_sec_context include 809 INTEGER major_status = GSS_S_COMPLETE 810 CONTEXT HANDLE output_context_handle = context_handle 811 OCTET STRING output_token = output_token 812 BOOLEAN replay_det_state = TRUE 813 BOOLEAN mutual_state = TRUE 815 Since the major_status is set to GSS_S_COMPLETE the client side 816 security context is established, but since the output_token is not 817 NULL client MUST send a TKEY query to the server as described below. 819 VII. Client sends a query with QTYPE = TKEY to server 820 Client sends to the server a TKEY query for the 821 789.client.example.com.server.example.com. name. Query contains a TKEY 822 record in its Additional records section with the following fields 823 (Note that some INPUT and OUTPUT parameters not critical to this 824 algorithm are not described in this example) 825 NAME = 789.client.example.com.server.example.com. 826 RDATA 827 Algorithm Name = gss-tsig 828 Mode = 3 (GSS-API negotiation - per [RFC2930]) 829 Key Size = size of output_token in octets 830 Key Data = output_token 832 VIII. Server receives a TKEY query 833 When the server receives a TKEY query, the server verifies that Mode 834 and Algorithm fields in the TKEY record in the Additional records 835 section of the query are set to 3 and gss-tsig, repectively. It 836 finds that the key_name 789.client.example.com.server.example.com. is 837 listed in its (key_name, context_handle) mapping table. 839 IX. Server calls GSS_Accept_sec_context 840 To continue security context negotiation server calls 841 GSS_Accept_sec_context with the following parameters (Note that some 842 INPUT and OUTPUT parameters not critical for this algorithm are not 843 described in this example) 844 INPUTS 845 CONTEXT HANDLE input_context_handle = context_handle from the 846 (789.client.example.com.server.example.com., context_handle) 847 entry in the server's mapping table 848 OCTET STRING input_token = token specified in the Key 849 field of TKEY RR (from Additional records Section of 850 the client's query) 852 The OUTPUTS parameters returned by GSS_Accept_sec_context include 853 INTEGER major_status = GSS_S_COMPLETE 854 CONTEXT_HANDLE output_context_handle = context_handle 855 OCTET STRING output_token = NULL 857 Since major_status = GSS_S_COMPLETE, the security context on the 858 server side is established, but the server still needs to respond to 859 the client's TKEY query, as described below. The security context 860 state is advanced to Context Established. 862 X. Server responds to the TKEY query 863 Since the major_status = GSS_S_COMPLETE in the last server's call to 864 GSS_Accept_sec_context and the output_token is NULL, the server 865 responds to the TKEY query placing in the answer section a TKEY record 866 that was sent by the client in the Additional records section of the 867 client's latest TKEY query. In addition to this server places a 868 TSIG record in additional records section of its response. Server 869 calls GSS_GetMIC to generate a signature to include it in the TSIG 870 record. The server specifies the following GSS_GetMIC INPUT 871 parameters: 872 CONTEXT HANDLE context_handle = context_handle from the 873 (789.client.example.com.server.example.com., context_handle) 874 entry in the server's mapping table 875 OCTET STRING message = outgoing message plus TSIG 876 variables (as described in [RFC2845]) 878 The OUTPUTS parameters returned by GSS_GetMIC include 879 INTEGER major_status = GSS_S_COMPLETE 880 OCTET STRING per_msg_token 882 Signature field in the TSIG record is set to per_msg_token. 884 XI. Client processes token returned by server 885 Client receives the TKEY query response from the server. Since the 886 major_status was GSS_S_COMPLETE in the last client's call to 887 GSS_Init_sec_context, the client verifies that the server's response 888 is signed. To validate the signature client calls GSS_VerifyMIC with 889 the following parameters: 891 INPUTS 892 CONTEXT HANDLE context_handle = context_handle for 893 789.client.example.com.server.example.com. key_name 894 OCTET STRING message = incoming message plus TSIG 895 variables (as described in [RFC2845]) 896 OCTET STRING per_msg_token = Signature field from TSIG RR 897 included in the server's query response 899 Since the OUTPUTS parameter major_status = GSS_S_COMPLETE, the 900 signature is validated, security negotiation is complete and the 901 security context state is advanced to Context Established. These 902 client and server will use the established security context to sign 903 and validate the signatures when they exchange packets with each 904 other until the context expires. 906 7. Security Considerations 908 This document describes a protocol for DNS security using GSS-API. 909 The security provided by this protocol is only as effective as the 910 security provided by the underlying GSS mechanisms. 912 All the security considerations from RFC2845, RFC2930 and RFC 2743 913 apply to the protocol described in this document. 915 8. IANA Considerations 917 The authors request that the IANA reserve the TSIG Algorithm name 918 gss-tsig for the use in the Algorithm fields of TKEY and TSIG resource 919 records. This Algorithm name refers to the algorithm described in this 920 document. The requirement to have this name registered with IANA is 921 specified in RFC 2845. 923 9. Conformance 925 The GSS API using SPNEGO [RFC2478] provides maximum flexibility to 926 choose the underlying security mechanisms that enables security context 927 negotiation. GSS API using SPNEGO [RFC2478] enables client and server to 928 negotiate and choose such underlying security mechanisms on the fly. To 929 support such flexibility, DNS clients and servers SHOULD specify SPNEGO 930 mech_type in their GSS API calls. At the same time, in order to 931 guarantee interoperability between DNS clients and servers that support 932 GSS-TSIG it is required that 933 - DNS servers specify SPNEGO mech_type 934 - GSS APIs called by DNS client support Kerberos v5 935 - GSS APIs called by DNS server support SPNEGO [RFC2478] and 936 Kerberos v5. 938 In addition to these, GSS APIs used by DNS client and server MAY also 939 support other underlying security mechanisms. 941 10. Acknowledgements 943 The authors of this document would like to thank the following people 944 for their contribution to this specification: Chuck Chan, Mike Swift, 945 Ram Viswanathan, Olafur Gudmundsson and Donald E. Eastlake 3rd. 947 11. References 949 [RFC2743] J. Linn, "Generic Security Service Application Program 950 Interface, Version 2 , Update 1", RFC 2743, RSA Laboratories, 951 January 2000. 953 [RFC2845] P. Vixie, O. Gudmundsson, D. Eastlake, B. Wellington, 954 "Secret Key Transaction Signatures for DNS (TSIG)", RFC 2845, 955 ISC, NAI Labs, Motorola, Nominum, May, 2000, 957 [RFC2930] D. Eastlake 3rd, "Secret Key Establishment for DNS (TKEY RR)", 958 RFC 2930, Motorola, September 2000. 960 [RFC2535] D. Eastlake 3rd, "Domain Name System Security Extensions," 961 RFC 2535, IBM, March 1999. 963 [RFC2137] D. Eastlake 3rd, "Secure Domain Name System Dynamic Update," 964 RFC 2137, CyberCash, April 1997. 966 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 967 Requirement Levels", BCP 14, RFC 2119, March 1997. 969 [RFC1034] Mockapetris, P., "Domain Names - Concepts and Facilities", 970 STD 13, RFC 1034, November 1987. 972 [RFC1035] Mockapetris, P., "Domain Names - Implementation and 973 Specification", STD 13, RFC 1034, November 1987. 975 [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", 976 RFC 1964, OpenVision Technologies, June 1996. 978 [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)", 979 RFC 2025, Bell-Northern Research, October 1996. 981 [RFC2478] Baize, E., Pinkas, D., "The Simple and Protected GSS-API 982 Negotiation Mechanism", RFC 2478, Bull, December 1998. 984 [ISO11578]"Information technology", "Open Systems 985 Interconnection", "Remote Procedure Call", 986 ISO/IEC 11578:1996, http://www.iso.ch/cate/d2229.html. 988 12. Author's Addresses 990 Stuart Kwan Praerit Garg 991 Microsoft Corporation Microsoft Corporation 992 One Microsoft Way One Microsoft Way 993 Redmond, WA 98052 Redmond, WA 98052 994 USA USA 995 skwan@microsoft.com praeritg@microsoft.com 997 James Gilroy Levon Esibov 998 Microsoft Corporation Microsoft Corporation 999 One Microsoft Way One Microsoft Way 1000 Redmond, WA 98052 Redmond, WA 98052 1001 USA USA 1002 jamesg@microsoft.com levone@microsoft.com 1004 Randy Hall Jeff Westhead 1005 Lucent Technologies Microsoft Corporation 1006 400 Lapp Road One Microsoft Way 1007 Malvern PA 19355 Redmond, WA 98052 1008 USA USA 1009 randyhall@lucent.com jwesth@microsoft.com