idnits 2.17.1 draft-skwan-gss-tsig-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-24) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == 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 13 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** 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 contain references ([RFC2078]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 1999) is 9200 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2078 (Obsoleted by RFC 2743) -- No information found for draft-ietf-dnsind-tsig- - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'TSIG' -- No information found for draft-ietf-dnssec-tkey- - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'TKEY' ** Obsolete normative reference: RFC 2065 (Obsoleted by RFC 2535) ** Obsolete normative reference: RFC 2137 (Obsoleted by RFC 3007) Summary: 11 errors (**), 0 flaws (~~), 3 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Stuart Kwan 3 Praerit Garg 4 James Gilroy 5 Microsoft Corp. 6 August 1998 7 Expires February 1999 9 GSS Algorithm for TSIG (GSS-TSIG) 11 Status of this Memo 13 This document is an Internet-Draft. Internet-Drafts are working 14 documents of the Internet Engineering Task Force (IETF), its 15 areas, and its working groups. Note that other groups may also 16 distribute working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six 19 months and may be updated, replaced, or obsoleted by other 20 documents at any time. It is inappropriate to use Internet- 21 Drafts as reference material or to cite them other than as 22 "work in progress." 24 To view the entire list of current Internet-Drafts, please check 25 the "1id-abstracts.txt" listing contained in the Internet-Drafts 26 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 27 (Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East 28 Coast), or ftp.isi.edu (US West Coast). 30 Abstract 32 The TSIG protocol provides transaction level authentication for DNS. 33 TSIG is extensible through the definition of new algorithms. This 34 document specifies an algorithm based on the Generic Security Service 35 Application Program Interface (GSS-API) [RFC2078]. 37 Table of Contents 39 1: Introduction......................................................2 40 2: Protocol Overview.................................................3 41 2.1: GSS Details...................................................4 42 3: Client Protocol Details...........................................4 43 3.1: Negotiating Context...........................................4 44 3.1.1: Call GSS_Init_sec_context.................................5 45 3.1.2: Send TKEY Query to Server.................................6 46 3.1.3: Receive TKEY Query-Response from Server...................6 47 3.2: Context Established...........................................8 48 4: Server Protocol Details...........................................8 49 4.1: Negotiating Context...........................................8 50 4.1.1: Receive TKEY Query from Client............................9 51 4.1.2: Call GSS_Accept_sec_context...............................9 52 4.1.3: Send TKEY Query-Response to Client........................9 53 4.2: Context Established..........................................10 54 4.2.1: Terminating a Context....................................10 55 5: Sending and Verifying Signed Messages............................11 56 5.1: Sending a Signed Message - Call GSS_GetMIC...................11 57 5.2: Verifying a Signed Message - Call GSS_VerifyMIC..............12 58 6: Security Considerations..........................................12 59 7: Acknowledgements.................................................13 60 8: References.......................................................13 62 1. Introduction 64 The Secret Key Transaction Signature for DNS [TSIG] protocol was 65 developed to provide a lightweight alternative to full DNS security 66 [RFC2065] and secure dynamic update [RFC2137], where full security is 67 impractical due to implementation complexity, management overhead, or 68 computational cost. 70 The [TSIG] protocol is extensible through the definition of new 71 algorithms. This document specifies an algorithm based on the Generic 72 Security Service Application Program Interface (GSS-API) [RFC2078]. 73 GSS-API is a framework that provides an abstraction of security to the 74 application protocol developer. The security services offered can 75 include authentication, integrity, and confidentiality. 77 The GSS-API framework has several benefits: 78 * Mechanism and protocol independence. The underlying mechanisms that 79 realize the security services can be negotiated on the fly and varied 80 over time. For example, a client and server may use Kerberos for one 81 transaction, whereas that same server may use TLS with a different 82 client. 84 * The protocol developer is removed from the responsibility of 85 creating and managing a security infrastructure. For example, the 86 developer does not need to create new key distribution or key 87 management systems. Instead the developer relies on the security 88 service mechanism to manage this on its behalf. 90 2. Protocol Overview 92 Readers that are unfamiliar with the GSS-API concepts are encouraged 93 to read the characteristics and concepts section of [RFC2078] before 94 examining this protocol in detail. 96 In GSS, client and server interact to create a "security context". 97 The security context is used to create and verify transaction 98 signatures on messages between the two parties. A unique security 99 context is required for each unique connection between client and 100 server. 102 Creating a security context involves a negotiation between client and 103 server. Once a context has been established, it has a finite lifetime 104 for which it can be used to secure messages. Thus there are three 105 states of a context associated with a connection: 107 +----------+ 108 | | 109 V | 110 +---------------+ | 111 | Uninitialized | | 112 | | | 113 +---------------+ | 114 | | 115 V | 116 +---------------+ | 117 | Negotiating | | 118 | Context | | 119 +---------------+ | 120 | | 121 V | 122 +---------------+ | 123 | Context | | 124 | Established | | 125 +---------------+ | 126 | | 127 +----------+ 129 Every connection begins in the uninitialized state. 131 2.1 GSS Details 133 Client and server must be locally authenticated and have acquired 134 default credentials per [RFC2078] before using this protocol. 136 Not all flags used in GSS-API interfaces are specified in this 137 document. Where omitted, clients and servers may select the default 138 or use a value based on local system policy. 140 Not all error return values from GSS-API interfaces are specified in 141 this document. When errors are encountered, the caller should act 142 appropriately. 144 3. Client Protocol Details 146 A unique context is required for each server to which the client sends 147 secure messages. A context is identified by a context handle. A 148 client maintains a mapping of handles to servers, 150 (target_server_name, key_name, context_handle) 152 The value key_name also identifies a context handle, and is used on 153 the wire to indicate to a server which context should be used to 154 process the current request. 156 3.1 Negotiating Context 158 In GSS, establishing a security context involves the passing of opaque 159 tokens between the client and the server. The client generates the 160 initial token and sends it to the server. The server processes the 161 token and if necessary, returns a subsequent token to the client. The 162 client processes this token, and so on, until the negotiation is 163 complete. The number of times the client and server exchange tokens 164 depends on the underlying security mechanism. A completed negotiation 165 results in a context handle. 167 The TKEY resource record [TKEY] is used as the vehicle to transfer 168 tokens between client and server. The TKEY record is a general 169 mechanism for establishing secret keys for use with TSIG. For more 170 information, see [TKEY]. 172 3.1.1 Call GSS_Init_sec_context 174 The client obtains the first token by calling GSS_Init_sec_context. 175 The following input parameters are used. The outcome of the call 176 is indicated with the output values below. Consult [RFC2078] for 177 syntax definitions. 179 INPUTS 180 CONTEXT HANDLE input_context_handle = 0 181 INTERNAL NAME targ_name = target_server_name 182 OCTET STRING input_token = NULL 183 BOOLEAN replay_det_req_flag = TRUE 184 BOOLEAN mutual_req_flag = TRUE 185 BOOLEAN deleg_req_flag = TRUE (optional) 187 OUTPUTS 188 INTEGER major_status 189 CONTEXT HANDLE output_context_handle 190 OCTET STRING output_token 191 BOOLEAN replay_det_state 192 BOOLEAN mutual_state 194 The values of replay_det_state and mutual_state indicate if the 195 security package can provide replay detection and mutual 196 authentication, respectively. If one or both of these values 197 are FALSE, the client must abandon this protocol. 199 The deleg_req_flag is optional, and can be used if the client wants 200 the server to be able to call out to other services under the 201 context of the client. 203 If major_status indicates an error, the client must abandon the 204 protocol. Success values of major_status are GSS_S_CONTINUE_NEEDED 205 and GSS_S_COMPLETE. The exact success code is important during later 206 processing. 208 The handle output_context_handle is unique to this negotiation and 209 is stored in the client's mapping table as the context_handle that 210 maps to target_server_name. 212 3.1.2 Send TKEY Query to Server 214 The output_token from GSS_Init_sec_context is transmitted to the 215 server in a query request for a TKEY record. The token itself 216 will be placed in a TKEY record in the additional records section of 217 the query. The domain-like name of the TKEY record set queried for 218 and the name of the supplied TKEY record in the additional section 219 will uniquely identify the security context to both the client and 220 server, and thus the client should use a value which is globally 221 unique. 223 TKEY Record 224 NAME = client-generated globally unique domain name string 225 (see [TKEY]) 226 RDATA 227 Algorithm Name = gss-tsig.microsoft.com (TBD) 228 Inception = as appropriate - see [TKEY] 229 Expire = as appropriate - see [TKEY] 230 Mode = 3 (GSS-API negotiation - see [TKEY]) 231 Key Size = as appropriate, size of output_token 232 Key = output_token 234 If the last call to GSS_Init_sec_context yielded a major_status value 235 of GSS_S_COMPLETE, then the message should be signed with a TSIG 236 record before being sent to the server. See section 5, Sending 237 and Verifying Signed Messages, for the signing procedure. 239 The query is transmitted to the server. 241 3.1.3 Receive TKEY Query-Response from Server 243 The server will return a standard TKEY query-response (see [TKEY]). 244 The response may indicate that TKEY is not supported, or that the 245 GSS-API mode and algorithm are not supported. If this is the case, 246 the client must abandon this algorithm. 248 If the value of the Error field in the TKEY RDATA (TKEY.Error) is 249 BADKEY, then the token provided by the client was invalid. The 250 client must abandon this algorithm. 252 If TKEY.Error indicates success, then the client may continue. The 253 next processing step depends on the value of major_status from the 254 most recent call to GSS_Init_sec_context: either GSS_S_COMPLETE or 255 GSS_S_CONTINUE. 257 3.1.3.1 Value of major_status == GSS_S_COMPLETE 259 If the last call to GSS_Init_sec_context yielded a major_status value 260 of GSS_S_COMPLETE and a non-NULL output_token was sent to the server, 261 then the client side component of the negotiation is complete and the 262 client is awaiting confirmation from the server. 264 Confirmation will be in the form of a NOERROR query response 265 containing the last client supplied TKEY record in the answer section 266 of the query. The response may also be signed with a TSIG record, 267 and if present this signature must be verified using the procedure 268 detailed in section 5, Sending and Verifying Signed Messages. 270 If the message verification completes without an error, or if a TSIG 271 signature was not included, the context state is advanced to Context 272 Established. Proceed to section 3.2 for usage of the security 273 context. 275 3.1.3.2 Value of major_status == GSS_S_CONTINUE 277 If the last call to GSS_Init_sec_context yielded a major_status value 278 of GSS_S_CONTINUE, then the negotiation is not yet complete. The 279 server will respond to the TKEY query with a NOERROR query response 280 that contains a TKEY record in the answer section. The TKEY record 281 contains a token that is passed to GSS_Init_sec_context using the 282 parameters from the previous call and the following modifications: 284 INPUTS 285 CONTEXT HANDLE input_context_handle = context_handle 286 OCTET STRING input_token = token from Key field of 287 TKEY record 289 OUTPUTS 290 INTEGER major_status 291 OCTET STRING output_token 293 If major_status indicates an error, the client must abandon this 294 algorithm. Success values are GSS_S_CONTINUE and GSS_S_COMPLETE. 296 If major_status is GSS_S_CONTINUE the negotiation is not yet 297 finished. The token output_token must again be passed to the server 298 in a TKEY record. The negotiation sequence is repeated beginning 299 with section 3.1.2. Client should place a limit on the number 300 of continuations in a context negotiation to prevent endless 301 looping. 303 If major_status is GSS_S_COMPLETE and output_token is non-NULL, 304 the client side component of the negotiation is complete but the 305 token output_token must be passed to the server. The negotiation 306 sequence is repeated beginning with section 3.1.2. 308 If major_status is GSS_S_COMPLETE and output_token is NULL, context 309 negotiation is complete. The response from the server may be signed 310 with a TSIG record, and if present this signature must be verified 311 using the procedure detailed in section 5, Sending and 312 Verifying Signed Messages. 314 If the message verification completes without an error, or if a TSIG 315 signature was not included, the context state is advanced to Context 316 Established. Proceed to section 3.2 for usage of the security 317 context. 319 3.2 Context Established 321 When context negotiation is complete, the handle context_handle is 322 used for the generation and verification of transaction signatures. 324 The procedures for sending and receiving signed messages are given in 325 section 5, Sending and Verifying Signed Messages. 327 4. Server Protocol Details 329 As on the client side, the result of a successful context negotiation 330 is a context handle used in future processing. 332 A server may be managing several contexts with several clients. 333 Clients identify their contexts by providing a key name in their 334 request. The server maintains a mapping of key names to handles: 336 (key_name, context_handle) 338 4.1 Negotiating Context 340 A server recognizes TKEY queries as security context negotiation 341 messages. 343 4.1.1 Receive TKEY Query from Client 345 Upon receiving a TKEY query, the server must examine the Mode and 346 Algorithm Name fields to see if they match this algorithm. If they 347 match, the (key_name, context_handle) mapping table is searched for 348 the NAME value of the TKEY record. If the name is found in the table, 349 the corresponding context_handle is used in following GSS operations. 350 If the name is not found a new negotiation is started. 352 4.1.2 Call GSS_Accept_sec_context 354 The server performs its side of a context negotiation by calling 355 GSS_Accept_sec_context with the token provided by the client in the 356 TKEY record. 358 The server calls GSS_Accept_sec_context: 360 INPUTS 361 CONTEXT HANDLE input_context_handle = 0 if new negotiation, 362 context_handle if ongoing 363 OCTET STRING input_token = Key field from TKEY RR 365 OUTPUTS 366 INTEGER major_status 367 CONTEXT_HANDLE output_context_handle 368 OCTET STRING output_token 370 If this is the first call to GSS_Accept_sec_context in a new 371 negotiation, then output_context_handle is stored in the server's 372 key-mapping table as the context_handle that maps to the name of the 373 TKEY record. 375 4.1.3 Send TKEY Query-Response to Client 377 If major_status returns a GSS failure code, the negotiation has 378 failed. The server must respond to the client with a standard 379 TKEY query-response where the TKEY error field value is set to 380 BADKEY. 382 Success values for major_status are GSS_S_COMPLETE or GSS_S_CONTINUE. 384 If major_status is GSS_S_COMPLETE the server component of the 385 negotiation is finished. The message from the client may be signed 386 with a TSIG RR, and if present this signature must be verified 387 using the procedure detailed in section 5, Sending and 388 Verifying Signed Messages. The server responds to the TKEY query 389 using a standard query response. If output_token is non-NULL, then it 390 must be returned to the client in a TKEY in the Answer section of the 391 response. If output_token is NULL, then the TKEY record received from 392 the client must be returned in the Answer section of the response. 393 The answer should be signed with a TSIG record per the procedure given 394 in section 5, Sending and Verifying Signed Messages. 395 The context state is advanced to Established. Section 4.2 discusses 396 the usage of the security context. 398 If major_status is GSS_S_CONTINUE, the server component of the 399 negotiation is not yet finished. The server responds to the TKEY 400 query with a standard query response, placing a TKEY record containing 401 output_token in the answer section. The negotiation sequence then 402 repeats beginning with section 4.1.1. The server must limit the 403 number of times that a given context is allowed to repeat, to prevent 404 endless looping. 406 4.2 Context Established 408 When context negotiation is complete, the handle context_handle 409 is used for the generation and verification of transaction signatures. 410 The handle is valid for a finite amount of time determined by the 411 underlying security mechanism. A server may unilaterally terminate 412 a context at any time. 414 The procedures for sending and receiving signed messages are given in 415 section 5, Sending and Verifying Signed Messages. 417 4.2.1 Terminating a Context 419 A server can terminate any established context at any time. The 420 server may hint to the client that the context is being deleted 421 by including a TKEY RR in a response with the mode field set to 422 "key deletion". See [TKEY] for more details. 424 An active context is deleted by calling GSS_Delete_sec_context 425 providing the associated context_handle. 427 5. Sending and Verifying Signed Messages 429 5.1 Sending a Signed Message - Call GSS_GetMIC 431 The procedure for sending a signature-protected message is specified 432 in [TSIG]. The data to be passed to the signature routine includes 433 the whole DNS message with specific TSIG variables appended. For the 434 exact format, see [TSIG]. For this protocol, use the following 435 TSIG variable values: 437 TSIG Record 438 NAME = key_name that identifies this context 439 RDATA 440 Algorithm Name = gss-tsig.microsoft.com (TBD) 442 For the GSS algorithm, the signature is generated by calling 443 GSS_GetMIC: 445 INPUTS 446 CONTEXT HANDLE context_handle = context_handle for key_name 447 OCTET STRING message = outgoing message plus TSIG 448 variables (see [TSIG]) 450 OUTPUTS 451 INTEGER major_status 452 OCTET STRING per_msg_token 454 If major_status is GSS_S_COMPLETE, then signature generation 455 succeeded. The signature in per_msg_token is inserted into the 456 Signature field of the TSIG RR and the message is transmitted. 458 If major_status is GSS_S_CONTEXT_EXPIRED or GSS_S_CREDENTIALS_EXPIRED, 459 the caller needs to return to the uninitialized state and negotiate 460 a new security context. 462 5.2 Verifying a Signed Message - Call GSS_VerifyMIC 464 The procedure for verifying a signature-protected message is specified 465 in [TSIG]. 467 The NAME of the TSIG record determines which context_handle 468 maps to this context. If the NAME does not map to a currently active 469 context, the server must send a standard TSIG error response to the 470 client indicating BADKEY in the TSIG error field (see [TSIG]). 472 For the GSS algorithm, a signature is verified by using GSS_VerifyMIC: 474 INPUTS 475 CONTEXT HANDLE context_handle = context_handle for key_name 476 OCTET STRING message = incoming message plus TSIG 477 variables (see [TSIG]) 478 OCTET STRING per_msg_token = Signature field from TSIG RR 480 OUTPUTS 481 INTEGER major_status 483 If major_status is GSS_S_COMPLETE, the signature is authentic and the 484 message was delivered intact. Per [TSIG], the Time Signed and Expire 485 fields of the TSIG record must also be valid before considering the 486 message to be authentic. The caller must not act on the request or 487 response in the message until these three checks are verified. 489 If major_status is GSS_S_CONTEXT_EXPIRED, the negotiated context is no 490 longer valid. If this failure occurs when a server is processing a 491 client request, the server must send a standard TSIG error response 492 to the client indicating BADKEY in the TSIG error field (see [TSIG]). 494 If major_status is any other error code or the Time Signed and/or the 495 Expire fields of the TSIG record are invalid, the message must not 496 be considered authentic. If this error checking fails when a server 497 is processing a client request, the appropriate error response must 498 be sent to the client per [TSIG]. 500 6. Security Considerations 502 This document describes a protocol for DNS security using GSS-API. 503 The security provided by this protocol is only as effective as the 504 security provided by the underlying GSS mechanisms. 506 7. Acknowledgements 508 The authors of this document would like to thank the following people 509 for their contribution to this specification: Chuck Chan, Mike Swift, 510 Ram Viswanathan and Donald E. Eastlake 3rd. 512 8. References 514 [RFC2078] J. Linn, "Generic Security Service Application Program 515 Interface, Version 2," RFC 2078, OpenVision Technologies, 516 January 1997. 518 [TSIG] P. Vixie, O. Gudmundsson, D. Eastlake, "Secret Key 519 Transaction Signatures for DNS (TSIG)," 520 draft-ietf-dnsind-tsig-*..txt, ISC, TIS, Cybercash. 522 [TKEY] D. Eastlake 3rd, "Secret Key Establishment for DNS (TKEY 523 RR)," draft-ietf-dnssec-tkey-*.txt. 525 [RFC2065] D. Eastlake 3rd, C. Kaufman, "Domain Name System Security 526 Extensions," RFC 2065, Cybercash, Iris, January 1997. 528 [RFC2137] D. Eastlake 3rd, "Secure Domain Name System Dynamic Update," 529 RFC 2137, CyberCash, April 1997. 531 9. Author's Addresses 533 Stuart Kwan Praerit Garg 534 Microsoft Corporation Microsoft Corporation 535 One Microsoft Way One Microsoft Way 536 Redmond, WA 98052 Redmond, WA 98052 537 USA USA 538 540 James Gilroy 541 Microsoft Corporation 542 One Microsoft Way 543 Redmond, WA 98052 544 USA 545