diff options
Diffstat (limited to 'contrib/bind9/doc/rfc/rfc3645.txt')
| -rw-r--r-- | contrib/bind9/doc/rfc/rfc3645.txt | 1459 |
1 files changed, 0 insertions, 1459 deletions
diff --git a/contrib/bind9/doc/rfc/rfc3645.txt b/contrib/bind9/doc/rfc/rfc3645.txt deleted file mode 100644 index 6126678..0000000 --- a/contrib/bind9/doc/rfc/rfc3645.txt +++ /dev/null @@ -1,1459 +0,0 @@ - - - - - - -Network Working Group S. Kwan -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. - - - - - - - - - - - - - - - - - -Kwan, et al. Standards Track [Page 1] - -RFC 3645 GSS-TSIG October 2003 - - -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. - - - - - - - -Kwan, et al. Standards Track [Page 2] - -RFC 3645 GSS-TSIG October 2003 - - - 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: - - - - - -Kwan, et al. Standards Track [Page 3] - -RFC 3645 GSS-TSIG October 2003 - - - +----------+ - | | - 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. - - - -Kwan, et al. Standards Track [Page 4] - -RFC 3645 GSS-TSIG October 2003 - - - 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. - - - - - - - -Kwan, et al. Standards Track [Page 5] - -RFC 3645 GSS-TSIG October 2003 - - - 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 - - - -Kwan, et al. Standards Track [Page 6] - -RFC 3645 GSS-TSIG October 2003 - - - 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. - - - - - -Kwan, et al. Standards Track [Page 7] - -RFC 3645 GSS-TSIG October 2003 - - -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. - - - - - - - -Kwan, et al. Standards Track [Page 8] - -RFC 3645 GSS-TSIG October 2003 - - -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 - - - - - -Kwan, et al. Standards Track [Page 9] - -RFC 3645 GSS-TSIG October 2003 - - - 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 - looping the number of attempts to establish a security context MUST - be limited to ten or less. - - If OUTPUT major_status is GSS_S_CONTINUE_NEEDED OR GSS_S_COMPLETE - then client MUST act as described below. - - - - - -Kwan, et al. Standards Track [Page 10] - -RFC 3645 GSS-TSIG October 2003 - - - If the response from the server was signed, and the OUTPUT - major_status is GSS_S_COMPLETE,then the signature in the TSIG record - MUST be verified using the procedure detailed in section 5, Sending - and Verifying Signed Messages. If the signature is invalid, then 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 - looping the number of attempts to establish a security context MUST - be limited to ten or less. - - If major_status is GSS_S_CONTINUE_NEEDED the negotiation is not yet - finished. The token output_token MUST be passed to the server in a - TKEY record by repeating the negotiation sequence beginning with - section 3.1.2. The client MUST place a limit on the number of - continuations in a context negotiation to prevent endless looping. - Such limit SHOULD NOT exceed value of 10. - - 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 by repeating the - negotiation sequence beginning with section 3.1.2. - - If major_status is GSS_S_COMPLETE and output_token is NULL, context - negotiation is complete. 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 MUST - be used for the generation and verification of transaction - signatures. - - The procedures for sending and receiving signed messages are - described in section 5, Sending and Verifying Signed Messages. - -3.2.1. Terminating a Context - - When the client is not intended to continue using the established - security context, the client SHOULD delete an active context by - calling GSS_Delete_sec_context providing the associated - context_handle, AND client SHOULD delete the established context on - the DNS server by using TKEY RR with the Mode field set to 5, i.e., - "key deletion" [RFC2930]. - - - - - -Kwan, et al. Standards Track [Page 11] - -RFC 3645 GSS-TSIG October 2003 - - -4. Server Protocol Details - - As on the client-side, the result of a successful context negotiation - is a context handle used in future generation and verification of the - transaction signatures. - - 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 MUST recognize TKEY queries as security context negotiation - messages. - -4.1.1. Receive TKEY Query from Client - - Upon receiving a query with QTYPE = TKEY, the server MUST examine - whether the Mode and Algorithm Name fields of the TKEY record in the - additional records section of the message contain values of 3 and - gss-tsig, respectively. If they do, then the (key_name, - context_handle) mapping table is searched for the key_name matching - the owner name of the TKEY record in the additional records section - of the query. If the name is found in the table and the security - context for this name is established and not expired, then the server - MUST respond to the query with BADNAME error in the TKEY error field. - If the name is found in the table and the security context is not - established, the corresponding context_handle is used in subsequent - GSS operations. If the name is found but the security context is - expired, then the server deletes this security context, as described - in Section 4.2.1, and interprets this query as a start of new - security context negotiation and performs operations described in - Section 4.1.2 and 4.1.3. If the name is not found, then the server - interprets this query as a start of new security context negotiation - and performs operations described in Section 4.1.2 and 4.1.3. - -4.1.2. Call GSS_Accept_sec_context - - The server performs its side of a context negotiation by calling - GSS_Accept_sec_context. The following input parameters MUST be used. - The outcome of the call is indicated with the output values below. - Consult Sections 2.2.2 "GSS_Accept_sec_context call" of the RFC 2743 - [RFC2743] for syntax definitions. - - - - - - -Kwan, et al. Standards Track [Page 12] - -RFC 3645 GSS-TSIG October 2003 - - - INPUTS - CONTEXT HANDLE input_context_handle = 0 if new negotiation, - context_handle matching - key_name if ongoing negotiation - OCTET STRING input_token = token specified in the Key - field from TKEY RR (from Additional records Section of - the client's query) - - CREDENTIAL HANDLE acceptor_cred_handle = NULL (NULL specifies "use - default"). Server MAY instead specify some other valid - handle to its credentials. - 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 - INTEGER minor_status - INTERNAL NAME src_name - OBJECT IDENTIFIER mech_type - BOOLEAN deleg_state - BOOLEAN mutual_state - BOOLEAN replay_det_state - BOOLEAN sequence_state - BOOLEAN anon_state - BOOLEAN trans_state - BOOLEAN prot_ready_state - BOOLEAN conf_avail - BOOLEAN integ_avail - INTEGER lifetime_rec - CONTEXT_HANDLE delegated_cred_handle - - 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 - - The server MUST respond to the client with a TKEY query response with - RCODE = NOERROR, that contains a TKEY record in the answer section. - - If OUTPUT major_status is one of the following errors the error field - in the TKEY record set to BADKEY. - - - - - - -Kwan, et al. Standards Track [Page 13] - -RFC 3645 GSS-TSIG October 2003 - - - GSS_S_DEFECTIVE_TOKEN - GSS_S_DEFECTIVE_CREDENTIAL - GSS_S_BAD_SIG (GSS_S_BAD_MIC) - GSS_S_DUPLICATE_TOKEN - GSS_S_OLD_TOKEN - GSS_S_NO_CRED - GSS_S_CREDENTIALS_EXPIRED - GSS_S_BAD_BINDINGS - GSS_S_NO_CONTEXT - GSS_S_BAD_MECH - GSS_S_FAILURE - - If OUTPUT major_status is set to GSS_S_COMPLETE or - GSS_S_CONTINUE_NEEDED then server MUST act as described below. - - If major_status is GSS_S_COMPLETE the server component of the - negotiation is finished. If output_token is non-NULL, then it MUST - be returned to the client in a Key Data field of the RDATA in TKEY. - The error field in the TKEY record is set to NOERROR. The message - MUST be signed with a TSIG record as described in section 5, Sending - and Verifying Signed Messages. Note that 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 context state is advanced - to Context Established. Section 4.2 discusses the usage of the - security context. - - If major_status is GSS_S_COMPLETE and output_token is NULL, then the - TKEY record received from the client MUST be returned in the Answer - section of the response. The message MUST be signed with a TSIG - record as described in section 5, Sending and Verifying Signed - Messages. Note that 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 context state is advanced to Context - Established. Section 4.2 discusses the usage of the security - context. - - If major_status is GSS_S_CONTINUE_NEEDED, the server component of the - negotiation is not yet finished. The server responds to the TKEY - query with a standard query response, placing in the answer section a - TKEY record containing output_token in the Key Data RDATA field. The - error field in the TKEY record is set to NOERROR. The server MUST - limit the number of times that a given context is allowed to repeat, - to prevent endless looping. Such limit SHOULD NOT exceed value of - 10. - - - - - - - -Kwan, et al. Standards Track [Page 14] - -RFC 3645 GSS-TSIG October 2003 - - - In all cases, except if major_status is GSS_S_COMPLETE and - output_token is NULL, other TKEY record fields MUST contain the - following values: - - NAME = key_name - RDATA - Algorithm Name = gss-tsig - Mode = 3 (GSS-API negotiation - per [RFC2930]) - Key Size = size of output_token in octets - - The remaining fields in the TKEY RDATA, i.e., Inception, Expiration, - Error, Other Size and Data Fields, MUST be set according to - [RFC2930]. - -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 (see section 4.2.1). - - Server SHOULD limit the amount of memory used to cache established - contexts. - - 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 5, i.e., - "key deletion" [RFC2930]. An active context is deleted by calling - GSS_Delete_sec_context providing the associated context_handle. - -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 [RFC2845]. The data to be passed to the signature routine - includes the whole DNS message with specific TSIG variables appended. - For the exact format, see [RFC2845]. For this protocol, use the - following TSIG variable values: - - - - - - -Kwan, et al. Standards Track [Page 15] - -RFC 3645 GSS-TSIG October 2003 - - - TSIG Record - NAME = key_name that identifies this context - RDATA - Algorithm Name = gss-tsig - - Assign the remaining fields in the TSIG RDATA appropriate values as - described in [RFC2845]. - - The signature is generated by calling GSS_GetMIC. The following - input parameters MUST be used. The outcome of the call is indicated - with the output values specified below. Consult Sections 2.3.1 - "GSS_GetMIC call" of the RFC 2743[RFC2743] for syntax definitions. - - INPUTS - CONTEXT HANDLE context_handle = context_handle for key_name - OCTET STRING message = outgoing message plus TSIG - variables (per [RFC2845]) - INTEGER qop_req = 0 (0 requests a default - value). Caller MAY instead specify other valid value (for - details see Section 1.2.4 in [RFC2743]) - - OUTPUTS - INTEGER major_status - INTEGER minor_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, GSS_S_CREDENTIALS_EXPIRED - or GSS_S_FAILURE the caller MUST delete the security context, return - to the uninitialized state and SHOULD negotiate a new security - context, as described above in Section 3.1 - - If major_status is GSS_S_NO_CONTEXT, the caller MUST remove the entry - for key_name from the (target_ name, key_name, context_handle) - mapping table, return to the uninitialized state and SHOULD negotiate - a new security context, as described above in Section 3.1 - - If major_status is GSS_S_BAD_QOP, the caller SHOULD repeat the - GSS_GetMIC call with allowed QOP value. The number of such - repetitions MUST be limited to prevent infinite loops. - -5.2. Verifying a Signed Message - Call GSS_VerifyMIC - - The procedure for verifying a signature-protected message is - specified in [RFC2845]. - - - -Kwan, et al. Standards Track [Page 16] - -RFC 3645 GSS-TSIG October 2003 - - - The NAME of the TSIG record determines which context_handle maps to - the context that MUST be used to verify the signature. If the NAME - does not map to an established context, the server MUST send a - standard TSIG error response to the client indicating BADKEY in the - TSIG error field (as described in [RFC2845]). - - 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 (per [RFC2845]) - OCTET STRING per_msg_token = Signature field from TSIG RR - - OUTPUTS - INTEGER major_status - INTEGER minor_status - INTEGER qop_state - - If major_status is GSS_S_COMPLETE, the signature is authentic and the - message was delivered intact. Per [RFC2845], the timer values of the - TSIG record MUST also be valid before considering the message to be - authentic. The caller MUST not act on the request or response in the - message until these checks are verified. - - 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 as described in [RFC2845], if major_status is set to - one of the following values - - GSS_S_DEFECTIVE_TOKEN - GSS_S_BAD_SIG (GSS_S_BAD_MIC) - GSS_S_DUPLICATE_TOKEN - GSS_S_OLD_TOKEN - GSS_S_UNSEQ_TOKEN - GSS_S_GAP_TOKEN - GSS_S_CONTEXT_EXPIRED - GSS_S_NO_CONTEXT - GSS_S_FAILURE - - 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 according to [RFC2845]. - - - - - - -Kwan, et al. Standards Track [Page 17] - -RFC 3645 GSS-TSIG October 2003 - - -6. Example usage of GSS-TSIG algorithm - - This Section describes an example where a Client, client.example.com, - and a Server, server.example.com, establish a security context - according to the algorithm described above. - - I. Client initializes security context negotiation - - To establish a security context with a server, server.example.com, the - Client calls GSS_Init_sec_context with the following parameters. - (Note that some INPUT and OUTPUT parameters not critical for this - algorithm are not described in this example.) - - CONTEXT HANDLE input_context_handle = 0 - INTERNAL NAME targ_name = "DNS@server.example.com" - OCTET STRING input_token = NULL - BOOLEAN replay_det_req_flag = TRUE - BOOLEAN mutual_req_flag = TRUE - - The OUTPUTS parameters returned by GSS_Init_sec_context include - INTEGER major_status = GSS_S_CONTINUE_NEEDED - CONTEXT HANDLE output_context_handle context_handle - OCTET STRING output_token output_token - BOOLEAN replay_det_state = TRUE - BOOLEAN mutual_state = TRUE - - Client verifies that replay_det_state and mutual_state values are - TRUE. Since the major_status is GSS_S_CONTINUE_NEEDED, which is a - success OUTPUT major_status value, client stores context_handle that - maps to "DNS@server.example.com" and proceeds to the next step. - - II. Client sends a query with QTYPE = TKEY to server - - Client sends a query with QTYPE = TKEY for a client-generated globally - unique domain name string, 789.client.example.com.server.example.com. - Query contains a TKEY record in its Additional records section with - the following fields. (Note that some fields not specific to this - algorithm are not specified.) - - NAME = 789.client.example.com.server.example.com. - RDATA - Algorithm Name = gss-tsig - Mode = 3 (GSS-API negotiation - per [RFC2930]) - Key Size = size of output_token in octets - Key Data = output_token - - - - - - -Kwan, et al. Standards Track [Page 18] - -RFC 3645 GSS-TSIG October 2003 - - - After the key_name 789.client.example.com.server.example.com. - is generated it is stored in the client's (target_name, key_name, - context_handle) mapping table. - - III. Server receives a query with QTYPE = TKEY - - When server receives a query with QTYPE = TKEY, the server verifies - that Mode and Algorithm fields in the TKEY record in the Additional - records section of the query are set to 3 and "gss-tsig" respectively. - It finds that the key_name 789.client.example.com.server.example.com. - is not listed in its (key_name, context_handle) mapping table. - - IV. Server calls GSS_Accept_sec_context - - To continue security context negotiation server calls - GSS_Accept_sec_context with the following parameters. (Note that - some INPUT and OUTPUT parameters not critical for this algorithm - are not described in this example.) - - INPUTS - CONTEXT HANDLE input_context_handle = 0 - OCTET STRING input_token = token specified in the Key - field from TKEY RR (from Additional - records section of the client's query) - - The OUTPUTS parameters returned by GSS_Accept_sec_context include - INTEGER major_status = GSS_S_CONTINUE_NEEDED - CONTEXT_HANDLE output_context_handle context_handle - OCTET STRING output_token output_token - - Server stores the mapping of the - 789.client.example.com.server.example.com. to OUTPUT context_handle - in its (key_name, context_handle) mapping table. - - V. Server responds to the TKEY query - - Since the major_status = GSS_S_CONTINUE_NEEDED in the last server's - call to GSS_Accept_sec_context, the server responds to the TKEY query - placing in the answer section a TKEY record containing output_token in - the Key Data RDATA field. The error field in the TKEY record is set - to 0. The RCODE in the query response is set to NOERROR. - - VI. Client processes token returned by server - - When the client receives the TKEY query response from the server, the - client calls GSS_Init_sec_context with the following parameters. - (Note that some INPUT and OUTPUT parameters not critical for this - algorithm are not described in this example.) - - - -Kwan, et al. Standards Track [Page 19] - -RFC 3645 GSS-TSIG October 2003 - - - CONTEXT HANDLE input_context_handle = the context_handle stored - in the client's mapping table entry (DNS@server.example.com., - 789.client.example.com.server.example.com., context_handle) - INTERNAL NAME targ_name = "DNS@server.example.com" - OCTET STRING input_token = token from Key field of TKEY - record from the Answer section of the server's response - BOOLEAN replay_det_req_flag = TRUE - BOOLEAN mutual_req_flag = TRUE - - The OUTPUTS parameters returned by GSS_Init_sec_context include - INTEGER major_status = GSS_S_COMPLETE - CONTEXT HANDLE output_context_handle = context_handle - OCTET STRING output_token = output_token - BOOLEAN replay_det_state = TRUE - BOOLEAN mutual_state = TRUE - - Since the major_status is set to GSS_S_COMPLETE the client side - security context is established, but since the output_token is not - NULL client MUST send a TKEY query to the server as described below. - - VII. Client sends a query with QTYPE = TKEY to server - - Client sends to the server a TKEY query for the - 789.client.example.com.server.example.com. name. Query contains a - TKEY record in its Additional records section with the following - fields. (Note that some INPUT and OUTPUT parameters not critical to - this algorithm are not described in this example.) - - NAME = 789.client.example.com.server.example.com. - RDATA - Algorithm Name = gss-tsig - Mode = 3 (GSS-API negotiation - per [RFC2930]) - Key Size = size of output_token in octets - Key Data = output_token - - VIII. Server receives a TKEY query - - When the server receives a TKEY query, the server verifies that Mode - and Algorithm fields in the TKEY record in the Additional records - section of the query are set to 3 and gss-tsig, respectively. It - finds that the key_name 789.client.example.com.server.example.com. is - listed in its (key_name, context_handle) mapping table. - - - - - - - - - -Kwan, et al. Standards Track [Page 20] - -RFC 3645 GSS-TSIG October 2003 - - - IX. Server calls GSS_Accept_sec_context - - To continue security context negotiation server calls - GSS_Accept_sec_context with the following parameters (Note that some - INPUT and OUTPUT parameters not critical for this algorithm are not - described in this example) - - INPUTS - CONTEXT HANDLE input_context_handle = context_handle from the - (789.client.example.com.server.example.com., context_handle) - entry in the server's mapping table - OCTET STRING input_token = token specified in the Key - field of TKEY RR (from Additional records Section of - the client's query) - - The OUTPUTS parameters returned by GSS_Accept_sec_context include - INTEGER major_status = GSS_S_COMPLETE - CONTEXT_HANDLE output_context_handle = context_handle - OCTET STRING output_token = NULL - - Since major_status = GSS_S_COMPLETE, the security context on the - server side is established, but the server still needs to respond to - the client's TKEY query, as described below. The security context - state is advanced to Context Established. - - X. Server responds to the TKEY query - - Since the major_status = GSS_S_COMPLETE in the last server's call to - GSS_Accept_sec_context and the output_token is NULL, the server - responds to the TKEY query placing in the answer section a TKEY record - that was sent by the client in the Additional records section of the - client's latest TKEY query. In addition, this server places a - TSIG record in additional records section of its response. Server - calls GSS_GetMIC to generate a signature to include it in the TSIG - record. The server specifies the following GSS_GetMIC INPUT - parameters: - - CONTEXT HANDLE context_handle = context_handle from the - (789.client.example.com.server.example.com., context_handle) - entry in the server's mapping table - OCTET STRING message = outgoing message plus TSIG - variables (as described in [RFC2845]) - - The OUTPUTS parameters returned by GSS_GetMIC include - INTEGER major_status = GSS_S_COMPLETE - OCTET STRING per_msg_token - - Signature field in the TSIG record is set to per_msg_token. - - - -Kwan, et al. Standards Track [Page 21] - -RFC 3645 GSS-TSIG October 2003 - - - XI. Client processes token returned by server - - Client receives the TKEY query response from the server. Since the - major_status was GSS_S_COMPLETE in the last client's call to - GSS_Init_sec_context, the client verifies that the server's response - is signed. To validate the signature, the client calls - GSS_VerifyMIC with the following parameters: - - INPUTS - CONTEXT HANDLE context_handle = context_handle for - 789.client.example.com.server.example.com. key_name - OCTET STRING message = incoming message plus TSIG - variables (as described in [RFC2845]) - OCTET STRING per_msg_token = Signature field from TSIG RR - included in the server's query response - - Since the OUTPUTS parameter major_status = GSS_S_COMPLETE, the - signature is validated, security negotiation is complete and the - security context state is advanced to Context Established. These - client and server will use the established security context to sign - and validate the signatures when they exchange packets with each - other until the context expires. - -7. 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. - - All the security considerations from RFC 2845, RFC 2930 and RFC 2743 - apply to the protocol described in this document. - -8. IANA Considerations - - The IANA has reserved the TSIG Algorithm name gss-tsig for the use in - the Algorithm fields of TKEY and TSIG resource records. This - Algorithm name refers to the algorithm described in this document. - The requirement to have this name registered with IANA is specified - in RFC 2845. - -9. Conformance - - The GSS API using SPNEGO [RFC2478] provides maximum flexibility to - choose the underlying security mechanisms that enables security - context negotiation. GSS API using SPNEGO [RFC2478] enables client - and server to negotiate and choose such underlying security - mechanisms on the fly. To support such flexibility, DNS clients and - servers SHOULD specify SPNEGO mech_type in their GSS API calls. At - - - -Kwan, et al. Standards Track [Page 22] - -RFC 3645 GSS-TSIG October 2003 - - - the same time, in order to guarantee interoperability between DNS - clients and servers that support GSS-TSIG it is required that - - - DNS servers specify SPNEGO mech_type - - GSS APIs called by DNS client support Kerberos v5 - - GSS APIs called by DNS server support SPNEGO [RFC2478] and - Kerberos v5. - - In addition to these, GSS APIs used by DNS client and server MAY also - support other underlying security mechanisms. - -10. Intellectual Property Statement - - The IETF takes no position regarding the validity or scope of any - intellectual property or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; neither does it represent that it - has made any effort to identify any such rights. Information on the - IETF's procedures with respect to rights in standards-track and - standards-related documentation can be found in BCP-11. Copies of - claims of rights made available for publication and any assurances of - licenses to be made available, or the result of an attempt made to - obtain a general license or permission for the use of such - proprietary rights by implementors or users of this specification can - be obtained from the IETF Secretariat. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights which may cover technology that may be required to practice - this standard. Please address the information to the IETF Executive - Director. - -11. 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, Olafur Gudmundsson, Donald E. Eastlake, 3rd - and Erik Nordmark. - - - - - - - - - - - - -Kwan, et al. Standards Track [Page 23] - -RFC 3645 GSS-TSIG October 2003 - - -12. References - -12.1. Normative References - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC2478] Baize, E. and D. Pinkas, "The Simple and Protected GSS-API - Negotiation Mechanism", RFC 2478, December 1998. - - [RFC2743] Linn, J., "Generic Security Service Application Program - Interface, Version 2 , Update 1", RFC 2743, January 2000. - - [RFC2845] Vixie, P., Gudmundsson, O., Eastlake 3rd, D. and B. - Wellington, "Secret Key Transaction Authentication for DNS - (TSIG)", RFC 2845, May 2000. - - [RFC2930] Eastlake 3rd, D., "Secret Key Establishment for DNS (TKEY - RR)", RFC 2930, September 2000. - -12.2. Informative References - - - [ISO11578] "Information technology", "Open Systems Interconnection", - "Remote Procedure Call", ISO/IEC 11578:1996, - http://www.iso.ch/cate/d2229.html. - - [RFC1034] Mockapetris, P., "Domain Names - Concepts and Facilities", - STD 13, RFC 1034, November 1987. - - [RFC1035] Mockapetris, P., "Domain Names - Implementation and - Specification", STD 13, RFC 1034, November 1987. - - [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC - 1964, June 1996. - - [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism - (SPKM)", RFC 2025, October 1996. - - [RFC2137] Eastlake 3rd, D., "Secure Domain Name System Dynamic - Update", RFC 2137, April 1997. - - [RFC2535] Eastlake 3rd, D., "Domain Name System Security Extensions", - RFC 2535, March 1999. - - - - - - - -Kwan, et al. Standards Track [Page 24] - -RFC 3645 GSS-TSIG October 2003 - - -13. Authors' Addresses - - Stuart Kwan - Microsoft Corporation - One Microsoft Way - Redmond, WA 98052 - USA - EMail: skwan@microsoft.com - - Praerit Garg - Microsoft Corporation - One Microsoft Way - Redmond, WA 98052 - USA - EMail: praeritg@microsoft.com - - James Gilroy - Microsoft Corporation - One Microsoft Way - Redmond, WA 98052 - USA - EMail: jamesg@microsoft.com - - Levon Esibov - Microsoft Corporation - One Microsoft Way - Redmond, WA 98052 - USA - EMail: levone@microsoft.com - - Randy Hall - Lucent Technologies - 400 Lapp Road - Malvern PA 19355 - USA - EMail: randyhall@lucent.com - - Jeff Westhead - Microsoft Corporation - One Microsoft Way - Redmond, WA 98052 - USA - EMail: jwesth@microsoft.com - - - - - - - - -Kwan, et al. Standards Track [Page 25] - -RFC 3645 GSS-TSIG October 2003 - - -14. Full Copyright Statement - - Copyright (C) The Internet Society (2003). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assignees. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Kwan, et al. Standards Track [Page 26] - |
