Request for Comments: 3645 P. Garg
Updates: 2845 J. Gilroy
Category: Standards Track L. Esibov
J. Westhead
Microsoft Corp.
R. Hall
Lucent Technologies
October 2003
Generic Security Service Algorithm for
Secret Key Transaction Authentication for DNS (GSS-TSIG)
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2003). All Rights Reserved.
Abstract
The Secret Key Transaction Authentication for DNS (TSIG) protocol
provides transaction level authentication for DNS. TSIG is
extensible through the definition of new algorithms. This document
specifies an algorithm based on the Generic Security Service
Application Program Interface (GSS-API) (RFC2743). This document
updates RFC 2845.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Algorithm Overview . . . . . . . . . . . . . . . . . . . . . . 3
2.1. GSS Details. . . . . . . . . . . . . . . . . . . . . . . 4
2.2. Modifications to the TSIG protocol (RFC 2845). . . . . . 4
3. Client Protocol Details. . . . . . . . . . . . . . . . . . . . 5
3.1. Negotiating Context. . . . . . . . . . . . . . . . . . . 5
3.1.1. Call GSS_Init_sec_context. . . . . . . . . . . . . 6
3.1.2. Send TKEY Query to Server. . . . . . . . . . . . . 8
3.1.3. Receive TKEY Query-Response from Server. . . . . . 8
3.2. Context Established. . . . . . . . . . . . . . . . . . . 11
3.2.1. Terminating a Context. . . . . . . . . . . . . . . 11
4. Server Protocol Details. . . . . . . . . . . . . . . . . . . . 12
4.1. Negotiating Context. . . . . . . . . . . . . . . . . . . 12
4.1.1. Receive TKEY Query from Client . . . . . . . . . . 12
4.1.2. Call GSS_Accept_sec_context. . . . . . . . . . . . 12
4.1.3. Send TKEY Query-Response to Client . . . . . . . . 13
4.2. Context Established. . . . . . . . . . . . . . . . . . . 15
4.2.1. Terminating a Context. . . . . . . . . . . . . . . 15
5. Sending and Verifying Signed Messages. . . . . . . . . . . . . 15
5.1. Sending a Signed Message - Call GSS_GetMIC . . . . . . . 15
5.2. Verifying a Signed Message - Call GSS_VerifyMIC. . . . . 16
6. Example usage of GSS-TSIG algorithm. . . . . . . . . . . . . . 18
7. Security Considerations. . . . . . . . . . . . . . . . . . . . 22
8. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 22
9. Conformance. . . . . . . . . . . . . . . . . . . . . . . . . . 22
10. Intellectual Property Statement. . . . . . . . . . . . . . . . 23
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 23
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24
12.1. Normative References. . . . . . . . . . . . . . . . . . 24
12.2. Informative References. . . . . . . . . . . . . . . . . 24
13. Authors’ Addresses . . . . . . . . . . . . . . . . . . . . . . 25
14. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 26
1. Introduction
The Secret Key Transaction Authentication for DNS (TSIG) [RFC2845]
protocol was developed to provide a lightweight authentication and
integrity of messages between two DNS entities, such as client and
server or server and server. TSIG can be used to protect dynamic
update messages, authenticate regular message or to off-load
complicated DNSSEC [RFC2535] processing from a client to a server and
still allow the client to be assured of the integrity of the answers.
The TSIG protocol [RFC2845] is extensible through the definition of
new algorithms. This document specifies an algorithm based on the
Generic Security Service Application Program Interface (GSS-API)
[RFC2743]. GSS-API is a framework that provides an abstraction of
security to the application protocol developer. The security
services offered can include authentication, integrity, and
confidentiality.
The GSS-API framework has several benefits:
* Mechanism and protocol independence. The underlying mechanisms
that realize the security services can be negotiated on the fly
and varied over time. For example, a client and server MAY use
Kerberos [RFC1964] for one transaction, whereas that same server
MAY use SPKM [RFC2025] with a different client.
* The protocol developer is removed from the responsibility of
creating and managing a security infrastructure. For example, the
developer does not need to create new key distribution or key
management systems. Instead the developer relies on the security
service mechanism to manage this on its behalf.
The scope of this document is limited to the description of an
authentication mechanism only. It does not discuss and/or propose an
authorization mechanism. Readers that are unfamiliar with GSS-API
concepts are encouraged to read the characteristics and concepts
section of [RFC2743] before examining this protocol in detail. It is
also assumed that the reader is familiar with [RFC2845], [RFC2930],
[RFC1034] and [RFC1035].
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",
"RECOMMENDED", and "MAY" in this document are to be interpreted as
described in BCP 14, RFC 2119 [RFC2119].
2. Algorithm Overview
In GSS, client and server interact to create a "security context".
The security context can be used to create and verify transaction
signatures on messages between the two parties. A unique security
context is required for each unique connection between client and
server.
Creating a security context involves a negotiation between client and
server. Once a context has been established, it has a finite
lifetime for which it can be used to secure messages. Thus there are
three states of a context associated with a connection:
+----------+
| |
V |
+---------------+ |
| Uninitialized | |
| | |
+---------------+ |
| |
V |
+---------------+ |
| Negotiating | |
| Context | |
+---------------+ |
| |
V |
+---------------+ |
| Context | |
| Established | |
+---------------+ |
| |
+----------+
Every connection begins in the uninitialized state.
2.1. GSS Details
Client and server MUST be locally authenticated and have acquired
default credentials before using this protocol as specified in
Section 1.1.1 "Credentials" in RFC 2743 [RFC2743].
The GSS-TSIG algorithm consists of two stages:
I. Establish security context. The Client and Server use the
GSS_Init_sec_context and GSS_Accept_sec_context APIs to generate
the tokens that they pass to each other using [RFC2930] as a
transport mechanism.
II. Once the security context is established it is used to generate
and verify signatures using GSS_GetMIC and GSS_VerifyMIC APIs.
These signatures are exchanged by the Client and Server as a part
of the TSIG records exchanged in DNS messages sent between the
Client and Server, as described in [RFC2845].
2.2. Modifications to the TSIG protocol (RFC 2845)
Modification to RFC 2845 allows use of TSIG through signing server’s
response in an explicitly specified place in multi message exchange
between two DNS entities even if client’s request wasn’t signed.
Specifically, Section 4.2 of RFC 2845 MUST be modified as follows:
Replace:
"The server MUST not generate a signed response to an unsigned
request."
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."
3. Client Protocol Details
A unique context is required for each server to which the client
sends secure messages. A context is identified by a context handle.
A client maintains a mapping of servers to handles:
(target_name, key_name, context_handle)
The value key_name also identifies a context handle. The key_name is
the owner name of the TKEY and TSIG records sent between a client and
a server to indicate to each other which context MUST be used to
process the current request.
DNS client and server MAY use various underlying security mechanisms
to establish security context as described in sections 3 and 4. At
the same time, in order to guarantee interoperability between DNS
clients and servers that support GSS-TSIG it is REQUIRED that
security mechanism used by client enables use of Kerberos v5 (see
Section 9 for more information).
3.1. Negotiating Context
In GSS, establishing a security context involves the passing of
opaque tokens between the client and the server. The client
generates the initial token and sends it to the server. The server
processes the token and if necessary, returns a subsequent token to
the client. The client processes this token, and so on, until the
negotiation is complete. The number of times the client and server
exchange tokens depends on the underlying security mechanism. A
completed negotiation results in a context handle.
The TKEY resource record [RFC2930] is used as the vehicle to transfer
tokens between client and server. The TKEY record is a general
mechanism for establishing secret keys for use with TSIG. For more
information, see [RFC2930].
3.1.1. Call GSS_Init_sec_context
To obtain the first token to be sent to a server, a client MUST call
GSS_Init_sec_context API.
The following input parameters MUST be used. The outcome of the call
is indicated with the output values below. Consult Sections 2.2.1,
"GSS_Init_sec_context call", of [RFC2743] for syntax definitions.
INPUTS
CREDENTIAL HANDLE claimant_cred_handle = NULL (NULL specifies "use
default"). Client MAY instead specify some other valid
handle to its credentials.
CONTEXT HANDLE input_context_handle = 0
INTERNAL NAME targ_name = "DNS@<target_server_name>"
OBJECT IDENTIFIER mech_type = Underlying security
mechanism chosen by implementers. To guarantee
interoperability of the implementations of the GSS-TSIG
mechanism client MUST specify a valid underlying security
mechanism that enables use of Kerberos v5 (see Section 9 for
more information).
OCTET STRING input_token = NULL
BOOLEAN replay_det_req_flag = TRUE
BOOLEAN mutual_req_flag = TRUE
BOOLEAN deleg_req_flag = TRUE
BOOLEAN sequence_req_flag = TRUE
BOOLEAN anon_req_flag = FALSE
BOOLEAN integ_req_flag = TRUE
INTEGER lifetime_req = 0 (0 requests a default
value). Client MAY instead specify another upper bound for the
lifetime of the context to be established in seconds.
OCTET STRING chan_bindings = Any valid channel bindings
as specified in Section 1.1.6 "Channel Bindings" in [RFC2743]
OUTPUTS
INTEGER major_status
CONTEXT HANDLE output_context_handle
OCTET STRING output_token
BOOLEAN replay_det_state
BOOLEAN mutual_state
INTEGER minor_status
OBJECT IDENTIFIER mech_type
BOOLEAN deleg_state
BOOLEAN sequence_state
BOOLEAN anon_state
BOOLEAN trans_state
BOOLEAN prot_ready_state
BOOLEAN conf_avail
BOOLEAN integ_avail
INTEGER lifetime_rec
If returned major_status is set to one of the following errors:
GSS_S_DEFECTIVE_TOKEN
GSS_S_DEFECTIVE_CREDENTIAL
GSS_S_BAD_SIG (GSS_S_BAD_MIC)
GSS_S_NO_CRED
GSS_S_CREDENTIALS_EXPIRED
GSS_S_BAD_BINDINGS
GSS_S_OLD_TOKEN
GSS_S_DUPLICATE_TOKEN
GSS_S_NO_CONTEXT
GSS_S_BAD_NAMETYPE
GSS_S_BAD_NAME
GSS_S_BAD_MECH
GSS_S_FAILURE
then the client MUST abandon the algorithm and MUST NOT use the GSS-
TSIG algorithm to establish this security context. This document
does not prescribe which other mechanism could be used to establish a
security context. Next time when this client needs to establish
security context, the client MAY use GSS-TSIG algorithm.
Success values of major_status are GSS_S_CONTINUE_NEEDED and
GSS_S_COMPLETE. The exact success code is important during later
processing.
The values of replay_det_state and mutual_state indicate if the
security package provides replay detection and mutual authentication,
respectively. If returned major_status is GSS_S_COMPLETE AND one or
both of these values are FALSE, the client MUST abandon this
algorithm.
Client’s behavior MAY depend on other OUTPUT parameters according to
the policy local to the client.
The handle output_context_handle is unique to this negotiation and is
stored in the client’s mapping table as the context_handle that maps
to target_name.
3.1.2. Send TKEY Query to Server
An opaque output_token returned by GSS_Init_sec_context is
transmitted to the server in a query request with QTYPE=TKEY. The
token itself will be placed in a Key Data field of the RDATA field in
the TKEY resource record in the additional records section of the
query. The owner name of the TKEY resource record set queried for
and the owner name of the supplied TKEY resource record in the
additional records section MUST be the same. This name uniquely
identifies the security context to both the client and server, and
thus the client SHOULD use a value which is globally unique as
described in [RFC2930]. To achieve global uniqueness, the name MAY
contain a UUID/GUID [ISO11578].
TKEY Record
NAME = client-generated globally unique domain name string
(as described in [RFC2930])
RDATA
Algorithm Name = gss-tsig
Mode = 3 (GSS-API negotiation - per [RFC2930])
Key Size = size of output_token in octets
Key Data = output_token
The remaining fields in the TKEY RDATA, i.e., Inception, Expiration,
Error, Other Size and Data Fields, MUST be set according to
[RFC2930].
The query is transmitted to the server.
Note: if the original client call to GSS_Init_sec_context returned
any major_status other than GSS_S_CONTINUE_NEEDED or GSS_S_COMPLETE,
then the client MUST NOT send TKEY query. Client’s behavior in this
case is described above in Section 3.1.1.
3.1.3. Receive TKEY Query-Response from Server
Upon the reception of the TKEY query the DNS server MUST respond
according to the description in Section 4. This section specifies
the behavior of the client after it receives the matching response to
its query.
The next processing step depends on the value of major_status from
the most recent call that client performed to GSS_Init_sec_context:
either GSS_S_COMPLETE or GSS_S_CONTINUE.
3.1.3.1. Value of major_status == GSS_S_COMPLETE
If the last call to GSS_Init_sec_context yielded a major_status value
of GSS_S_COMPLETE and a non-NULL output_token was sent to the server,
then the client side component of the negotiation is complete and the
client is awaiting confirmation from the server.
Confirmation is in the form of a query response with RCODE=NOERROR
and with the last client supplied TKEY record in the answer section
of the query. The response MUST be signed with a TSIG record. Note
that the server is allowed to sign a response to unsigned client’s
query due to modification to the RFC 2845 specified in Section 2.2
above. The signature in the TSIG record MUST be verified using the
procedure detailed in section 5, Sending and Verifying Signed
Messages. If the response is not signed, OR if the response is
signed but the signature is invalid, then an attacker has tampered
with the message in transit or has attempted to send the client a
false response. In this case, the client MAY continue waiting for a
response to its last TKEY query until the time period since the
client sent last TKEY query expires. Such a time period is specified
by the policy local to the client. This is a new option that allows
the DNS client to accept multiple answers for one query ID and select
one (not necessarily the first one) based on some criteria.
If the signature is verified, the context state is advanced to
Context Established. Proceed to section 3.2 for usage of the
security context.
3.1.3.2. Value of major_status == GSS_S_CONTINUE_NEEDED
If the last call to GSS_Init_sec_context yielded a major_status value
of GSS_S_CONTINUE_NEEDED, then the negotiation is not yet complete.
The server will return to the client a query response with a TKEY
record in the Answer section. If the DNS message error is not
NO_ERROR or error field in the TKEY record is not 0 (i.e., no error),
then the client MUST abandon this negotiation sequence. The client
MUST delete an active context by calling GSS_Delete_sec_context
providing the associated context_handle. The client MAY repeat the
negotiation sequence starting with the uninitialized state as
described in section 3.1. To prevent infinite looping the number of
attempts to establish a security context MUST be limited to ten or
less.
If the DNS message error is NO_ERROR and the error field in the TKEY
record is 0 (i.e., no error), then the client MUST pass a token
specified in the Key Data field in the TKEY resource record to
GSS_Init_sec_context using the same parameters values as in previous
call except values for CONTEXT HANDLE input_context_handle and OCTET
STRING input_token as described below:
INPUTS
CONTEXT HANDLE input_context_handle = context_handle (this is the
context_handle corresponding to the key_name which is the
owner name of the TKEY record in the answer section in the
TKEY query response)
OCTET STRING input_token = token from Key field of
TKEY record
Depending on the following OUTPUT values of GSS_Init_sec_context
INTEGER major_status
OCTET STRING output_token
the client MUST take one of the following actions:
If OUTPUT major_status is set to one of the following values:
GSS_S_DEFECTIVE_TOKEN
GSS_S_DEFECTIVE_CREDENTIAL
GSS_S_BAD_SIG (GSS_S_BAD_MIC)
GSS_S_NO_CRED
GSS_S_CREDENTIALS_EXPIRED
GSS_S_BAD_BINDINGS
GSS_S_OLD_TOKEN
GSS_S_DUPLICATE_TOKEN
GSS_S_NO_CONTEXT
GSS_S_BAD_NAMETYPE
GSS_S_BAD_NAME
GSS_S_BAD_MECH
GSS_S_FAILURE
the client MUST abandon this negotiation sequence. This means that
the client MUST delete an active context by calling
GSS_Delete_sec_context providing the associated context_handle. The
client MAY repeat the negotiation sequence starting with the
uninitialized state as described in section 3.1. To prevent infinite