Internet Draft
INTERNET-DRAFT Stuart Kwan
Praerit Garg
James Gilroy
Microsoft Corp.
June 1999
<draft-skwan-gss-tsig-04.txt> Expires January 2000
GSS Algorithm for TSIG (GSS-TSIG)
Status of this Memo
This document is an Internet-Draft and is in full conformance
with all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other
documents at any time. It is inappropriate to use Internet-
Drafts as reference material or to cite them other than as
"work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Abstract
The 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) [RFC2078].
Expires January 2000 [Page 1]
INTERNET-DRAFT GSS-TSIG June 1999
Table of Contents
1: Introduction......................................................2
2: Protocol Overview.................................................3
2.1: GSS Details...................................................4
3: Client Protocol Details...........................................4
3.1: Negotiating Context...........................................4
3.1.1: Call GSS_Init_sec_context.................................5
3.1.2: Send TKEY Query to Server.................................6
3.1.3: Receive TKEY Query-Response from Server...................6
3.2: Context Established...........................................8
4: Server Protocol Details...........................................8
4.1: Negotiating Context...........................................8
4.1.1: Receive TKEY Query from Client............................9
4.1.2: Call GSS_Accept_sec_context...............................9
4.1.3: Send TKEY Query-Response to Client........................9
4.2: Context Established..........................................10
4.2.1: Terminating a Context....................................10
5: Sending and Verifying Signed Messages............................11
5.1: Sending a Signed Message - Call GSS_GetMIC...................11
5.2: Verifying a Signed Message - Call GSS_VerifyMIC..............12
6: Security Considerations..........................................12
7: Acknowledgements.................................................13
8: References.......................................................13
1. Introduction
The Secret Key Transaction Signature for DNS [TSIG] protocol was
developed to provide a lightweight alternative to full DNS security
[RFC2535] and secure dynamic update [RFC2137], where full security is
impractical due to implementation complexity, management overhead, or
computational cost.
The [TSIG] protocol is extensible through the definition of new
algorithms. This document specifies an algorithm based on the Generic
Security Service Application Program Interface (GSS-API) [RFC2078].
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 for one
transaction, whereas that same server may use TLS with a different
client.
Expires January 2000 [Page 2]
INTERNET-DRAFT GSS-TSIG June 1999
* 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.
2. Protocol Overview
Readers that are unfamiliar with the GSS-API concepts are encouraged
to read the characteristics and concepts section of [RFC2078] before
examining this protocol in detail.
In GSS, client and server interact to create a "security context".
The security context is 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.
Expires January 2000 [Page 3]
INTERNET-DRAFT GSS-TSIG June 1999
2.1 GSS Details
Client and server must be locally authenticated and have acquired
default credentials per [RFC2078] before using this protocol.
Not all flags used in GSS-API interfaces are specified in this
document. Where omitted, clients and servers may select the default
or use a value based on local system policy.
Not all error return values from GSS-API interfaces are specified in
this document. When errors are encountered, the caller should act
appropriately.
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 handles to servers,
(target_server_name, key_name, context_handle)
The value key_name also identifies a context handle, and is used on
the wire to indicate to a server which context should be used to
process the current request.
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 [TKEY] 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 [TKEY].
Expires January 2000 [Page 4]
INTERNET-DRAFT GSS-TSIG June 1999
3.1.1 Call GSS_Init_sec_context
The client obtains the first token by calling GSS_Init_sec_context.
The following input parameters are used. The outcome of the call
is indicated with the output values below. Consult [RFC2078] for
syntax definitions.
INPUTS
CONTEXT HANDLE input_context_handle = 0
INTERNAL NAME targ_name = DNS/
OCTET STRING input_token = NULL
BOOLEAN replay_det_req_flag = TRUE
BOOLEAN mutual_req_flag = TRUE
BOOLEAN deleg_req_flag = TRUE (optional)
OUTPUTS
INTEGER major_status
CONTEXT HANDLE output_context_handle
OCTET STRING output_token
BOOLEAN replay_det_state
BOOLEAN mutual_state
The values of replay_det_state and mutual_state indicate if the
security package can provide replay detection and mutual
authentication, respectively. If one or both of these values
are FALSE, the client must abandon this protocol.
The deleg_req_flag is optional, and can be used if the client wants
the server to be able to call out to other services under the
context of the client.
If major_status indicates an error, the client must abandon the
protocol. Success values of major_status are GSS_S_CONTINUE_NEEDED
and GSS_S_COMPLETE. The exact success code is important during later
processing.
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_server_name.
Expires January 2000 [Page 5]
INTERNET-DRAFT GSS-TSIG June 1999
3.1.2 Send TKEY Query to Server
The output_token from GSS_Init_sec_context is transmitted to the
server in a query request for a TKEY record. The token itself
will be placed in a TKEY record in the additional records section of
the query. The domain-like name of the TKEY record set queried for
and the name of the supplied TKEY record in the additional section
will uniquely identify the security context to both the client and
server, and thus the client should use a value which is globally
unique.
TKEY Record
NAME = client-generated globally unique domain name string
(see [TKEY])
RDATA
Algorithm Name = gss-tsig.microsoft.com
Mode = 3 (GSS-API negotiation - see [TKEY])
Key Size = size of output_token
Key = output_token
Assign the remaining fields in the TKEY RDATA appropriate values
per [TKEY].
If the last call to GSS_Init_sec_context yielded a major_status value
of GSS_S_COMPLETE, then the message should be signed with a TSIG
record before being sent to the server. See section 5, Sending
and Verifying Signed Messages, for the signing procedure.
The query is transmitted to the server.
3.1.3 Receive TKEY Query-Response from Server
The server will return a standard TKEY query-response (see [TKEY]).
The response may indicate that TKEY is not supported, or that the
GSS-API mode and algorithm are not supported. If this is the case,
the client must abandon this algorithm.
If the value of the Error field in the TKEY RDATA (TKEY.Error) is
BADKEY, then the token provided by the client was invalid. The
client must abandon this algorithm.
If TKEY.Error indicates success, then the client may continue. The
next processing step depends on the value of major_status from the
most recent call to GSS_Init_sec_context: either GSS_S_COMPLETE or
GSS_S_CONTINUE.
Expires January 2000 [Page 6]
INTERNET-DRAFT GSS-TSIG June 1999
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 will be in the form of a NOERROR query response
containing the last client supplied TKEY record in the answer section
of the query. The response may also be signed with a TSIG record,
and if present this signature must be verified using the procedure
detailed in section 5, Sending and Verifying Signed Messages.
If the message verification completes without an error, or if a TSIG
signature was not included, 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
If the last call to GSS_Init_sec_context yielded a major_status value
of GSS_S_CONTINUE, then the negotiation is not yet complete. The
server will respond to the TKEY query with a NOERROR query response
that contains a TKEY record in the answer section. The TKEY record
contains a token that is passed to GSS_Init_sec_context using the
parameters from the previous call and the following modifications:
INPUTS
CONTEXT HANDLE input_context_handle = context_handle
OCTET STRING input_token = token from Key field of
TKEY record
OUTPUTS
INTEGER major_status
OCTET STRING output_token
If major_status indicates an error, the client must abandon this
algorithm. Success values are GSS_S_CONTINUE and GSS_S_COMPLETE.
If major_status is GSS_S_CONTINUE the negotiation is not yet
finished. The token output_token must again be passed to the server
in a TKEY record. The negotiation sequence is repeated beginning
with section 3.1.2. The client should place a limit on the number
of continuations in a context negotiation to prevent endless
looping.
Expires January 2000 [Page 7]
INTERNET-DRAFT GSS-TSIG June 1999
If major_status is GSS_S_COMPLETE and output_token is non-NULL,
the client-side component of the negotiation is complete but the
token output_token must be passed to the server. The negotiation
sequence is repeated beginning with section 3.1.2.
If major_status is GSS_S_COMPLETE and output_token is NULL, context
negotiation is complete. The response from the server may be signed
with a TSIG record, and if present this signature must be verified
using the procedure detailed in section 5, Sending and
Verifying Signed Messages.
If the message verification completes without an error, or if a TSIG
signature was not included, the context state is advanced to Context
Established. Proceed to section 3.2 for usage of the security
context.
3.2 Context Established
When context negotiation is complete, the handle context_handle is
used for the generation and verification of transaction signatures.
The procedures for sending and receiving signed messages are given in
section 5, Sending and Verifying Signed Messages.
4. Server Protocol Details
As on the client-side, the result of a successful context negotiation
is a context handle used in future processing.
A server may be managing several contexts with several clients.
Clients identify their contexts by providing a key name in their
request. The server maintains a mapping of key names to handles:
(key_name, context_handle)
4.1 Negotiating Context
A server recognizes TKEY queries as security context negotiation
messages.
Expires January 2000 [Page 8]
INTERNET-DRAFT GSS-TSIG June 1999
4.1.1 Receive TKEY Query from Client
Upon receiving a TKEY query, the server must examine the Mode and
Algorithm Name fields to see if they match this algorithm. If they
match, the (key_name, context_handle) mapping table is searched for
the NAME value of the TKEY record. If the name is found in the table,
the corresponding context_handle is used in following GSS operations.
If the name is not found a new negotiation is started.
4.1.2 Call GSS_Accept_sec_context
The server performs its side of a context negotiation by calling
GSS_Accept_sec_context with the token provided by the client in the
TKEY record.
The server calls GSS_Accept_sec_context:
INPUTS
CONTEXT HANDLE input_context_handle = 0 if new negotiation,
context_handle if ongoing
OCTET STRING input_token = Key field from TKEY RR
OUTPUTS
INTEGER major_status
CONTEXT_HANDLE output_context_handle
OCTET STRING output_token
If this is the first call to GSS_Accept_sec_context in a new
negotiation, then output_context_handle is stored in the server's
key-mapping table as the context_handle that maps to the name of the
TKEY record.
4.1.3 Send TKEY Query-Response to Client
If major_status returns a GSS failure code, the negotiation has
failed. The server must respond to the client with a standard
TKEY query-response where the TKEY error field value is set to
BADKEY.
Success values for major_status are GSS_S_COMPLETE or GSS_S_CONTINUE.
Expires January 2000 [Page 9]
INTERNET-DRAFT GSS-TSIG June 1999
If major_status is GSS_S_COMPLETE the server component of the
negotiation is finished. The message from the client may be signed
with a TSIG RR, and if present this signature must be verified
using the procedure detailed in section 5, Sending and
Verifying Signed Messages. The server responds to the TKEY query
using a standard query response. If output_token is non-NULL, then it
must be returned to the client in a TKEY in the Answer section of the
response. If output_token is NULL, then the TKEY record received from
the client must be returned in the Answer section of the response.
The answer should be signed with a TSIG record per the procedure given
in section 5, Sending and Verifying Signed Messages.
The context state is advanced to Established. Section 4.2 discusses
the usage of the security context.
If major_status is GSS_S_CONTINUE, the server component of the
negotiation is not yet finished. The server responds to the TKEY
query with a standard query response, placing a TKEY record containing
output_token in the answer section. The negotiation sequence then
repeats beginning with section 4.1.1. The server must limit the
number of times that a given context is allowed to repeat, to prevent
endless looping.
4.2 Context Established
When context negotiation is complete, the handle context_handle
is used for the generation and verification of transaction signatures.
The handle is valid for a finite amount of time determined by the
underlying security mechanism. A server may unilaterally terminate
a context at any time.
The procedures for sending and receiving signed messages are given in
section 5, Sending and Verifying Signed Messages.
4.2.1 Terminating a Context
A server can terminate any established context at any time. The
server may hint to the client that the context is being deleted
by including a TKEY RR in a response with the mode field set to
"key deletion". See [TKEY] for more details.
An active context is deleted by calling GSS_Delete_sec_context
providing the associated context_handle.
Expires January 2000 [Page 10]
INTERNET-DRAFT GSS-TSIG June 1999
5. Sending and Verifying Signed Messages
5.1 Sending a Signed Message - Call GSS_GetMIC
The procedure for sending a signature-protected message is specified
in [TSIG]. The data to be passed to the signature routine includes
the whole DNS message with specific TSIG variables appended. For the
exact format, see [TSIG]. For this protocol, use the following
TSIG variable values:
TSIG Record
NAME = key_name that identifies this context
RDATA
Algorithm Name = gss-tsig.microsoft.com
Assign the remaining fields in the TKEY RDATA appropriate values
per [TKEY].
For the GSS algorithm, the signature is generated by calling
GSS_GetMIC:
INPUTS
CONTEXT HANDLE context_handle = context_handle for key_name
OCTET STRING message = outgoing message plus TSIG
variables (see [TSIG])
OUTPUTS
INTEGER major_status
OCTET STRING per_msg_token
If major_status is GSS_S_COMPLETE, then signature generation
succeeded. The signature in per_msg_token is inserted into the
Signature field of the TSIG RR and the message is transmitted.
If major_status is GSS_S_CONTEXT_EXPIRED or GSS_S_CREDENTIALS_EXPIRED,
the caller needs to return to the uninitialized state and negotiate
a new security context.
Expires January 2000 [Page 11]
INTERNET-DRAFT GSS-TSIG June 1999
5.2 Verifying a Signed Message - Call GSS_VerifyMIC
The procedure for verifying a signature-protected message is specified
in [TSIG].
The NAME of the TSIG record determines which context_handle
maps to this context. If the NAME does not map to a currently active
context, the server must send a standard TSIG error response to the
client indicating BADKEY in the TSIG error field (see [TSIG]).
For the GSS algorithm, a signature is verified by using GSS_VerifyMIC:
INPUTS
CONTEXT HANDLE context_handle = context_handle for key_name
OCTET STRING message = incoming message plus TSIG
variables (see [TSIG])
OCTET STRING per_msg_token = Signature field from TSIG RR
OUTPUTS
INTEGER major_status
If major_status is GSS_S_COMPLETE, the signature is authentic and the
message was delivered intact. Per [TSIG], the timer values of the
TSIG record must also be valid before considering the message to be
authentic. The caller must not act on the request or response in the
message until these checks are verified.
If major_status is GSS_S_CONTEXT_EXPIRED, the negotiated context is no
longer valid. If this failure occurs when a server is processing a
client request, the server must send a standard TSIG error response
to the client indicating BADKEY in the TSIG error field (see [TSIG]).
If major_status is any other error code or if the timer values of the
TSIG record are invalid, the message must not be considered authentic.
If this error checking fails when a server is processing a client
request, the appropriate error response must be sent to the client
per [TSIG].
6. Security Considerations
This document describes a protocol for DNS security using GSS-API.
The security provided by this protocol is only as effective as the
security provided by the underlying GSS mechanisms.
Expires January 2000 [Page 12]
INTERNET-DRAFT GSS-TSIG June 1999
7. Acknowledgements
The authors of this document would like to thank the following people
for their contribution to this specification: Chuck Chan, Mike Swift,
Ram Viswanathan and Donald E. Eastlake 3rd.
8. References
[RFC2078] J. Linn, "Generic Security Service Application Program
Interface, Version 2," RFC 2078, OpenVision Technologies,
January 1997.
[TSIG] P. Vixie, O. Gudmundsson, D. Eastlake, "Secret Key
Transaction Signatures for DNS (TSIG),"
draft-ietf-dnsind-tsig-*..txt, ISC, TIS, Cybercash.
[TKEY] D. Eastlake 3rd, "Secret Key Establishment for DNS (TKEY
RR)," draft-ietf-dnssec-tkey-*.txt.
[RFC2535] D. Eastlake 3rd, "Domain Name System Security Extensions,"
RFC 2535, IBM, March 1999.
[RFC2137] D. Eastlake 3rd, "Secure Domain Name System Dynamic Update,"
RFC 2137, CyberCash, April 1997.
9. Author's Addresses
Stuart Kwan Praerit Garg
Microsoft Corporation Microsoft Corporation
One Microsoft Way One Microsoft Way
Redmond, WA 98052 Redmond, WA 98052
USA USA
James Gilroy
Microsoft Corporation
One Microsoft Way
Redmond, WA 98052
USA