draft-ietf-dnsext-gss-tsig-06.txt

bind-3.2.

                                            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

Expires August 28, 2003                                       [Page 11]

INTERNET-DRAFT                   GSS-TSIG             February 28, 2003


     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.



Expires August 28, 2003                                       [Page 12]

INTERNET-DRAFT                   GSS-TSIG             February 28, 2003

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, 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.

Expires August 28, 2003                                       [Page 13]

INTERNET-DRAFT                   GSS-TSIG             February 28, 2003

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.

Expires August 28, 2003                                       [Page 14]

INTERNET-DRAFT                   GSS-TSIG             February 28, 2003


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






Expires August 28, 2003                                       [Page 15]

INTERNET-DRAFT                   GSS-TSIG             February 28, 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             = "[e-mail]"
     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 "[e-mail]" 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.