idnits 2.17.1 draft-ietf-dnsext-gss-tsig-06.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 22 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. -- The abstract seems to indicate that this document updates RFC2845, but the header doesn't have an 'Updates:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 380 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: Replace: "The server MUST not generate a signed response to an unsigned request." == 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: With: "The server MUST not generate a signed response to an unsigned request, except in case of response to client's unsigned TKEY query if secret key is established on server side after server processed client's query. Signing responses to unsigned TKEY queries MUST be explicitly specified in the description of an individual secret key establishment algorithm." == 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 325, but not defined == Unused Reference: 'RFC2137' is defined on line 1005, 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 (~~), 9 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Stuart Kwan 2 Praerit Garg 3 February 28, 2003 James Gilroy 4 Expires August 28, 2003 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). This document updates 40 RFC 2845. 42 Table of Contents 44 1: Introduction......................................................2 45 2: Algorithm Overview................................................3 46 2.1: GSS Details...................................................4 47 2.2: Modifications to the TSIG protocol (RFC 2845).................4 48 3: Client Protocol Details...........................................4 49 3.1: Negotiating Context...........................................5 50 3.1.1: Call GSS_Init_sec_context.................................5 51 3.1.2: Send TKEY Query to Server.................................7 52 3.1.3: Receive TKEY Query-Response from Server...................7 53 3.2: Context Established..........................................10 54 3.2.1: Terminating a Context....................................10 55 4: Server Protocol Details..........................................10 56 4.1: Negotiating Context..........................................10 57 4.1.1: Receive TKEY Query from Client...........................11 58 4.1.2: Call GSS_Accept_sec_context..............................11 59 4.1.3: Send TKEY Query-Response to Client.......................12 60 4.2: Context Established..........................................13 61 4.2.1: Terminating a Context....................................13 62 5: Sending and Verifying Signed Messages............................14 63 5.1: Sending a Signed Message - Call GSS_GetMIC...................14 64 5.2: Verifying a Signed Message - Call GSS_VerifyMIC..............15 65 6: Example usage of GSS-TSIG algorithm..............................16 66 7: Security Considerations..........................................20 67 8: IANA Considerations..............................................20 68 9: Conformance......................................................20 69 10:Acknowledgements.................................................20 70 11:References.......................................................20 72 1. Introduction 74 The Secret Key Transaction Authentication for DNS (TSIG) [RFC2845] 75 protocol was developed to provide a lightweight authentication and 76 integrity of messages between two DNS entities, such as client and 77 server or server and server. TSIG can be used to protect dynamic 78 update messages, authenticate regular message or to off-load 79 complicated DNSSEC [RFC2535] processing from a client to a server and 80 still allow the client to be assured of the integrity of the answers. 82 The TSIG protocol [RFC2845] is extensible through the definition of new 83 algorithms. This document specifies an algorithm based on the Generic 84 Security Service Application Program Interface (GSS-API) [RFC2743]. 85 GSS-API is a framework that provides an abstraction of security to the 86 application protocol developer. The security services offered can 87 include authentication, integrity, and confidentiality. 89 The GSS-API framework has several benefits: 90 * Mechanism and protocol independence. The underlying mechanisms that 91 realize the security services can be negotiated on the fly and varied 92 over time. For example, a client and server MAY use Kerberos [RFC1964] 93 for one transaction, whereas that same server MAY use SPKM [RFC2025] 94 with a different client. 96 * The protocol developer is removed from the responsibility of 97 creating and managing a security infrastructure. For example, the 98 developer does not need to create new key distribution or key 99 management systems. Instead the developer relies on the security 100 service mechanism to manage this on its behalf. 102 The scope of this document is limited to the description of an 103 authentication mechanism only. It does not discuss and/or propose an 104 authorization mechanism. Readers that are unfamiliar with GSS-API 105 concepts are encouraged to read the characteristics and concepts section 106 of [RFC2743] before examining this protocol in detail. It is also 107 assumed that the reader is familiar with [RFC2845], [RFC2930], [RFC1034] 108 and [RFC1035]. 110 The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", 111 "RECOMMENDED", and "MAY" in this document are to be interpreted as 112 described in RFC 2119 [RFC2119]. 114 2. Algorithm Overview 116 In GSS, client and server interact to create a "security context". 117 The security context can be used to create and verify transaction 118 signatures on messages between the two parties. A unique security 119 context is required for each unique connection between client and 120 server. 122 Creating a security context involves a negotiation between client and 123 server. Once a context has been established, it has a finite lifetime 124 for which it can be used to secure messages. Thus there are three 125 states of a context associated with a connection: 127 +----------+ 128 | | 129 V | 130 +---------------+ | 131 | Uninitialized | | 132 | | | 133 +---------------+ | 134 | | 135 V | 136 +---------------+ | 137 | Negotiating | | 138 | Context | | 139 +---------------+ | 140 | | 141 V | 142 +---------------+ | 143 | Context | | 144 | Established | | 145 +---------------+ | 146 | | 147 +----------+ 149 Every connection begins in the uninitialized state. 151 2.1 GSS Details 153 Client and server MUST be locally authenticated and have acquired 154 default credentials before using this protocol as specified in 155 Section 1.1.1 "Credentials" in RFC 2743 [RFC2743]. 157 The GSS-TSIG algorithm consists of two stages: 159 I. Establish security context. The Client and Server use the 160 GSS_Init_sec_context and GSS_Accept_sec_context APIs to generate the 161 tokens that they pass to each other using [RFC2930] as a transport 162 mechanism. 164 II. Once the security context is established it is used to generate and 165 verify signatures using GSS_GetMIC and GSS_VerifyMIC APIs. These 166 signatures are exchanged by the Client and Server as a part of the TSIG 167 records exchanged in DNS messages sent between the Client and Server, 168 as described in [RFC2845]. 170 2.2 Modifications to the TSIG protocol (RFC 2845) 172 Modification to RFC 2845 allows use of TSIG through signing server's 173 response in an explicitly specified place in multi message exchange 174 between two DNS entities even if client's request wasn't signed. 176 Specifically Section 4.2 of RFC 2845 MUST be modified as follows. 178 Replace: 179 "The server MUST not generate a signed response to an unsigned 180 request." 182 With: 183 "The server MUST not generate a signed response to an unsigned request, 184 except in case of response to client's unsigned TKEY query if secret 185 key is established on server side after server processed client's 186 query. Signing responses to unsigned TKEY queries MUST be explicitly 187 specified in the description of an individual secret key establishment 188 algorithm." 190 3. Client Protocol Details 192 A unique context is required for each server to which the client sends 193 secure messages. A context is identified by a context handle. A 194 client maintains a mapping of servers to handles, 196 (target_name, key_name, context_handle) 198 The value key_name also identifies a context handle. The key_name is 199 the owner name of the TKEY and TSIG records sent between a client and a 200 server to indicate to each other which context MUST be used to process 201 the current request. 203 DNS client and server MAY use various underlying security mechanisms to 204 establish security context as described in sections 3 and 4. At the 205 same time, in order to guarantee interoperability between DNS clients 206 and servers that support GSS-TSIG it is REQUIRED that security 207 mechanism used by client enables use of Kerberos v5 (see Section 9 208 for more information). 210 3.1 Negotiating Context 212 In GSS, establishing a security context involves the passing of opaque 213 tokens between the client and the server. The client generates the 214 initial token and sends it to the server. The server processes the 215 token and if necessary, returns a subsequent token to the client. The 216 client processes this token, and so on, until the negotiation is 217 complete. The number of times the client and server exchange tokens 218 depends on the underlying security mechanism. A completed negotiation 219 results in a context handle. 221 The TKEY resource record [RFC2930] is used as the vehicle to transfer 222 tokens between client and server. The TKEY record is a general 223 mechanism for establishing secret keys for use with TSIG. For more 224 information, see [RFC2930]. 226 3.1.1 Call GSS_Init_sec_context 228 To obtain the first token to be sent to a server, a client MUST call 229 GSS_Init_sec_context API. 230 The following input parameters MUST be used. The outcome of the call is 231 indicated with the output values below. Consult Sections 2.2.1 232 "GSS_Init_sec_context call" of [RFC2743] for syntax definitions. 234 INPUTS 235 CREDENTIAL HANDLE claimant_cred_handle = NULL (NULL specifies "use 236 default"). Client MAY instead specify some other valid handle 237 to its credentials. 238 CONTEXT HANDLE input_context_handle = 0 239 INTERNAL NAME targ_name = "DNS@" 240 OBJECT IDENTIFIER mech_type = Underlying security 241 mechanism chosen by implementers. To guarantee 242 interoperability of the implementations of the GSS-TSIG 243 mechanism client MUST specify a valid underlying security 244 mechanism that enables use of Kerberos v5 (see Section 9 for 245 more information). 246 OCTET STRING input_token = NULL 247 BOOLEAN replay_det_req_flag = TRUE 248 BOOLEAN mutual_req_flag = TRUE 249 BOOLEAN deleg_req_flag = TRUE 250 BOOLEAN sequence_req_flag = TRUE 251 BOOLEAN anon_req_flag = FALSE 252 BOOLEAN integ_req_flag = TRUE 253 INTEGER lifetime_req = 0 (0 requests a default 254 value). Client MAY instead specify another upper bound for the 255 lifetime of the context to be established in seconds. 256 OCTET STRING chan_bindings = Any valid channel bindings 257 as specified in Section 1.1.6 "Channel Bindings" in [RFC2743] 259 OUTPUTS 260 INTEGER major_status 261 CONTEXT HANDLE output_context_handle 262 OCTET STRING output_token 263 BOOLEAN replay_det_state 264 BOOLEAN mutual_state 265 INTEGER minor_status 266 OBJECT IDENTIFIER mech_type 267 BOOLEAN deleg_state 268 BOOLEAN sequence_state 269 BOOLEAN anon_state 270 BOOLEAN trans_state 271 BOOLEAN prot_ready_state 272 BOOLEAN conf_avail 273 BOOLEAN integ_avail 274 INTEGER lifetime_rec 276 If returned major_status is set to one of the following errors 278 GSS_S_DEFECTIVE_TOKEN 279 GSS_S_DEFECTIVE_CREDENTIAL 280 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 281 GSS_S_NO_CRED 282 GSS_S_CREDENTIALS_EXPIRED 283 GSS_S_BAD_BINDINGS 284 GSS_S_OLD_TOKEN 285 GSS_S_DUPLICATE_TOKEN 286 GSS_S_NO_CONTEXT 287 GSS_S_BAD_NAMETYPE 288 GSS_S_BAD_NAME 289 GSS_S_BAD_MECH 290 GSS_S_FAILURE 292 then the the client MUST abandon the algorithm and MUST NOT use the 293 GSS-TSIG algorithm to establish this security contex. This document 294 does not prescribe which other mechanism could be used to establish 295 a security context. Next time when this client needs to establish 296 security context, the client MAY use GSS-TSIG algorithm. 298 Success values of major_status are GSS_S_CONTINUE_NEEDED and 299 GSS_S_COMPLETE. The exact success code is important during later 300 processing. 302 The values of replay_det_state and mutual_state indicate if the 303 security package provides replay detection and mutual authentication, 304 respectively. If returned major_status is GSS_S_COMPLETE AND one or both 305 of these values are FALSE, the client MUST abandon this algorithm. 307 Client's behavior MAY depend on other OUTPUT parameters according 308 to the policy local to the client. 310 The handle output_context_handle is unique to this negotiation and 311 is stored in the client's mapping table as the context_handle that 312 maps to target_name. 314 3.1.2 Send TKEY Query to Server 316 An opaque output_token returned by GSS_Init_sec_context is transmitted 317 to the server in a query request with QTYPE=TKEY. The token itself 318 will be placed in a Key Data field of the RDATA field in the TKEY 319 resource record in the additional records section of the query. The 320 owner name of the TKEY resource record set queried for and the owner 321 name of the supplied TKEY resource record in the additional records 322 section MUST be the same. This name uniquely identifies the security 323 context to both the client and server, and thus the client SHOULD use 324 a value which is globally unique as described in [RFC2930]. To achieve 325 global uniqueness, the name MAY contain a UUID/GUID [ISO11578]. 327 TKEY Record 328 NAME = client-generated globally unique domain name string 329 (as described in [RFC2930]) 330 RDATA 331 Algorithm Name = gss-tsig 332 Mode = 3 (GSS-API negotiation - per [RFC2930]) 333 Key Size = size of output_token in octets 334 Key Data = output_token 336 The remaining fields in the TKEY RDATA, i.e. Inception, Expiration, 337 Error, Other Size and Data Fields, MUST be set according to [RFC2930]. 339 The query is transmitted to the server. 341 Note: if the original client call to GSS_Init_sec_context returned any 342 major_status other than GSS_S_CONTINUE_NEEDED or GSS_S_COMPLETE, then 343 the client MUST NOT send TKEY query. Client's behavior in this case is 344 described above in Section 3.1.1. 346 3.1.3 Receive TKEY Query-Response from Server 348 Upon the reception of the TKEY query DNS server MUST respond according 349 to the description in Section 4. This Section specifies the behavior 350 of the client after it receives the matching response to its query. 352 The next processing step depends on the value of major_status from the 353 most recent call that client performed to GSS_Init_sec_context: either 354 GSS_S_COMPLETE or GSS_S_CONTINUE. 356 3.1.3.1 Value of major_status == GSS_S_COMPLETE 358 If the last call to GSS_Init_sec_context yielded a major_status value 359 of GSS_S_COMPLETE and a non-NULL output_token was sent to the server, 360 then the client side component of the negotiation is complete and the 361 client is awaiting confirmation from the server. 363 Confirmation is in the form of a query response with RCODE=NOERROR 364 and with the last client supplied TKEY record in the answer section 365 of the query. The response MUST be signed with a TSIG record. Note 366 that server is allowed to sign a response to unsigned client's query 367 due to modification to the RFC 2845 specified in Section 2.2 above. 368 The signature in the TSIG record MUST be verified using the procedure 369 detailed in section 5, Sending and Verifying Signed Messages. If the 370 response is not signed, OR if the response is signed but signature is 371 invalid, then an attacker has tampered with the message in transit or 372 has attempted to send the client a false response. In this case the 373 client MAY continue waiting for a response to its last TKEY query until 374 the time period since the client sent last TKEY query expires. Such a 375 time period is specified by the policy local to the client. This is a 376 new option that allows DNS client to accept multiple answers for one 377 query ID and select one (not necessarily the first one) based on some 378 criteria. 380 If the signature is verified the context state is advanced to Context 381 Established. Proceed to section 3.2 for usage of the security context. 383 3.1.3.2 Value of major_status == GSS_S_CONTINUE 385 If the last call to GSS_Init_sec_context yielded a major_status value 386 of GSS_S_CONTINUE, then the negotiation is not yet complete. The server 387 will return to the client a query-response with a TKEY record in the 388 Answer section. If the DNS message error is not NO_ERROR or error field 389 in the TKEY record is not 0 (i.e. no error), then the client MUST 390 abandon this negotiation sequence. The client MUST delete an active 391 context by calling GSS_Delete_sec_context providing the associated 392 context_handle. The client MAY repeat the negotiation sequence starting 393 with the uninitialized state as described in section 3.1. To prevent 394 infinite looping the number of attempts to establish a security context 395 MUST be limited to ten or less. 397 If the DNS message error is NO_ERROR and error filed in the TKEY record 398 is 0 (i.e. no error), then the client MUST pass a token specified in the 399 Key Data field in the TKEY resource record to GSS_Init_sec_context 400 using the same parameters values as in previous call except values for 401 CONTEXT HANDLE input_context_handle and OCTET STRING input_token as 402 described below: 404 INPUTS 405 CONTEXT HANDLE input_context_handle = context_handle (this is the 406 context_handle corresponding to the key_name which is the 407 owner name of the TKEY record in the answer section in the 408 TKEY query response) 409 OCTET STRING input_token = token from Key field of 410 TKEY record 412 Depending on the following OUTPUT values of GSS_Init_sec_context 413 INTEGER major_status 414 OCTET STRING output_token 415 the client MUST take one of the following actions: 417 If OUTPUT major_status is set to one of the following values 418 GSS_S_DEFECTIVE_TOKEN 419 GSS_S_DEFECTIVE_CREDENTIAL 420 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 421 GSS_S_NO_CRED 422 GSS_S_CREDENTIALS_EXPIRED 423 GSS_S_BAD_BINDINGS 424 GSS_S_OLD_TOKEN 425 GSS_S_DUPLICATE_TOKEN 426 GSS_S_NO_CONTEXT 427 GSS_S_BAD_NAMETYPE 428 GSS_S_BAD_NAME 429 GSS_S_BAD_MECH 430 GSS_S_FAILURE 432 the client MUST abandon this negotiation sequence. This means that the 433 client MUST delete an active context by calling GSS_Delete_sec_context 434 providing the associated context_handle. The client MAY repeat the 435 negotiation sequence starting with the uninitialized state as described 436 in section 3.1. To prevent infinite looping the number of attempts to 437 establish a security context MUST be limited to ten or less. 439 If OUTPUT major_status is GSS_S_CONTINUE_NEEDED OR GSS_S_COMPLETE then 440 client MUST act as described below. 442 If the response from the server was signed, and the OUTPUT major_status 443 is GSS_S_COMPLETE,then the signature in the TSIG record MUST be verified 444 using the procedure detailed in section 5, Sending and Verifying Signed 445 Messages. If the signature is invalid, then the client MUST abandon this 446 negotiation sequence. This means that the client MUST delete an active 447 context by calling GSS_Delete_sec_context providing the associated 448 context_handle. The client MAY repeat the negotiation sequence starting 449 with the uninitialized state as described in section 3.1. To prevent 450 infinite looping the number of attempts to establish a security context 451 MUST be limited to ten or less. 453 If major_status is GSS_S_CONTINUE_NEEDED the negotiation is not yet 454 finished. The token output_token MUST be passed to the server in a TKEY 455 record by repeating the negotiation sequence beginning with section 456 3.1.2. The client MUST place a limit on the number of continuations in 457 a context negotiation to prevent endless looping. Such limit SHOULD NOT 458 exceed value of 10. 460 If major_status is GSS_S_COMPLETE and output_token is non-NULL, the 461 client-side component of the negotiation is complete but the token 462 output_token MUST be passed to the server by repeating the negotiation 463 sequence beginning with section 3.1.2. 465 If major_status is GSS_S_COMPLETE and output_token is NULL, context 466 negotiation is complete. The context state is advanced to Context 467 Established. Proceed to section 3.2 for usage of the security context. 469 3.2 Context Established 471 When context negotiation is complete, the handle context_handle MUST be 472 used for the generation and verification of transaction signatures. 474 The procedures for sending and receiving signed messages are described 475 in section 5, Sending and Verifying Signed Messages. 477 3.2.1 Terminating a Context 479 When the client is not intended to continue using the established 480 security context, the client SHOULD delete an active context by 481 calling GSS_Delete_sec_context providing the associated context_handle, 482 AND client SHOULD delete the established context on the DNS server 483 by using TKEY RR with the Mode field set to 5, i.e. "key deletion" 484 [RFC2930]. 486 4. Server Protocol Details 488 As on the client-side, the result of a successful context negotiation 489 is a context handle used in future generation and verification of the 490 transaction signatures. 492 A server MAY be managing several contexts with several clients. 493 Clients identify their contexts by providing a key name in their 494 request. The server maintains a mapping of key names to handles: 496 (key_name, context_handle) 498 4.1 Negotiating Context 500 A server MUST recognize TKEY queries as security context negotiation 501 messages. 503 4.1.1 Receive TKEY Query from Client 505 Upon receiving a query with QTYPE = TKEY, the server MUST examine 506 whether the Mode and Algorithm Name fields of the TKEY record in the 507 additional records section of the message contain values of 3 and 508 gss-tsig, respectively. If they do, then the (key_name, context_handle) 509 mapping table is searched for the key_name matching the owner name of 510 the TKEY record in the additional records section of the query. If the 511 name is found in the table and the security context for this name is 512 established and not expired, then the server MUST respond to the query 513 with BADNAME error in the TKEY error field. If the name is found in the 514 table and the security context is not established, the corresponding 515 context_handle is used in subsequent GSS operations. If the name is 516 found but the security context is expired, then the server deletes this 517 security context, as described in Section 4.2.1, and interprets this 518 query as a start of new security context negotiation and performs 519 operations described in Section 4.1.2 and 4.1.3. If the name is not 520 found, then the server interprets this query as a start of new security 521 context negotiation and performs operations described in Section 4.1.2 522 and 4.1.3. 524 4.1.2 Call GSS_Accept_sec_context 526 The server performs its side of a context negotiation by calling 527 GSS_Accept_sec_context. The following input parameters MUST be used. The 528 outcome of the call is indicated with the output values below. Consult 529 Sections 2.2.2 "GSS_Accept_sec_context call" of the RFC 2743[RFC2743] 530 for syntax definitions. 532 INPUTS 533 CONTEXT HANDLE input_context_handle = 0 if new negotiation, 534 context_handle matching 535 key_name if ongoing negotiation 536 OCTET STRING input_token = token specified in the Key 537 field from TKEY RR (from Additional records Section of 538 the client's query) 539 CREDENTIAL HANDLE acceptor_cred_handle = NULL (NULL specifies "use 540 default"). Server MAY instead specify some other valid handle 541 to its credentials. 542 OCTET STRING chan_bindings = Any valid channel bindings 543 as specified in Section 1.1.6 "Channel Bindings" in [RFC2743] 545 OUTPUTS 546 INTEGER major_status 547 CONTEXT_HANDLE output_context_handle 548 OCTET STRING output_token 549 INTEGER minor_status 550 INTERNAL NAME src_name 551 OBJECT IDENTIFIER mech_type 552 BOOLEAN deleg_state 553 BOOLEAN mutual_state 554 BOOLEAN replay_det_state 555 BOOLEAN sequence_state 556 BOOLEAN anon_state 557 BOOLEAN trans_state 558 BOOLEAN prot_ready_state 559 BOOLEAN conf_avail 560 BOOLEAN integ_avail 561 INTEGER lifetime_rec 562 CONTEXT_HANDLE delegated_cred_handle 564 If this is the first call to GSS_Accept_sec_context in a new 565 negotiation, then output_context_handle is stored in the server's 566 key-mapping table as the context_handle that maps to the name of the 567 TKEY record. 569 4.1.3 Send TKEY Query-Response to Client 571 The server MUST respond to the client with a TKEY query response with 572 RCODE = NOERROR, that contains a TKEY record in the answer section. 574 If OUTPUT major_status is one of the following errors the error field 575 in the TKEY record set to BADKEY. 577 GSS_S_DEFECTIVE_TOKEN 578 GSS_S_DEFECTIVE_CREDENTIAL 579 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 580 GSS_S_DUPLICATE_TOKEN 581 GSS_S_OLD_TOKEN 582 GSS_S_NO_CRED 583 GSS_S_CREDENTIALS_EXPIRED 584 GSS_S_BAD_BINDINGS 585 GSS_S_NO_CONTEXT 586 GSS_S_BAD_MECH 587 GSS_S_FAILURE 589 If OUTPUT major_status is set to GSS_S_COMPLETE or 590 GSS_S_CONTINUE_NEEDED then server MUST act as described below. 592 If major_status is GSS_S_COMPLETE the server component of the 593 negotiation is finished. If output_token is non-NULL, then it MUST be 594 returned to the client in a Key Data field of the RDATA in TKEY. The 595 error field in the TKEY record is set to NOERROR. The message MUST be 596 signed with a TSIG record as described in section 5, Sending and 597 Verifying Signed Messages. Note that server is allowed to sign a 598 response to unsigned client's query due to modification to the RFC 599 2845 specified in Section 2.2 above. The context state is advanced to 600 Context Established. Section 4.2 discusses the usage of the security 601 context. 603 If major_status is GSS_S_COMPLETE and output_token is NULL, then the 604 TKEY record received from the client MUST be returned in the Answer 605 section of the response. The message MUST be signed with a TSIG record 606 as described in section 5, Sending and Verifying Signed Messages. Note 607 that server is allowed to sign a response to unsigned client's query 608 due to modification to the RFC 2845 specified in section 2.2 above. The 609 context state is advanced to Context Established. Section 4.2 discusses 610 the usage of the security context. 612 If major_status is GSS_S_CONTINUE, the server component of the 613 negotiation is not yet finished. The server responds to the TKEY 614 query with a standard query response, placing in the answer section a 615 TKEY record containing output_token in the Key Data RDATA field. The 616 error field in the TKEY record is set to NOERROR. The server MUST limit 617 the number of times that a given context is allowed to repeat, to 618 prevent endless looping. Such limit SHOULD NOT exceed value of 10. 620 In all cases except if major_status is GSS_S_COMPLETE and output_token 621 is NULL other TKEY record fields MUST contain the following values: 622 NAME = key_name 623 RDATA 624 Algorithm Name = gss-tsig 625 Mode = 3 (GSS-API negotiation - per [RFC2930]) 626 Key Size = size of output_token in octets 628 The remaining fields in the TKEY RDATA, i.e. Inception, Expiration, 629 Error, Other Size and Data Fields, MUST be set according to [RFC2930]. 631 4.2 Context Established 633 When context negotiation is complete, the handle context_handle 634 is used for the generation and verification of transaction signatures. 635 The handle is valid for a finite amount of time determined by the 636 underlying security mechanism. A server MAY unilaterally terminate 637 a context at any time (see section 4.2.1). 639 Server SHOULD limit the amount of memory used to cache established 640 contexts. 642 The procedures for sending and receiving signed messages are given in 643 section 5, Sending and Verifying Signed Messages. 645 4.2.1 Terminating a Context 647 A server can terminate any established context at any time. The 648 server MAY hint to the client that the context is being deleted by 649 including a TKEY RR in a response with the Mode field set to 5, i.e. 650 "key deletion" [RFC2930]. 651 An active context is deleted by calling GSS_Delete_sec_context 652 providing the associated context_handle. 654 5. Sending and Verifying Signed Messages 656 5.1 Sending a Signed Message - Call GSS_GetMIC 658 The procedure for sending a signature-protected message is specified 659 in [RFC2845]. The data to be passed to the signature routine includes 660 the whole DNS message with specific TSIG variables appended. For the 661 exact format, see [RFC2845]. For this protocol, use the following 662 TSIG variable values: 664 TSIG Record 665 NAME = key_name that identifies this context 666 RDATA 667 Algorithm Name = gss-tsig 669 Assign the remaining fields in the TSIG RDATA appropriate values 670 as described in [RFC2845]. 672 The signature is generated by calling GSS_GetMIC. The following input 673 parameters MUST be used. The outcome of the call is indicated with the 674 output values specified below. Consult Sections 2.3.1 "GSS_GetMIC 675 call" of the RFC 2743[RFC2743] for syntax definitions. 677 INPUTS 678 CONTEXT HANDLE context_handle = context_handle for key_name 679 OCTET STRING message = outgoing message plus TSIG 680 variables (per [RFC2845]) 681 INTEGER qop_req = 0 (0 requests a default 682 value). Caller MAY instead specify other valid value (for 683 details see Section 1.2.4 in [RFC2743]) 685 OUTPUTS 686 INTEGER major_status 687 INTEGER minor_status 688 OCTET STRING per_msg_token 690 If major_status is GSS_S_COMPLETE, then signature generation 691 succeeded. The signature in per_msg_token is inserted into the 692 Signature field of the TSIG RR and the message is transmitted. 694 If major_status is GSS_S_CONTEXT_EXPIRED, GSS_S_CREDENTIALS_EXPIRED or 695 GSS_S_FAILURE the caller MUST delete the security context, return to the 696 uninitialized state and SHOULD negotiate a new security context, as 697 described above in Section 3.1 699 If major_status is GSS_S_NO_CONTEXT, the caller MUST remove the entry 700 for key_name from the (target_ name, key_name, context_handle) mapping 701 table, return to the uninitialized state and SHOULD negotiate a new 702 security context, as described above in Section 3.1 704 If major_status is GSS_S_BAD_QOP, the caller SHOULD repeat the 705 GSS_GetMIC call with allowed QOP value. The number of such repetitions 706 MUST be limited to prevent infinite loops. 708 5.2 Verifying a Signed Message - Call GSS_VerifyMIC 710 The procedure for verifying a signature-protected message is specified 711 in [RFC2845]. 712 The NAME of the TSIG record determines which context_handle maps to 713 the context that MUST be used to verify the signature. If the NAME 714 does not map to an established context, the server MUST send a 715 standard TSIG error response to the client indicating BADKEY in the 716 TSIG error field (as described in [RFC2845]). 718 For the GSS algorithm, a signature is verified by using GSS_VerifyMIC: 719 INPUTS 720 CONTEXT HANDLE context_handle = context_handle for key_name 721 OCTET STRING message = incoming message plus TSIG 722 variables (per [RFC2845]) 723 OCTET STRING per_msg_token = Signature field from TSIG RR 725 OUTPUTS 726 INTEGER major_status 727 INTEGER minor_status 728 INTEGER qop_state 730 If major_status is GSS_S_COMPLETE, the signature is authentic and the 731 message was delivered intact. Per [RFC2845], the timer values of the 732 TSIG record MUST also be valid before considering the message to be 733 authentic. The caller MUST not act on the request or response in the 734 message until these checks are verified. 736 When a server is processing a client request, 737 the server MUST send a standard TSIG error response to the client 738 indicating BADKEY in the TSIG error field as described in [RFC2845], 739 if major_status is set to one of the following values 740 GSS_S_DEFECTIVE_TOKEN 741 GSS_S_BAD_SIG (GSS_S_BAD_MIC) 742 GSS_S_DUPLICATE_TOKEN 743 GSS_S_OLD_TOKEN 744 GSS_S_UNSEQ_TOKEN 745 GSS_S_GAP_TOKEN 746 GSS_S_CONTEXT_EXPIRED 747 GSS_S_NO_CONTEXT 748 GSS_S_FAILURE 750 If the timer values of the TSIG record are invalid, the message MUST 751 NOT be considered authentic. If this error checking fails when a server 752 is processing a client request, the appropriate error response MUST be 753 sent to the client according to [RFC2845]. 755 6. Example usage of GSS-TSIG algorithm 757 This Section describes an example where a Client, client.example.com, 758 and a Server, server.example.com, establish a security context according 759 to the algorithm described above. 761 I. Client initializes security context negotiation 762 To establish a security context with a server, server.example.com, the 763 Client calls GSS_Init_sec_context with the following parameters 764 (Note that some INPUT and OUTPUT parameters not critical for this 765 algorithm are not described in this example) 766 CONTEXT HANDLE input_context_handle = 0 767 INTERNAL NAME targ_name = "DNS@server.example.com" 768 OCTET STRING input_token = NULL 769 BOOLEAN replay_det_req_flag = TRUE 770 BOOLEAN mutual_req_flag = TRUE 772 The OUTPUTS parameters returned by GSS_Init_sec_context include 773 INTEGER major_status = GSS_S_CONTINUE_NEEDED 774 CONTEXT HANDLE output_context_handle context_handle 775 OCTET STRING output_token output_token 776 BOOLEAN replay_det_state = TRUE 777 BOOLEAN mutual_state = TRUE 779 Client verifies that replay_det_state and mutual_state values are 780 TRUE. Since the major_status is GSS_S_CONTINUE_NEEDED, which is a 781 success OUTPUT major_status value, client stores context_handle that 782 maps to "DNS@server.example.com" and proceeds to the next step. 784 II. Client sends a query with QTYPE = TKEY to server 785 Client sends a query with QTYPE = TKEY for a client-generated globally 786 unique domain name string, 789.client.example.com.server.example.com. 787 Query contains a TKEY record in its Additional records section with 788 the following fields (Note that some fields not specific to this 789 algorithm are not specified) 791 NAME = 789.client.example.com.server.example.com. 792 RDATA 793 Algorithm Name = gss-tsig 794 Mode = 3 (GSS-API negotiation - per [RFC2930]) 795 Key Size = size of output_token in octets 796 Key Data = output_token 798 After the key_name 789.client.example.com.server.example.com. 799 is generated it is stored in the client's (target_name, key_name, 800 context_handle) mapping table. 802 III. Server receives a query with QTYPE = TKEY 803 When server receives a query with QTYPE = TKEY, the server verifies 804 that Mode and Algorithm fields in the TKEY record in the Additional 805 records section of the query are set to 3 and "gss-tsig" respectively. 806 It finds that the key_name 789.client.example.com.server.example.com. 807 is not listed in its (key_name, context_handle) mapping table. 809 IV. Server calls GSS_Accept_sec_context 810 To continue security context negotiation server calls 811 GSS_Accept_sec_context with the following parameters (Note that some 812 INPUT and OUTPUT parameters not critical for this algorithm are not 813 described in this example) 814 INPUTS 815 CONTEXT HANDLE input_context_handle = 0 816 OCTET STRING input_token = token specified in the Key 817 field from TKEY RR (from Additional 818 records section of the client's query) 819 The OUTPUTS parameters returned by GSS_Accept_sec_context include 820 INTEGER major_status = GSS_S_CONTINUE_NEEDED 821 CONTEXT_HANDLE output_context_handle context_handle 822 OCTET STRING output_token output_token 824 Server stores the mapping of the 825 789.client.example.com.server.example.com. to OUTPUT context_handle 826 in its (key_name, context_handle) mapping table. 828 V. Server responds to the TKEY query 829 Since the major_status = GSS_S_CONTINUE_NEEDED in the last server's 830 call to GSS_Accept_sec_context, the server responds to the TKEY query 831 placing in the answer section a TKEY record containing output_token in 832 the Key Data RDATA field. The error field in the TKEY record is set to 833 0. The RCODE in the query response is set to NOERROR. 835 VI. Client processes token returned by server 836 When the client receives the TKEY query response from the server, the 837 client calls GSS_Init_sec_context with the following parameters (Note 838 that some INPUT and OUTPUT parameters not critical for this algorithm 839 are not described in this example) 840 CONTEXT HANDLE input_context_handle = the context_handle stored 841 in the client's mapping table entry (DNS@server.example.com., 842 789.client.example.com.server.example.com., context_handle) 843 INTERNAL NAME targ_name = "DNS@server.example.com" 844 OCTET STRING input_token = token from Key field of TKEY 845 record from the Answer section of the server's response 846 BOOLEAN replay_det_req_flag = TRUE 847 BOOLEAN mutual_req_flag = TRUE 849 The OUTPUTS parameters returned by GSS_Init_sec_context include 850 INTEGER major_status = GSS_S_COMPLETE 851 CONTEXT HANDLE output_context_handle = context_handle 852 OCTET STRING output_token = output_token 853 BOOLEAN replay_det_state = TRUE 854 BOOLEAN mutual_state = TRUE 856 Since the major_status is set to GSS_S_COMPLETE the client side 857 security context is established, but since the output_token is not 858 NULL client MUST send a TKEY query to the server as described below. 860 VII. Client sends a query with QTYPE = TKEY to server 861 Client sends to the server a TKEY query for the 862 789.client.example.com.server.example.com. name. Query contains a TKEY 863 record in its Additional records section with the following fields 864 (Note that some INPUT and OUTPUT parameters not critical to this 865 algorithm are not described in this example) 866 NAME = 789.client.example.com.server.example.com. 867 RDATA 868 Algorithm Name = gss-tsig 869 Mode = 3 (GSS-API negotiation - per [RFC2930]) 870 Key Size = size of output_token in octets 871 Key Data = output_token 873 VIII. Server receives a TKEY query 874 When the server receives a TKEY query, the server verifies that Mode 875 and Algorithm fields in the TKEY record in the Additional records 876 section of the query are set to 3 and gss-tsig, repectively. It 877 finds that the key_name 789.client.example.com.server.example.com. is 878 listed in its (key_name, context_handle) mapping table. 880 IX. Server calls GSS_Accept_sec_context 881 To continue security context negotiation server calls 882 GSS_Accept_sec_context with the following parameters (Note that some 883 INPUT and OUTPUT parameters not critical for this algorithm are not 884 described in this example) 885 INPUTS 886 CONTEXT HANDLE input_context_handle = context_handle from the 887 (789.client.example.com.server.example.com., context_handle) 888 entry in the server's mapping table 889 OCTET STRING input_token = token specified in the Key 890 field of TKEY RR (from Additional records Section of 891 the client's query) 893 The OUTPUTS parameters returned by GSS_Accept_sec_context include 894 INTEGER major_status = GSS_S_COMPLETE 895 CONTEXT_HANDLE output_context_handle = context_handle 896 OCTET STRING output_token = NULL 898 Since major_status = GSS_S_COMPLETE, the security context on the 899 server side is established, but the server still needs to respond to 900 the client's TKEY query, as described below. The security context 901 state is advanced to Context Established. 903 X. Server responds to the TKEY query 904 Since the major_status = GSS_S_COMPLETE in the last server's call to 905 GSS_Accept_sec_context and the output_token is NULL, the server 906 responds to the TKEY query placing in the answer section a TKEY record 907 that was sent by the client in the Additional records section of the 908 client's latest TKEY query. In addition to this server places a 909 TSIG record in additional records section of its response. Server 910 calls GSS_GetMIC to generate a signature to include it in the TSIG 911 record. The server specifies the following GSS_GetMIC INPUT 912 parameters: 913 CONTEXT HANDLE context_handle = context_handle from the 914 (789.client.example.com.server.example.com., context_handle) 915 entry in the server's mapping table 916 OCTET STRING message = outgoing message plus TSIG 917 variables (as described in [RFC2845]) 919 The OUTPUTS parameters returned by GSS_GetMIC include 920 INTEGER major_status = GSS_S_COMPLETE 921 OCTET STRING per_msg_token 923 Signature field in the TSIG record is set to per_msg_token. 925 XI. Client processes token returned by server 926 Client receives the TKEY query response from the server. Since the 927 major_status was GSS_S_COMPLETE in the last client's call to 928 GSS_Init_sec_context, the client verifies that the server's response 929 is signed. To validate the signature client calls GSS_VerifyMIC with 930 the following parameters: 932 INPUTS 933 CONTEXT HANDLE context_handle = context_handle for 934 789.client.example.com.server.example.com. key_name 935 OCTET STRING message = incoming message plus TSIG 936 variables (as described in [RFC2845]) 937 OCTET STRING per_msg_token = Signature field from TSIG RR 938 included in the server's query response 940 Since the OUTPUTS parameter major_status = GSS_S_COMPLETE, the 941 signature is validated, security negotiation is complete and the 942 security context state is advanced to Context Established. These 943 client and server will use the established security context to sign 944 and validate the signatures when they exchange packets with each 945 other until the context expires. 947 7. Security Considerations 949 This document describes a protocol for DNS security using GSS-API. 950 The security provided by this protocol is only as effective as the 951 security provided by the underlying GSS mechanisms. 953 All the security considerations from RFC2845, RFC2930 and RFC 2743 954 apply to the protocol described in this document. 956 8. IANA Considerations 958 The authors request that the IANA reserve the TSIG Algorithm name 959 gss-tsig for the use in the Algorithm fields of TKEY and TSIG resource 960 records. This Algorithm name refers to the algorithm described in this 961 document. The requirement to have this name registered with IANA is 962 specified in RFC 2845. 964 9. Conformance 966 The GSS API using SPNEGO [RFC2478] provides maximum flexibility to 967 choose the underlying security mechanisms that enables security context 968 negotiation. GSS API using SPNEGO [RFC2478] enables client and server to 969 negotiate and choose such underlying security mechanisms on the fly. To 970 support such flexibility, DNS clients and servers SHOULD specify SPNEGO 971 mech_type in their GSS API calls. At the same time, in order to 972 guarantee interoperability between DNS clients and servers that support 973 GSS-TSIG it is required that 974 - DNS servers specify SPNEGO mech_type 975 - GSS APIs called by DNS client support Kerberos v5 976 - GSS APIs called by DNS server support SPNEGO [RFC2478] and 977 Kerberos v5. 979 In addition to these, GSS APIs used by DNS client and server MAY also 980 support other underlying security mechanisms. 982 10. Acknowledgements 984 The authors of this document would like to thank the following people 985 for their contribution to this specification: Chuck Chan, Mike Swift, 986 Ram Viswanathan, Olafur Gudmundsson, Donald E. Eastlake 3rd and Erik 987 Nordmark. 989 11. References 991 [RFC2743] J. Linn, "Generic Security Service Application Program 992 Interface, Version 2 , Update 1", RFC 2743, RSA Laboratories, 993 January 2000. 995 [RFC2845] P. Vixie, O. Gudmundsson, D. Eastlake, B. Wellington, 996 "Secret Key Transaction Authentication for DNS (TSIG)", 997 RFC 2845, ISC, NAI Labs, Motorola, Nominum, May, 2000, 999 [RFC2930] D. Eastlake 3rd, "Secret Key Establishment for DNS (TKEY RR)", 1000 RFC 2930, Motorola, September 2000. 1002 [RFC2535] D. Eastlake 3rd, "Domain Name System Security Extensions," 1003 RFC 2535, IBM, March 1999. 1005 [RFC2137] D. Eastlake 3rd, "Secure Domain Name System Dynamic Update," 1006 RFC 2137, CyberCash, April 1997. 1008 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1009 Requirement Levels", BCP 14, RFC 2119, March 1997. 1011 [RFC1034] Mockapetris, P., "Domain Names - Concepts and Facilities", 1012 STD 13, RFC 1034, November 1987. 1014 [RFC1035] Mockapetris, P., "Domain Names - Implementation and 1015 Specification", STD 13, RFC 1034, November 1987. 1017 [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", 1018 RFC 1964, OpenVision Technologies, June 1996. 1020 [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)", 1021 RFC 2025, Bell-Northern Research, October 1996. 1023 [RFC2478] Baize, E., Pinkas, D., "The Simple and Protected GSS-API 1024 Negotiation Mechanism", RFC 2478, Bull, December 1998. 1026 [ISO11578]"Information technology", "Open Systems 1027 Interconnection", "Remote Procedure Call", 1028 ISO/IEC 11578:1996, http://www.iso.ch/cate/d2229.html. 1030 12. Author's Addresses 1032 Stuart Kwan Praerit Garg 1033 Microsoft Corporation Microsoft Corporation 1034 One Microsoft Way One Microsoft Way 1035 Redmond, WA 98052 Redmond, WA 98052 1036 USA USA 1037 skwan@microsoft.com praeritg@microsoft.com 1039 James Gilroy Levon Esibov 1040 Microsoft Corporation Microsoft Corporation 1041 One Microsoft Way One Microsoft Way 1042 Redmond, WA 98052 Redmond, WA 98052 1043 USA USA 1044 jamesg@microsoft.com levone@microsoft.com 1045 Randy Hall Jeff Westhead 1046 Lucent Technologies Microsoft Corporation 1047 400 Lapp Road One Microsoft Way 1048 Malvern PA 19355 Redmond, WA 98052 1049 USA USA 1050 randyhall@lucent.com jwesth@microsoft.com