One document matched: draft-kaduk-kitten-gss-loop-00.xml

<?xml version="1.0"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2743 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2743.xml">
<!ENTITY RFC2744 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2744.xml">
<!ENTITY RFC5801 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5801.xml">
<!ENTITY RFC3645 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3645.xml">
<!ENTITY RFC2203 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2203.xml">
<!ENTITY RFC4462 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4462.xml">
<!ENTITY RFC4752 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4752.xml">
<!ENTITY RFC4401 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4401.xml">
]>
<rfc category="std" ipr="trust200902" docName="draft-kaduk-kitten-gss-loop-00" submissionType="IETF">
  <front>
    <title>Structure of the GSS Negotiation Loop</title>
    <author initials="B." surname="Kaduk" fullname="Benjamin Kaduk">
      <organization abbrev="MIT">MIT Kerberos Consortium</organization>
      <address>
        <email>kaduk@mit.edu</email>
      </address>
    </author>
    <date month="October" year="2013"/>
    <abstract>
      <t>This document specifies the generic structure of the negotiation
	loop to establish a GSS security context between initiator and
	acceptor.  The control flow of the loop is indicated for both
	parties, including error conditions, and indications are given for
	where application-specific behavior must be specified.
      </t>
    </abstract>
  </front>
  <middle>
    <section anchor="intro" title="Introduction">
      <t>The Generic Security Service Application Program Intervace
	version 2 <xref target="RFC2743" /> provides a generic interface
	for security services, in the form of an abstraction layer over
	the underlying security mechanisms that an application may use.
	A GSS initiator and acceptor exchange messages, called tokens,
	until a security context is established.  Such a security context
	allows for mutual authentication of the two parties, the passing of
	confidential or integrity-protected messages
	between the initiator and acceptor, the generation of identical
	pseudo-random bit strings by both
	participants <xref target="RFC4401" />, and more.  The number of
	tokens which must be exchanged between initiator and acceptor in
	order to establish the security context is dependent on the
	underlying mechanism as well as the desired properties of the
	security context, and is in general not known to the application.
	Accordingly, the application's control flow must include a loop
	within which GSS security context tokens are exchanged, which
	terminates upon successful establishment of a security context
	(or an error condition).
      </t>
      <t>The GSS-API C bindings <xref target="RFC2744" /> provide some
	example code for such a negotiation loop, but this code does not
	specify the application's behavior on unexpected or error conditions.
	As such, individual application protocol specifications have
	had to specify the structure of their GSS negotiation loops,
	including error handling, on a per-protocol basis.
	<xref target="RFC4462" />, <xref target="RFC3645" />,
	<xref target="RFC5801" />, <xref target="RFC4752" />,
	<xref target="RFC2203" />
	This represents a substantial duplication of effort, and the
	various specifications go into different levels of detail and
	describe different possible error conditions.  It is therefore
	preferable to have the structure of the GSS negotiation loop,
	including error conditions and token passing, described in a single
	specification, which can then be referred to from other documents
	in lieu of repeating the structure of the loop each time.
	This document will perform that role.
      </t>
      <section title="Requirements Language">
	<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	  "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
	  document are to be interpreted as described in
	  <xref target="RFC2119" />.
	</t>
      </section>
    </section>
    <section anchor="loop" title="Loop Structure">
      <t>The loop is begun by the appropriately named initiator,
	which calls GSS_Init_sec_context() with an empty (zero-length)
	input_token and a fixed set of input flags containing the
	desired attributes for the security context.
	The initiator MUST NOT change any of the
	input parameters to GSS_Init_sec_context() between calls
	to it during the loop, with the exception of the input_token
	parameter, which will contain a message from the acceptor
	after the initial call, and the input_context_handle, which
	MUST be the result returned in the output_context_handle of
	the previous call to GSS_Init_sec_context() (or GSS_C_NO_CONTEXT
	for the first call).
      </t>
      <t>The following subsections will describe the various steps of
	the loop, without special consideration to whether a call
	to GSS_Init_sec_context() or GSS_Accept_sec_context() is the
	first such call in the loop.  For the first call to each
	routine in the loop, the major status code from the previous
	call to GSS_Init_sec_context() or GSS_Accept_sec_context() should
	be taken as GSS_S_CONTINUE_NEEDED.
      </t>
      <section anchor="anon" title="Anonymous Initiators">
	<t>If the initiator is requesting anonymity by setting the
	  anon_req_flag input to GSS_Init_sec_context(), then on
	  non-error returns from GSS_Init_sec_context() (that is,
	  the major status is GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED),
	  the initiator MUST verify that the output value of anon_state
	  from GSS_Init_sec_context() is true before sending the
	  security context token to the acceptor.  Failing to perform
	  this check could cause the initiator to lose anonymity.
	</t>
      </section>
      <section anchor="initiator" title="GSS_Init_sec_context">
	<t>The initiator calls GSS_Init_sec_context(), using the
	  input_context_handle for the current proto-security-context
	  and its fixed set of input parameters, and the input_token
	  received from the acceptor (if not the first iteration of
	  the loop).  The presence of a nonempty output_token and the
	  value of the major status code are the indicators for how to
	  proceed:
	  <list style="hanging">
	    <t>If the major status code is GSS_S_COMPLETE and the
	      output_token is empty, then the context negotiation is
	      fully complete and ready for use by the initiator with no
	      further actions.</t>
	    <t>If the major status code is GSS_S_COMPLETE and the
	      output_token is nonempty, then the initiator's portion
	      of the security context negotiation is complete but the
	      acceptor's is not.  The initiator MUST send the output_token
	      to the acceptor so that the acceptor can establish its half
	      of the security context.</t>
	    <t>If the major status code is GSS_S_CONTINUE_NEEDED and the
	      output_token is nonempty, the context negotiation is
	      incomplete.  The initiator MUST send the output_token
	      to the acceptor and await another input_token from the
	      acceptor.</t>
	    <t>If the major status code is GSS_S_CONTINUE_NEEDED and the
	      output_token is empty, the mechanism has produced an
	      inconsistent output and the security context negotiation
	      has failed.  The initiator SHOULD indicate the failure to
	      the acceptor if an appropriate channel to do so is
	      available.</t>
	    <t>If the major status code is any other value, the context
	      negotiation has failed.  If the output_token is nonempty,
	      it is an error token, and the initiator SHOULD send it to
	      the acceptor.  If the output_token is empty, then the
	      initiator SHOULD indicate the failure to the acceptor if an
	      appropriate channel to do so is available.
	    </t>
	  </list>
	</t>
      </section>
      <section anchor="itoa" title="Sending from Initiator to Acceptor">
	<t>The establishment of a GSS security context between initiator
	  and acceptor requires some communication channel by which to
	  exchange the context negotiation tokens.  The nature of this
	  channel is not specified by the GSS specification -- it could
	  be a synchronous TCP channel, a UDP-based RPC protocol, or
	  any other sort of channel.  In many cases, the channel will
	  be multiplexed with non-GSS application data; the application
	  protocol must provide some means by which the GSS context tokens
	  can be identified and passed through to the mechanism accordingly.
	  It is in such cases where the application protocol has a means
	  to indicate error conditions that the initiator could indicate
	  a failure to the acceptor, as mentioned in some of the above
	  cases conditional on "an appropriate channel to do so".</t>
	<t>However, even the presence of a communication channel does not
	  necessarily indicate that it is appropriate for the initiator
	  to indicate such errors.  For example, if the acceptor is
	  a stateless or near-stateless UDP server, there is probably
	  no need for the initiator to explicitly indicate its failure
	  to the acceptor.  Conditions such as this can be treated in
	  individual application protocol specifications.</t>
	<t>If a regular security context output_token is produced by the
	  call to GSS_Init_sec_context(), the initiator MUST transmit
	  this token to the acceptor over the application's communication
	  channel.  If the call to GSS_Init_sec_context() returns an
	  error token as output_token, it is RECOMMENDED that the intiator
	  transmit this token to the acceptor over the application's
	  communication channel.
	</t>
      </section>
      <section anchor="asan" title="Acceptor Sanity Checking">
	<t>The acceptor's half of the negotiation loop is triggered
	  by the receipt of a context token from the initiator.
	  Before calling GSS_Accept_sec_context(), the acceptor
	  may find it useful to perform some sanity checks on the
	  state of the negotiation loop.</t>
	<t>If the acceptor receives a context token but was not expecting
	  such a token (for example, if the acceptor's previous call to
	  GSS_Accept_sec_context() returned GSS_S_COMPLETE), this is
	  an error condition indicating that the initiator's state is invalid.
	  It is likely appropriate for the acceptor to report this error
	  condition to the acceptor via the application's communication
	  channel.</t>
	<t>If the acceptor is expecting a context token (e.g., if the
	  previous call to GSS_Accept_sec_context() returned
	  GSS_S_CONTINUE_NEEDED), but does not receive such a token within
	  a reasonable amount of time after transmitting the previous
	  output_token to the initiator, the acceptor should assume that
	  the initiator's state is invalid and fail the GSS negotiation.
	  Again, it is likely appropriate for the acceptor to report
	  this error condition to the initiator via the application's
	  communication channel.</t>
	<t>[Are there other checks to perform here?]
	</t>
      </section>
      <section anchor="accept" title="GSS_Accept_sec_context">
	<t>The GSS acceptor responds to the actions of an initiator;
	  as such, there should always be a nonempty input_token
	  to calls to GSS_Accept_sec_context().  The input_context_handle
	  parameter will always be given as the output_context_handle
	  from the previous call to GSS_Accept_sec_context() in a
	  given negotiation loop (or GSS_C_NO_CONTEXT on the first
	  call), but the acceptor_cred_handle and chan_bindings arguments
	  MUST remain fixed over the course of a given GSS negotiation
	  loop.</t>
	<t>The GSS acceptor calls GSS_Accept_sec_context(), using the
	  input_context_handle for the current proto-security-context
	  and the input_token received from the initiator.
	  The presence of a nonempty output_token and the value of the
	  major status code are the indicators for how to proceed:
	  <list style="hanging">
	    <t>If the major status code is GSS_S_COMPLETE and the
	      output_token is empty, then the context negotiation is
	      fully complete and ready for use by the acceptor with no
	      further actions.</t>
	    <t>If the major status code is GSS_S_COMPLETE and the
	      output_token is nonempty, then the acceptor's portion
	      of the security context negotiation is complete but the
	      initiator's is not.  The acceptor MUST send the output_token
	      to the initiator so that the initiator can establish its half
	      of the security context.</t>
	    <t>If the major status code is GSS_S_CONTINUE_NEEDED and the
	      output_token is nonempty, the context negotiation is
	      incomplete.  The acceptor MUST send the output_token
	      to the initiator and await another input_token from the
	      initiator.</t>
	    <t>If the major status code is GSS_S_CONTINUE_NEEDED and the
	      output_token is empty, the mechanism has produced an
	      inconsistent output and the security context negotiation
	      has failed.  The acceptor SHOULD indicate the failure to
	      the initiator if an appropriate channel to do so is
	      available.</t>
	    <t>If the major status code is any other value, the context
	      negotiation has failed.  If the output_token is nonempty,
	      it is an error token, and the acceptor SHOULD send it to
	      the initiator.  If the output_token is empty, then the
	      acceptor SHOULD indicate the failure to the initiator if an
	      appropriate channel to do so is available.
	    </t>
	  </list>
	</t>
      </section>
      <section anchor="atoi" title="Sending from Acceptor to Initiator">
	<t>The mechanism for sending the context token from acceptor to
	  initiator will depend on the nature of the communication channel
	  between the two parties.  For a synchronous bidirectional channel,
	  it can be just another piece of data sent over the link, but for
	  a stateless UDP RPC acceptor, the token will probably end up
	  being sent as an RPC output parameter.  Application protocol
	  specifications will need to specify the nature of this behavior.</t>
        <t>If the application protocol has the initiator driving the
	  application's control flow (with the acceptor just responding to
	  actions from the initiator), it is particularly helpful for
	  the acceptor to indicate a failure to the initiator, as mentioned
	  in some of the above cases conditional on "an appropriate channel
	  to do so".</t>
	<t>If a regular security context output_token is produced by the
	  call to GSS_Accept_sec_context(), the acceptor MUST transmit
	  this token to the initiator over the application's communication
	  channel.  If the call to GSS_Accept_sec_context() returns an
	  error token as output_token, it is RECOMMENDED that the acceptor
	  transmit this token to the initiator over the application's
	  communication channel.
	</t>
      </section>
      <section anchor="isan" title="Initiator input validation">
	<t>The initiator's half of the negotiation loop is triggered
	  (after the first call) by receipt of a context token from the
	  acceptor.  Before calling GSS_Init_sec_context(), the initiator
	  may find it useful to perform some sanity checks on the state
	  of the negotiation loop.</t>
	<t>If the initiator receives a context token but was not expecting
	  such a token (for example, if the initiator's previous call to
	  GSS_Init_sec_context() returned GSS_S_COMPLETE), this is an
	  error condition indicating that the acceptor's state is invalid.
	  It may be appropriate for the initiator to report this error
	  condition to the acceptor via the application's communication
	  channel.</t>
	<t>If the initiator is expecting a context token (that is, the
	  previous call to GSS_Init_sec_context() returned
	  GSS_S_CONTINUE_NEEDED), but does not receive such a token within
	  a reasonable amount of time after transmitting the previous
	  output_token to the acceptor, the initiator should assume that
	  the acceptor's state is invalid and fail the GSS negotiation.
	  Again, it may be appropriate for the initiator to report this
	  error condition to the acceptor via the application's communication
	  channel.</t>
	<t>[Are there other checks to perform here?]
	</t>
      </section>
      <section title="Continue the Loop">
	<t>If the loop is in neither a success or failure condition, then
	  the loop must continue.  Control flow returns to
	  <xref target="initiator" />.
	</t>
      </section>
    </section>
    <section anchor="post" title="After Security Context Negotiation">
      <t>Once a party has completed its half of the security context
	and fulfilled its obligations to the other party, the context
	is complete, but it is not necessarily ready and appropriate
	for use.  (In some cases the context may be ready for use
	earlier than this, see <xref target="partial" />.)
        In particular, the security context
	flags may not be appropriate for the given application's use.</t>
      <t>The initiator specifies as part of its fixed set of inputs
	to GSS_Init_sec_context() values for the following booleans:
	deleg_req_flag, mutual_req_flag, replay_det_req_flag,
	sequence_req_flag, conf_req_flag, and integ_req_flag.  Upon
	completion of security context negotiation, the initiator MUST
	verify the values of the deleg_state, mutual_state, replay_det_state,
	sequence_state, conf_avail, and integ_avail flags
	from the last call to GSS_Init_sec_context()
	corresponding to the requested flags.  If a flag was requested
	but is not available, and that feature is necessary for the
	appplication protocol, the initiator MUST destroy the security
	context and not use the security context for application traffic.</t>
      <t>Application protocol specifications citing this document
	MUST indicate which context flags are required for the application
	protocol.</t>
      <t>The acceptor receives as output the following booleans:
	deleg_state, mutual_state, replay_det_state, sequence_state,
	anon_state, trans_state, conf_avail, and integ_avail.
	The acceptor MUST verify that any flags necessary for the application
	protocol are set.  If a necessary flag is not set, the acceptor
	MUST destroy the security context and not use the security context
	for application traffic.
      </t>
      <section anchor="partial"
	       title="Using Partially Complete Security Contexts">
	<t>For mechanism/flag combinations that require multiple token
	  exchanges, an application protocol may find it desirable to
	  begin sending application data protected with GSS per-message
	  operations while continuing to exchange security context tokens
	  to complete the security context negotiation.  The
	  prot_ready_state output value from GSS_Init_sec_context() and
	  GSS_Accept_sec_context() indicates when per-message operations
	  are avaialble.</t>
	<t>Applications requiring confidentiality and/or integrity
	  protection from such messages MUST check the value of the
	  conf_avail and/or integ_avail output flags from
	  GSS_Init_sec_context()/GSS_Accept_sec_context() as well as the
	  conf_state output of GSS_Wrap() (if GSS_Wrap() is used).
	</t>
      </section>
    </section>
  </middle>
  <back>
    <references title="Normative References">
      &RFC2119;
      &RFC2743;
      &RFC2744;
      &RFC4401;
    </references>
    <references title="Informational References">
      &RFC4462;
      &RFC3645;
      &RFC5801;
      &RFC4752;
      &RFC2203;
    </references>
    <section title="Acknowledgements">
      <t>Acknowledgements.</t>
    </section>
  </back>
</rfc>