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.
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].
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.
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.
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.
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:
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].
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].
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
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.)
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.
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.
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])