7 Network Working Group S. Kwan
8 Request for Comments: 3645 P. Garg
9 Updates: 2845 J. Gilroy
10 Category: Standards Track L. Esibov
18 Generic Security Service Algorithm for
19 Secret Key Transaction Authentication for DNS (GSS-TSIG)
23 This document specifies an Internet standards track protocol for the
24 Internet community, and requests discussion and suggestions for
25 improvements. Please refer to the current edition of the "Internet
26 Official Protocol Standards" (STD 1) for the standardization state
27 and status of this protocol. Distribution of this memo is unlimited.
31 Copyright (C) The Internet Society (2003). All Rights Reserved.
35 The Secret Key Transaction Authentication for DNS (TSIG) protocol
36 provides transaction level authentication for DNS. TSIG is
37 extensible through the definition of new algorithms. This document
38 specifies an algorithm based on the Generic Security Service
39 Application Program Interface (GSS-API) (RFC2743). This document
58 Kwan, et al. Standards Track [Page 1]
60 RFC 3645 GSS-TSIG October 2003
65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
66 2. Algorithm Overview . . . . . . . . . . . . . . . . . . . . . . 3
67 2.1. GSS Details. . . . . . . . . . . . . . . . . . . . . . . 4
68 2.2. Modifications to the TSIG protocol (RFC 2845). . . . . . 4
69 3. Client Protocol Details. . . . . . . . . . . . . . . . . . . . 5
70 3.1. Negotiating Context. . . . . . . . . . . . . . . . . . . 5
71 3.1.1. Call GSS_Init_sec_context. . . . . . . . . . . . . 6
72 3.1.2. Send TKEY Query to Server. . . . . . . . . . . . . 8
73 3.1.3. Receive TKEY Query-Response from Server. . . . . . 8
74 3.2. Context Established. . . . . . . . . . . . . . . . . . . 11
75 3.2.1. Terminating a Context. . . . . . . . . . . . . . . 11
76 4. Server Protocol Details. . . . . . . . . . . . . . . . . . . . 12
77 4.1. Negotiating Context. . . . . . . . . . . . . . . . . . . 12
78 4.1.1. Receive TKEY Query from Client . . . . . . . . . . 12
79 4.1.2. Call GSS_Accept_sec_context. . . . . . . . . . . . 12
80 4.1.3. Send TKEY Query-Response to Client . . . . . . . . 13
81 4.2. Context Established. . . . . . . . . . . . . . . . . . . 15
82 4.2.1. Terminating a Context. . . . . . . . . . . . . . . 15
83 5. Sending and Verifying Signed Messages. . . . . . . . . . . . . 15
84 5.1. Sending a Signed Message - Call GSS_GetMIC . . . . . . . 15
85 5.2. Verifying a Signed Message - Call GSS_VerifyMIC. . . . . 16
86 6. Example usage of GSS-TSIG algorithm. . . . . . . . . . . . . . 18
87 7. Security Considerations. . . . . . . . . . . . . . . . . . . . 22
88 8. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 22
89 9. Conformance. . . . . . . . . . . . . . . . . . . . . . . . . . 22
90 10. Intellectual Property Statement. . . . . . . . . . . . . . . . 23
91 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 23
92 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24
93 12.1. Normative References. . . . . . . . . . . . . . . . . . 24
94 12.2. Informative References. . . . . . . . . . . . . . . . . 24
95 13. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 25
96 14. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 26
100 The Secret Key Transaction Authentication for DNS (TSIG) [RFC2845]
101 protocol was developed to provide a lightweight authentication and
102 integrity of messages between two DNS entities, such as client and
103 server or server and server. TSIG can be used to protect dynamic
104 update messages, authenticate regular message or to off-load
105 complicated DNSSEC [RFC2535] processing from a client to a server and
106 still allow the client to be assured of the integrity of the answers.
114 Kwan, et al. Standards Track [Page 2]
116 RFC 3645 GSS-TSIG October 2003
119 The TSIG protocol [RFC2845] is extensible through the definition of
120 new algorithms. This document specifies an algorithm based on the
121 Generic Security Service Application Program Interface (GSS-API)
122 [RFC2743]. GSS-API is a framework that provides an abstraction of
123 security to the application protocol developer. The security
124 services offered can include authentication, integrity, and
127 The GSS-API framework has several benefits:
129 * Mechanism and protocol independence. The underlying mechanisms
130 that realize the security services can be negotiated on the fly
131 and varied over time. For example, a client and server MAY use
132 Kerberos [RFC1964] for one transaction, whereas that same server
133 MAY use SPKM [RFC2025] with a different client.
135 * The protocol developer is removed from the responsibility of
136 creating and managing a security infrastructure. For example, the
137 developer does not need to create new key distribution or key
138 management systems. Instead the developer relies on the security
139 service mechanism to manage this on its behalf.
141 The scope of this document is limited to the description of an
142 authentication mechanism only. It does not discuss and/or propose an
143 authorization mechanism. Readers that are unfamiliar with GSS-API
144 concepts are encouraged to read the characteristics and concepts
145 section of [RFC2743] before examining this protocol in detail. It is
146 also assumed that the reader is familiar with [RFC2845], [RFC2930],
147 [RFC1034] and [RFC1035].
149 The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",
150 "RECOMMENDED", and "MAY" in this document are to be interpreted as
151 described in BCP 14, RFC 2119 [RFC2119].
153 2. Algorithm Overview
155 In GSS, client and server interact to create a "security context".
156 The security context can be used to create and verify transaction
157 signatures on messages between the two parties. A unique security
158 context is required for each unique connection between client and
161 Creating a security context involves a negotiation between client and
162 server. Once a context has been established, it has a finite
163 lifetime for which it can be used to secure messages. Thus there are
164 three states of a context associated with a connection:
170 Kwan, et al. Standards Track [Page 3]
172 RFC 3645 GSS-TSIG October 2003
197 Every connection begins in the uninitialized state.
201 Client and server MUST be locally authenticated and have acquired
202 default credentials before using this protocol as specified in
203 Section 1.1.1 "Credentials" in RFC 2743 [RFC2743].
205 The GSS-TSIG algorithm consists of two stages:
207 I. Establish security context. The Client and Server use the
208 GSS_Init_sec_context and GSS_Accept_sec_context APIs to generate
209 the tokens that they pass to each other using [RFC2930] as a
212 II. Once the security context is established it is used to generate
213 and verify signatures using GSS_GetMIC and GSS_VerifyMIC APIs.
214 These signatures are exchanged by the Client and Server as a part
215 of the TSIG records exchanged in DNS messages sent between the
216 Client and Server, as described in [RFC2845].
218 2.2. Modifications to the TSIG protocol (RFC 2845)
220 Modification to RFC 2845 allows use of TSIG through signing server's
221 response in an explicitly specified place in multi message exchange
222 between two DNS entities even if client's request wasn't signed.
226 Kwan, et al. Standards Track [Page 4]
228 RFC 3645 GSS-TSIG October 2003
231 Specifically, Section 4.2 of RFC 2845 MUST be modified as follows:
234 "The server MUST not generate a signed response to an unsigned
238 "The server MUST not generate a signed response to an unsigned
239 request, except in case of response to client's unsigned TKEY
240 query if secret key is established on server side after server
241 processed client's query. Signing responses to unsigned TKEY
242 queries MUST be explicitly specified in the description of an
243 individual secret key establishment algorithm."
245 3. Client Protocol Details
247 A unique context is required for each server to which the client
248 sends secure messages. A context is identified by a context handle.
249 A client maintains a mapping of servers to handles:
251 (target_name, key_name, context_handle)
253 The value key_name also identifies a context handle. The key_name is
254 the owner name of the TKEY and TSIG records sent between a client and
255 a server to indicate to each other which context MUST be used to
256 process the current request.
258 DNS client and server MAY use various underlying security mechanisms
259 to establish security context as described in sections 3 and 4. At
260 the same time, in order to guarantee interoperability between DNS
261 clients and servers that support GSS-TSIG it is REQUIRED that
262 security mechanism used by client enables use of Kerberos v5 (see
263 Section 9 for more information).
265 3.1. Negotiating Context
267 In GSS, establishing a security context involves the passing of
268 opaque tokens between the client and the server. The client
269 generates the initial token and sends it to the server. The server
270 processes the token and if necessary, returns a subsequent token to
271 the client. The client processes this token, and so on, until the
272 negotiation is complete. The number of times the client and server
273 exchange tokens depends on the underlying security mechanism. A
274 completed negotiation results in a context handle.
282 Kwan, et al. Standards Track [Page 5]
284 RFC 3645 GSS-TSIG October 2003
287 The TKEY resource record [RFC2930] is used as the vehicle to transfer
288 tokens between client and server. The TKEY record is a general
289 mechanism for establishing secret keys for use with TSIG. For more
290 information, see [RFC2930].
292 3.1.1. Call GSS_Init_sec_context
294 To obtain the first token to be sent to a server, a client MUST call
295 GSS_Init_sec_context API.
297 The following input parameters MUST be used. The outcome of the call
298 is indicated with the output values below. Consult Sections 2.2.1,
299 "GSS_Init_sec_context call", of [RFC2743] for syntax definitions.
302 CREDENTIAL HANDLE claimant_cred_handle = NULL (NULL specifies "use
303 default"). Client MAY instead specify some other valid
304 handle to its credentials.
305 CONTEXT HANDLE input_context_handle = 0
306 INTERNAL NAME targ_name = "DNS@<target_server_name>"
307 OBJECT IDENTIFIER mech_type = Underlying security
308 mechanism chosen by implementers. To guarantee
309 interoperability of the implementations of the GSS-TSIG
310 mechanism client MUST specify a valid underlying security
311 mechanism that enables use of Kerberos v5 (see Section 9 for
313 OCTET STRING input_token = NULL
314 BOOLEAN replay_det_req_flag = TRUE
315 BOOLEAN mutual_req_flag = TRUE
316 BOOLEAN deleg_req_flag = TRUE
317 BOOLEAN sequence_req_flag = TRUE
318 BOOLEAN anon_req_flag = FALSE
319 BOOLEAN integ_req_flag = TRUE
320 INTEGER lifetime_req = 0 (0 requests a default
321 value). Client MAY instead specify another upper bound for the
322 lifetime of the context to be established in seconds.
323 OCTET STRING chan_bindings = Any valid channel bindings
324 as specified in Section 1.1.6 "Channel Bindings" in [RFC2743]
328 CONTEXT HANDLE output_context_handle
329 OCTET STRING output_token
330 BOOLEAN replay_det_state
333 OBJECT IDENTIFIER mech_type
338 Kwan, et al. Standards Track [Page 6]
340 RFC 3645 GSS-TSIG October 2003
343 BOOLEAN sequence_state
346 BOOLEAN prot_ready_state
351 If returned major_status is set to one of the following errors:
353 GSS_S_DEFECTIVE_TOKEN
354 GSS_S_DEFECTIVE_CREDENTIAL
355 GSS_S_BAD_SIG (GSS_S_BAD_MIC)
357 GSS_S_CREDENTIALS_EXPIRED
360 GSS_S_DUPLICATE_TOKEN
367 then the client MUST abandon the algorithm and MUST NOT use the GSS-
368 TSIG algorithm to establish this security context. This document
369 does not prescribe which other mechanism could be used to establish a
370 security context. Next time when this client needs to establish
371 security context, the client MAY use GSS-TSIG algorithm.
373 Success values of major_status are GSS_S_CONTINUE_NEEDED and
374 GSS_S_COMPLETE. The exact success code is important during later
377 The values of replay_det_state and mutual_state indicate if the
378 security package provides replay detection and mutual authentication,
379 respectively. If returned major_status is GSS_S_COMPLETE AND one or
380 both of these values are FALSE, the client MUST abandon this
383 Client's behavior MAY depend on other OUTPUT parameters according to
384 the policy local to the client.
386 The handle output_context_handle is unique to this negotiation and is
387 stored in the client's mapping table as the context_handle that maps
394 Kwan, et al. Standards Track [Page 7]
396 RFC 3645 GSS-TSIG October 2003
399 3.1.2. Send TKEY Query to Server
401 An opaque output_token returned by GSS_Init_sec_context is
402 transmitted to the server in a query request with QTYPE=TKEY. The
403 token itself will be placed in a Key Data field of the RDATA field in
404 the TKEY resource record in the additional records section of the
405 query. The owner name of the TKEY resource record set queried for
406 and the owner name of the supplied TKEY resource record in the
407 additional records section MUST be the same. This name uniquely
408 identifies the security context to both the client and server, and
409 thus the client SHOULD use a value which is globally unique as
410 described in [RFC2930]. To achieve global uniqueness, the name MAY
411 contain a UUID/GUID [ISO11578].
414 NAME = client-generated globally unique domain name string
415 (as described in [RFC2930])
417 Algorithm Name = gss-tsig
418 Mode = 3 (GSS-API negotiation - per [RFC2930])
419 Key Size = size of output_token in octets
420 Key Data = output_token
422 The remaining fields in the TKEY RDATA, i.e., Inception, Expiration,
423 Error, Other Size and Data Fields, MUST be set according to
426 The query is transmitted to the server.
428 Note: if the original client call to GSS_Init_sec_context returned
429 any major_status other than GSS_S_CONTINUE_NEEDED or GSS_S_COMPLETE,
430 then the client MUST NOT send TKEY query. Client's behavior in this
431 case is described above in Section 3.1.1.
433 3.1.3. Receive TKEY Query-Response from Server
435 Upon the reception of the TKEY query the DNS server MUST respond
436 according to the description in Section 4. This section specifies
437 the behavior of the client after it receives the matching response to
440 The next processing step depends on the value of major_status from
441 the most recent call that client performed to GSS_Init_sec_context:
442 either GSS_S_COMPLETE or GSS_S_CONTINUE.
450 Kwan, et al. Standards Track [Page 8]
452 RFC 3645 GSS-TSIG October 2003
455 3.1.3.1. Value of major_status == GSS_S_COMPLETE
457 If the last call to GSS_Init_sec_context yielded a major_status value
458 of GSS_S_COMPLETE and a non-NULL output_token was sent to the server,
459 then the client side component of the negotiation is complete and the
460 client is awaiting confirmation from the server.
462 Confirmation is in the form of a query response with RCODE=NOERROR
463 and with the last client supplied TKEY record in the answer section
464 of the query. The response MUST be signed with a TSIG record. Note
465 that the server is allowed to sign a response to unsigned client's
466 query due to modification to the RFC 2845 specified in Section 2.2
467 above. The signature in the TSIG record MUST be verified using the
468 procedure detailed in section 5, Sending and Verifying Signed
469 Messages. If the response is not signed, OR if the response is
470 signed but the signature is invalid, then an attacker has tampered
471 with the message in transit or has attempted to send the client a
472 false response. In this case, the client MAY continue waiting for a
473 response to its last TKEY query until the time period since the
474 client sent last TKEY query expires. Such a time period is specified
475 by the policy local to the client. This is a new option that allows
476 the DNS client to accept multiple answers for one query ID and select
477 one (not necessarily the first one) based on some criteria.
479 If the signature is verified, the context state is advanced to
480 Context Established. Proceed to section 3.2 for usage of the
483 3.1.3.2. Value of major_status == GSS_S_CONTINUE_NEEDED
485 If the last call to GSS_Init_sec_context yielded a major_status value
486 of GSS_S_CONTINUE_NEEDED, then the negotiation is not yet complete.
487 The server will return to the client a query response with a TKEY
488 record in the Answer section. If the DNS message error is not
489 NO_ERROR or error field in the TKEY record is not 0 (i.e., no error),
490 then the client MUST abandon this negotiation sequence. The client
491 MUST delete an active context by calling GSS_Delete_sec_context
492 providing the associated context_handle. The client MAY repeat the
493 negotiation sequence starting with the uninitialized state as
494 described in section 3.1. To prevent infinite looping the number of
495 attempts to establish a security context MUST be limited to ten or
498 If the DNS message error is NO_ERROR and the error field in the TKEY
499 record is 0 (i.e., no error), then the client MUST pass a token
500 specified in the Key Data field in the TKEY resource record to
506 Kwan, et al. Standards Track [Page 9]
508 RFC 3645 GSS-TSIG October 2003
511 GSS_Init_sec_context using the same parameters values as in previous
512 call except values for CONTEXT HANDLE input_context_handle and OCTET
513 STRING input_token as described below:
516 CONTEXT HANDLE input_context_handle = context_handle (this is the
517 context_handle corresponding to the key_name which is the
518 owner name of the TKEY record in the answer section in the
521 OCTET STRING input_token = token from Key field of
524 Depending on the following OUTPUT values of GSS_Init_sec_context
527 OCTET STRING output_token
529 the client MUST take one of the following actions:
531 If OUTPUT major_status is set to one of the following values:
533 GSS_S_DEFECTIVE_TOKEN
534 GSS_S_DEFECTIVE_CREDENTIAL
535 GSS_S_BAD_SIG (GSS_S_BAD_MIC)
537 GSS_S_CREDENTIALS_EXPIRED
540 GSS_S_DUPLICATE_TOKEN
547 the client MUST abandon this negotiation sequence. This means that
548 the client MUST delete an active context by calling
549 GSS_Delete_sec_context providing the associated context_handle. The
550 client MAY repeat the negotiation sequence starting with the
551 uninitialized state as described in section 3.1. To prevent infinite
552 looping the number of attempts to establish a security context MUST
553 be limited to ten or less.
555 If OUTPUT major_status is GSS_S_CONTINUE_NEEDED OR GSS_S_COMPLETE
556 then client MUST act as described below.
562 Kwan, et al. Standards Track [Page 10]
564 RFC 3645 GSS-TSIG October 2003
567 If the response from the server was signed, and the OUTPUT
568 major_status is GSS_S_COMPLETE,then the signature in the TSIG record
569 MUST be verified using the procedure detailed in section 5, Sending
570 and Verifying Signed Messages. If the signature is invalid, then the
571 client MUST abandon this negotiation sequence. This means that the
572 client MUST delete an active context by calling
573 GSS_Delete_sec_context providing the associated context_handle. The
574 client MAY repeat the negotiation sequence starting with the
575 uninitialized state as described in section 3.1. To prevent infinite
576 looping the number of attempts to establish a security context MUST
577 be limited to ten or less.
579 If major_status is GSS_S_CONTINUE_NEEDED the negotiation is not yet
580 finished. The token output_token MUST be passed to the server in a
581 TKEY record by repeating the negotiation sequence beginning with
582 section 3.1.2. The client MUST place a limit on the number of
583 continuations in a context negotiation to prevent endless looping.
584 Such limit SHOULD NOT exceed value of 10.
586 If major_status is GSS_S_COMPLETE and output_token is non-NULL, the
587 client-side component of the negotiation is complete but the token
588 output_token MUST be passed to the server by repeating the
589 negotiation sequence beginning with section 3.1.2.
591 If major_status is GSS_S_COMPLETE and output_token is NULL, context
592 negotiation is complete. The context state is advanced to Context
593 Established. Proceed to section 3.2 for usage of the security
596 3.2. Context Established
598 When context negotiation is complete, the handle context_handle MUST
599 be used for the generation and verification of transaction
602 The procedures for sending and receiving signed messages are
603 described in section 5, Sending and Verifying Signed Messages.
605 3.2.1. Terminating a Context
607 When the client is not intended to continue using the established
608 security context, the client SHOULD delete an active context by
609 calling GSS_Delete_sec_context providing the associated
610 context_handle, AND client SHOULD delete the established context on
611 the DNS server by using TKEY RR with the Mode field set to 5, i.e.,
612 "key deletion" [RFC2930].
618 Kwan, et al. Standards Track [Page 11]
620 RFC 3645 GSS-TSIG October 2003
623 4. Server Protocol Details
625 As on the client-side, the result of a successful context negotiation
626 is a context handle used in future generation and verification of the
627 transaction signatures.
629 A server MAY be managing several contexts with several clients.
630 Clients identify their contexts by providing a key name in their
631 request. The server maintains a mapping of key names to handles:
633 (key_name, context_handle)
635 4.1. Negotiating Context
637 A server MUST recognize TKEY queries as security context negotiation
640 4.1.1. Receive TKEY Query from Client
642 Upon receiving a query with QTYPE = TKEY, the server MUST examine
643 whether the Mode and Algorithm Name fields of the TKEY record in the
644 additional records section of the message contain values of 3 and
645 gss-tsig, respectively. If they do, then the (key_name,
646 context_handle) mapping table is searched for the key_name matching
647 the owner name of the TKEY record in the additional records section
648 of the query. If the name is found in the table and the security
649 context for this name is established and not expired, then the server
650 MUST respond to the query with BADNAME error in the TKEY error field.
651 If the name is found in the table and the security context is not
652 established, the corresponding context_handle is used in subsequent
653 GSS operations. If the name is found but the security context is
654 expired, then the server deletes this security context, as described
655 in Section 4.2.1, and interprets this query as a start of new
656 security context negotiation and performs operations described in
657 Section 4.1.2 and 4.1.3. If the name is not found, then the server
658 interprets this query as a start of new security context negotiation
659 and performs operations described in Section 4.1.2 and 4.1.3.
661 4.1.2. Call GSS_Accept_sec_context
663 The server performs its side of a context negotiation by calling
664 GSS_Accept_sec_context. The following input parameters MUST be used.
665 The outcome of the call is indicated with the output values below.
666 Consult Sections 2.2.2 "GSS_Accept_sec_context call" of the RFC 2743
667 [RFC2743] for syntax definitions.
674 Kwan, et al. Standards Track [Page 12]
676 RFC 3645 GSS-TSIG October 2003
680 CONTEXT HANDLE input_context_handle = 0 if new negotiation,
681 context_handle matching
682 key_name if ongoing negotiation
683 OCTET STRING input_token = token specified in the Key
684 field from TKEY RR (from Additional records Section of
687 CREDENTIAL HANDLE acceptor_cred_handle = NULL (NULL specifies "use
688 default"). Server MAY instead specify some other valid
689 handle to its credentials.
690 OCTET STRING chan_bindings = Any valid channel bindings
691 as specified in Section 1.1.6 "Channel Bindings" in [RFC2743]
695 CONTEXT_HANDLE output_context_handle
696 OCTET STRING output_token
698 INTERNAL NAME src_name
699 OBJECT IDENTIFIER mech_type
702 BOOLEAN replay_det_state
703 BOOLEAN sequence_state
706 BOOLEAN prot_ready_state
710 CONTEXT_HANDLE delegated_cred_handle
712 If this is the first call to GSS_Accept_sec_context in a new
713 negotiation, then output_context_handle is stored in the server's
714 key-mapping table as the context_handle that maps to the name of the
717 4.1.3. Send TKEY Query-Response to Client
719 The server MUST respond to the client with a TKEY query response with
720 RCODE = NOERROR, that contains a TKEY record in the answer section.
722 If OUTPUT major_status is one of the following errors the error field
723 in the TKEY record set to BADKEY.
730 Kwan, et al. Standards Track [Page 13]
732 RFC 3645 GSS-TSIG October 2003
735 GSS_S_DEFECTIVE_TOKEN
736 GSS_S_DEFECTIVE_CREDENTIAL
737 GSS_S_BAD_SIG (GSS_S_BAD_MIC)
738 GSS_S_DUPLICATE_TOKEN
741 GSS_S_CREDENTIALS_EXPIRED
747 If OUTPUT major_status is set to GSS_S_COMPLETE or
748 GSS_S_CONTINUE_NEEDED then server MUST act as described below.
750 If major_status is GSS_S_COMPLETE the server component of the
751 negotiation is finished. If output_token is non-NULL, then it MUST
752 be returned to the client in a Key Data field of the RDATA in TKEY.
753 The error field in the TKEY record is set to NOERROR. The message
754 MUST be signed with a TSIG record as described in section 5, Sending
755 and Verifying Signed Messages. Note that server is allowed to sign a
756 response to unsigned client's query due to modification to the RFC
757 2845 specified in Section 2.2 above. The context state is advanced
758 to Context Established. Section 4.2 discusses the usage of the
761 If major_status is GSS_S_COMPLETE and output_token is NULL, then the
762 TKEY record received from the client MUST be returned in the Answer
763 section of the response. The message MUST be signed with a TSIG
764 record as described in section 5, Sending and Verifying Signed
765 Messages. Note that server is allowed to sign a response to unsigned
766 client's query due to modification to the RFC 2845 specified in
767 section 2.2 above. The context state is advanced to Context
768 Established. Section 4.2 discusses the usage of the security
771 If major_status is GSS_S_CONTINUE_NEEDED, the server component of the
772 negotiation is not yet finished. The server responds to the TKEY
773 query with a standard query response, placing in the answer section a
774 TKEY record containing output_token in the Key Data RDATA field. The
775 error field in the TKEY record is set to NOERROR. The server MUST
776 limit the number of times that a given context is allowed to repeat,
777 to prevent endless looping. Such limit SHOULD NOT exceed value of
786 Kwan, et al. Standards Track [Page 14]
788 RFC 3645 GSS-TSIG October 2003
791 In all cases, except if major_status is GSS_S_COMPLETE and
792 output_token is NULL, other TKEY record fields MUST contain the
797 Algorithm Name = gss-tsig
798 Mode = 3 (GSS-API negotiation - per [RFC2930])
799 Key Size = size of output_token in octets
801 The remaining fields in the TKEY RDATA, i.e., Inception, Expiration,
802 Error, Other Size and Data Fields, MUST be set according to
805 4.2. Context Established
807 When context negotiation is complete, the handle context_handle is
808 used for the generation and verification of transaction signatures.
809 The handle is valid for a finite amount of time determined by the
810 underlying security mechanism. A server MAY unilaterally terminate a
811 context at any time (see section 4.2.1).
813 Server SHOULD limit the amount of memory used to cache established
816 The procedures for sending and receiving signed messages are given in
817 section 5, Sending and Verifying Signed Messages.
819 4.2.1. Terminating a Context
821 A server can terminate any established context at any time. The
822 server MAY hint to the client that the context is being deleted by
823 including a TKEY RR in a response with the Mode field set to 5, i.e.,
824 "key deletion" [RFC2930]. An active context is deleted by calling
825 GSS_Delete_sec_context providing the associated context_handle.
827 5. Sending and Verifying Signed Messages
829 5.1. Sending a Signed Message - Call GSS_GetMIC
831 The procedure for sending a signature-protected message is specified
832 in [RFC2845]. The data to be passed to the signature routine
833 includes the whole DNS message with specific TSIG variables appended.
834 For the exact format, see [RFC2845]. For this protocol, use the
835 following TSIG variable values:
842 Kwan, et al. Standards Track [Page 15]
844 RFC 3645 GSS-TSIG October 2003
848 NAME = key_name that identifies this context
850 Algorithm Name = gss-tsig
852 Assign the remaining fields in the TSIG RDATA appropriate values as
853 described in [RFC2845].
855 The signature is generated by calling GSS_GetMIC. The following
856 input parameters MUST be used. The outcome of the call is indicated
857 with the output values specified below. Consult Sections 2.3.1
858 "GSS_GetMIC call" of the RFC 2743[RFC2743] for syntax definitions.
861 CONTEXT HANDLE context_handle = context_handle for key_name
862 OCTET STRING message = outgoing message plus TSIG
863 variables (per [RFC2845])
864 INTEGER qop_req = 0 (0 requests a default
865 value). Caller MAY instead specify other valid value (for
866 details see Section 1.2.4 in [RFC2743])
871 OCTET STRING per_msg_token
873 If major_status is GSS_S_COMPLETE, then signature generation
874 succeeded. The signature in per_msg_token is inserted into the
875 Signature field of the TSIG RR and the message is transmitted.
877 If major_status is GSS_S_CONTEXT_EXPIRED, GSS_S_CREDENTIALS_EXPIRED
878 or GSS_S_FAILURE the caller MUST delete the security context, return
879 to the uninitialized state and SHOULD negotiate a new security
880 context, as described above in Section 3.1
882 If major_status is GSS_S_NO_CONTEXT, the caller MUST remove the entry
883 for key_name from the (target_ name, key_name, context_handle)
884 mapping table, return to the uninitialized state and SHOULD negotiate
885 a new security context, as described above in Section 3.1
887 If major_status is GSS_S_BAD_QOP, the caller SHOULD repeat the
888 GSS_GetMIC call with allowed QOP value. The number of such
889 repetitions MUST be limited to prevent infinite loops.
891 5.2. Verifying a Signed Message - Call GSS_VerifyMIC
893 The procedure for verifying a signature-protected message is
894 specified in [RFC2845].
898 Kwan, et al. Standards Track [Page 16]
900 RFC 3645 GSS-TSIG October 2003
903 The NAME of the TSIG record determines which context_handle maps to
904 the context that MUST be used to verify the signature. If the NAME
905 does not map to an established context, the server MUST send a
906 standard TSIG error response to the client indicating BADKEY in the
907 TSIG error field (as described in [RFC2845]).
909 For the GSS algorithm, a signature is verified by using
913 CONTEXT HANDLE context_handle = context_handle for key_name
914 OCTET STRING message = incoming message plus TSIG
915 variables (per [RFC2845])
916 OCTET STRING per_msg_token = Signature field from TSIG RR
923 If major_status is GSS_S_COMPLETE, the signature is authentic and the
924 message was delivered intact. Per [RFC2845], the timer values of the
925 TSIG record MUST also be valid before considering the message to be
926 authentic. The caller MUST not act on the request or response in the
927 message until these checks are verified.
929 When a server is processing a client request, the server MUST send a
930 standard TSIG error response to the client indicating BADKEY in the
931 TSIG error field as described in [RFC2845], if major_status is set to
932 one of the following values
934 GSS_S_DEFECTIVE_TOKEN
935 GSS_S_BAD_SIG (GSS_S_BAD_MIC)
936 GSS_S_DUPLICATE_TOKEN
940 GSS_S_CONTEXT_EXPIRED
944 If the timer values of the TSIG record are invalid, the message MUST
945 NOT be considered authentic. If this error checking fails when a
946 server is processing a client request, the appropriate error response
947 MUST be sent to the client according to [RFC2845].
954 Kwan, et al. Standards Track [Page 17]
956 RFC 3645 GSS-TSIG October 2003
959 6. Example usage of GSS-TSIG algorithm
961 This Section describes an example where a Client, client.example.com,
962 and a Server, server.example.com, establish a security context
963 according to the algorithm described above.
965 I. Client initializes security context negotiation
967 To establish a security context with a server, server.example.com, the
968 Client calls GSS_Init_sec_context with the following parameters.
969 (Note that some INPUT and OUTPUT parameters not critical for this
970 algorithm are not described in this example.)
972 CONTEXT HANDLE input_context_handle = 0
973 INTERNAL NAME targ_name = "DNS@server.example.com"
974 OCTET STRING input_token = NULL
975 BOOLEAN replay_det_req_flag = TRUE
976 BOOLEAN mutual_req_flag = TRUE
978 The OUTPUTS parameters returned by GSS_Init_sec_context include
979 INTEGER major_status = GSS_S_CONTINUE_NEEDED
980 CONTEXT HANDLE output_context_handle context_handle
981 OCTET STRING output_token output_token
982 BOOLEAN replay_det_state = TRUE
983 BOOLEAN mutual_state = TRUE
985 Client verifies that replay_det_state and mutual_state values are
986 TRUE. Since the major_status is GSS_S_CONTINUE_NEEDED, which is a
987 success OUTPUT major_status value, client stores context_handle that
988 maps to "DNS@server.example.com" and proceeds to the next step.
990 II. Client sends a query with QTYPE = TKEY to server
992 Client sends a query with QTYPE = TKEY for a client-generated globally
993 unique domain name string, 789.client.example.com.server.example.com.
994 Query contains a TKEY record in its Additional records section with
995 the following fields. (Note that some fields not specific to this
996 algorithm are not specified.)
998 NAME = 789.client.example.com.server.example.com.
1000 Algorithm Name = gss-tsig
1001 Mode = 3 (GSS-API negotiation - per [RFC2930])
1002 Key Size = size of output_token in octets
1003 Key Data = output_token
1010 Kwan, et al. Standards Track [Page 18]
1012 RFC 3645 GSS-TSIG October 2003
1015 After the key_name 789.client.example.com.server.example.com.
1016 is generated it is stored in the client's (target_name, key_name,
1017 context_handle) mapping table.
1019 III. Server receives a query with QTYPE = TKEY
1021 When server receives a query with QTYPE = TKEY, the server verifies
1022 that Mode and Algorithm fields in the TKEY record in the Additional
1023 records section of the query are set to 3 and "gss-tsig" respectively.
1024 It finds that the key_name 789.client.example.com.server.example.com.
1025 is not listed in its (key_name, context_handle) mapping table.
1027 IV. Server calls GSS_Accept_sec_context
1029 To continue security context negotiation server calls
1030 GSS_Accept_sec_context with the following parameters. (Note that
1031 some INPUT and OUTPUT parameters not critical for this algorithm
1032 are not described in this example.)
1035 CONTEXT HANDLE input_context_handle = 0
1036 OCTET STRING input_token = token specified in the Key
1037 field from TKEY RR (from Additional
1038 records section of the client's query)
1040 The OUTPUTS parameters returned by GSS_Accept_sec_context include
1041 INTEGER major_status = GSS_S_CONTINUE_NEEDED
1042 CONTEXT_HANDLE output_context_handle context_handle
1043 OCTET STRING output_token output_token
1045 Server stores the mapping of the
1046 789.client.example.com.server.example.com. to OUTPUT context_handle
1047 in its (key_name, context_handle) mapping table.
1049 V. Server responds to the TKEY query
1051 Since the major_status = GSS_S_CONTINUE_NEEDED in the last server's
1052 call to GSS_Accept_sec_context, the server responds to the TKEY query
1053 placing in the answer section a TKEY record containing output_token in
1054 the Key Data RDATA field. The error field in the TKEY record is set
1055 to 0. The RCODE in the query response is set to NOERROR.
1057 VI. Client processes token returned by server
1059 When the client receives the TKEY query response from the server, the
1060 client calls GSS_Init_sec_context with the following parameters.
1061 (Note that some INPUT and OUTPUT parameters not critical for this
1062 algorithm are not described in this example.)
1066 Kwan, et al. Standards Track [Page 19]
1068 RFC 3645 GSS-TSIG October 2003
1071 CONTEXT HANDLE input_context_handle = the context_handle stored
1072 in the client's mapping table entry (DNS@server.example.com.,
1073 789.client.example.com.server.example.com., context_handle)
1074 INTERNAL NAME targ_name = "DNS@server.example.com"
1075 OCTET STRING input_token = token from Key field of TKEY
1076 record from the Answer section of the server's response
1077 BOOLEAN replay_det_req_flag = TRUE
1078 BOOLEAN mutual_req_flag = TRUE
1080 The OUTPUTS parameters returned by GSS_Init_sec_context include
1081 INTEGER major_status = GSS_S_COMPLETE
1082 CONTEXT HANDLE output_context_handle = context_handle
1083 OCTET STRING output_token = output_token
1084 BOOLEAN replay_det_state = TRUE
1085 BOOLEAN mutual_state = TRUE
1087 Since the major_status is set to GSS_S_COMPLETE the client side
1088 security context is established, but since the output_token is not
1089 NULL client MUST send a TKEY query to the server as described below.
1091 VII. Client sends a query with QTYPE = TKEY to server
1093 Client sends to the server a TKEY query for the
1094 789.client.example.com.server.example.com. name. Query contains a
1095 TKEY record in its Additional records section with the following
1096 fields. (Note that some INPUT and OUTPUT parameters not critical to
1097 this algorithm are not described in this example.)
1099 NAME = 789.client.example.com.server.example.com.
1101 Algorithm Name = gss-tsig
1102 Mode = 3 (GSS-API negotiation - per [RFC2930])
1103 Key Size = size of output_token in octets
1104 Key Data = output_token
1106 VIII. Server receives a TKEY query
1108 When the server receives a TKEY query, the server verifies that Mode
1109 and Algorithm fields in the TKEY record in the Additional records
1110 section of the query are set to 3 and gss-tsig, respectively. It
1111 finds that the key_name 789.client.example.com.server.example.com. is
1112 listed in its (key_name, context_handle) mapping table.
1122 Kwan, et al. Standards Track [Page 20]
1124 RFC 3645 GSS-TSIG October 2003
1127 IX. Server calls GSS_Accept_sec_context
1129 To continue security context negotiation server calls
1130 GSS_Accept_sec_context with the following parameters (Note that some
1131 INPUT and OUTPUT parameters not critical for this algorithm are not
1132 described in this example)
1135 CONTEXT HANDLE input_context_handle = context_handle from the
1136 (789.client.example.com.server.example.com., context_handle)
1137 entry in the server's mapping table
1138 OCTET STRING input_token = token specified in the Key
1139 field of TKEY RR (from Additional records Section of
1142 The OUTPUTS parameters returned by GSS_Accept_sec_context include
1143 INTEGER major_status = GSS_S_COMPLETE
1144 CONTEXT_HANDLE output_context_handle = context_handle
1145 OCTET STRING output_token = NULL
1147 Since major_status = GSS_S_COMPLETE, the security context on the
1148 server side is established, but the server still needs to respond to
1149 the client's TKEY query, as described below. The security context
1150 state is advanced to Context Established.
1152 X. Server responds to the TKEY query
1154 Since the major_status = GSS_S_COMPLETE in the last server's call to
1155 GSS_Accept_sec_context and the output_token is NULL, the server
1156 responds to the TKEY query placing in the answer section a TKEY record
1157 that was sent by the client in the Additional records section of the
1158 client's latest TKEY query. In addition, this server places a
1159 TSIG record in additional records section of its response. Server
1160 calls GSS_GetMIC to generate a signature to include it in the TSIG
1161 record. The server specifies the following GSS_GetMIC INPUT
1164 CONTEXT HANDLE context_handle = context_handle from the
1165 (789.client.example.com.server.example.com., context_handle)
1166 entry in the server's mapping table
1167 OCTET STRING message = outgoing message plus TSIG
1168 variables (as described in [RFC2845])
1170 The OUTPUTS parameters returned by GSS_GetMIC include
1171 INTEGER major_status = GSS_S_COMPLETE
1172 OCTET STRING per_msg_token
1174 Signature field in the TSIG record is set to per_msg_token.
1178 Kwan, et al. Standards Track [Page 21]
1180 RFC 3645 GSS-TSIG October 2003
1183 XI. Client processes token returned by server
1185 Client receives the TKEY query response from the server. Since the
1186 major_status was GSS_S_COMPLETE in the last client's call to
1187 GSS_Init_sec_context, the client verifies that the server's response
1188 is signed. To validate the signature, the client calls
1189 GSS_VerifyMIC with the following parameters:
1192 CONTEXT HANDLE context_handle = context_handle for
1193 789.client.example.com.server.example.com. key_name
1194 OCTET STRING message = incoming message plus TSIG
1195 variables (as described in [RFC2845])
1196 OCTET STRING per_msg_token = Signature field from TSIG RR
1197 included in the server's query response
1199 Since the OUTPUTS parameter major_status = GSS_S_COMPLETE, the
1200 signature is validated, security negotiation is complete and the
1201 security context state is advanced to Context Established. These
1202 client and server will use the established security context to sign
1203 and validate the signatures when they exchange packets with each
1204 other until the context expires.
1206 7. Security Considerations
1208 This document describes a protocol for DNS security using GSS-API.
1209 The security provided by this protocol is only as effective as the
1210 security provided by the underlying GSS mechanisms.
1212 All the security considerations from RFC 2845, RFC 2930 and RFC 2743
1213 apply to the protocol described in this document.
1215 8. IANA Considerations
1217 The IANA has reserved the TSIG Algorithm name gss-tsig for the use in
1218 the Algorithm fields of TKEY and TSIG resource records. This
1219 Algorithm name refers to the algorithm described in this document.
1220 The requirement to have this name registered with IANA is specified
1225 The GSS API using SPNEGO [RFC2478] provides maximum flexibility to
1226 choose the underlying security mechanisms that enables security
1227 context negotiation. GSS API using SPNEGO [RFC2478] enables client
1228 and server to negotiate and choose such underlying security
1229 mechanisms on the fly. To support such flexibility, DNS clients and
1230 servers SHOULD specify SPNEGO mech_type in their GSS API calls. At
1234 Kwan, et al. Standards Track [Page 22]
1236 RFC 3645 GSS-TSIG October 2003
1239 the same time, in order to guarantee interoperability between DNS
1240 clients and servers that support GSS-TSIG it is required that
1242 - DNS servers specify SPNEGO mech_type
1243 - GSS APIs called by DNS client support Kerberos v5
1244 - GSS APIs called by DNS server support SPNEGO [RFC2478] and
1247 In addition to these, GSS APIs used by DNS client and server MAY also
1248 support other underlying security mechanisms.
1250 10. Intellectual Property Statement
1252 The IETF takes no position regarding the validity or scope of any
1253 intellectual property or other rights that might be claimed to
1254 pertain to the implementation or use of the technology described in
1255 this document or the extent to which any license under such rights
1256 might or might not be available; neither does it represent that it
1257 has made any effort to identify any such rights. Information on the
1258 IETF's procedures with respect to rights in standards-track and
1259 standards-related documentation can be found in BCP-11. Copies of
1260 claims of rights made available for publication and any assurances of
1261 licenses to be made available, or the result of an attempt made to
1262 obtain a general license or permission for the use of such
1263 proprietary rights by implementors or users of this specification can
1264 be obtained from the IETF Secretariat.
1266 The IETF invites any interested party to bring to its attention any
1267 copyrights, patents or patent applications, or other proprietary
1268 rights which may cover technology that may be required to practice
1269 this standard. Please address the information to the IETF Executive
1272 11. Acknowledgements
1274 The authors of this document would like to thank the following people
1275 for their contribution to this specification: Chuck Chan, Mike
1276 Swift, Ram Viswanathan, Olafur Gudmundsson, Donald E. Eastlake, 3rd
1290 Kwan, et al. Standards Track [Page 23]
1292 RFC 3645 GSS-TSIG October 2003
1297 12.1. Normative References
1299 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1300 Requirement Levels", BCP 14, RFC 2119, March 1997.
1302 [RFC2478] Baize, E. and D. Pinkas, "The Simple and Protected GSS-API
1303 Negotiation Mechanism", RFC 2478, December 1998.
1305 [RFC2743] Linn, J., "Generic Security Service Application Program
1306 Interface, Version 2 , Update 1", RFC 2743, January 2000.
1308 [RFC2845] Vixie, P., Gudmundsson, O., Eastlake 3rd, D. and B.
1309 Wellington, "Secret Key Transaction Authentication for DNS
1310 (TSIG)", RFC 2845, May 2000.
1312 [RFC2930] Eastlake 3rd, D., "Secret Key Establishment for DNS (TKEY
1313 RR)", RFC 2930, September 2000.
1315 12.2. Informative References
1318 [ISO11578] "Information technology", "Open Systems Interconnection",
1319 "Remote Procedure Call", ISO/IEC 11578:1996,
1320 http://www.iso.ch/cate/d2229.html.
1322 [RFC1034] Mockapetris, P., "Domain Names - Concepts and Facilities",
1323 STD 13, RFC 1034, November 1987.
1325 [RFC1035] Mockapetris, P., "Domain Names - Implementation and
1326 Specification", STD 13, RFC 1034, November 1987.
1328 [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC
1331 [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism
1332 (SPKM)", RFC 2025, October 1996.
1334 [RFC2137] Eastlake 3rd, D., "Secure Domain Name System Dynamic
1335 Update", RFC 2137, April 1997.
1337 [RFC2535] Eastlake 3rd, D., "Domain Name System Security Extensions",
1338 RFC 2535, March 1999.
1346 Kwan, et al. Standards Track [Page 24]
1348 RFC 3645 GSS-TSIG October 2003
1351 13. Authors' Addresses
1354 Microsoft Corporation
1358 EMail: skwan@microsoft.com
1361 Microsoft Corporation
1365 EMail: praeritg@microsoft.com
1368 Microsoft Corporation
1372 EMail: jamesg@microsoft.com
1375 Microsoft Corporation
1379 EMail: levone@microsoft.com
1386 EMail: randyhall@lucent.com
1389 Microsoft Corporation
1393 EMail: jwesth@microsoft.com
1402 Kwan, et al. Standards Track [Page 25]
1404 RFC 3645 GSS-TSIG October 2003
1407 14. Full Copyright Statement
1409 Copyright (C) The Internet Society (2003). All Rights Reserved.
1411 This document and translations of it may be copied and furnished to
1412 others, and derivative works that comment on or otherwise explain it
1413 or assist in its implementation may be prepared, copied, published
1414 and distributed, in whole or in part, without restriction of any
1415 kind, provided that the above copyright notice and this paragraph are
1416 included on all such copies and derivative works. However, this
1417 document itself may not be modified in any way, such as by removing
1418 the copyright notice or references to the Internet Society or other
1419 Internet organizations, except as needed for the purpose of
1420 developing Internet standards in which case the procedures for
1421 copyrights defined in the Internet Standards process must be
1422 followed, or as required to translate it into languages other than
1425 The limited permissions granted above are perpetual and will not be
1426 revoked by the Internet Society or its successors or assignees.
1428 This document and the information contained herein is provided on an
1429 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
1430 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
1431 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
1432 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
1433 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1437 Funding for the RFC Editor function is currently provided by the
1458 Kwan, et al. Standards Track [Page 26]