C-Bindings alignment with rfc2078bis

[Martin Rex <martin.rex at sap-ag.de>]

Since we're in WG last call, I have been reading the C-Bindings
draft again to make sure that we get it properly aligned with
the high level document rfc2078bis so that both documents may
advance together in a consistent fashion.

Here's my list of pending alignments of the C-Bindings with rfc2078bis:


(1) support of certain explicit names to acquire credentials in
      7.2. gss_acquire_cred
      7.3. gss_add_cred

   quoting rfc2078bis, 2.1.1:  GSS_Acquire_cred call, excerpt 2nd paragraph:

          ...     Some implementations may therefore not support the
      acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via
      GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name
      resulting from applying GSS_Inquire_context() to an active context,
      or a name resulting from applying GSS_Inquire_cred() against a
      credential handle corresponding to default behavior. It is important
      to recognize that the explicit name which is yielded by resolving a
      default reference may change over time, e.g., as a result of local
      credential element management operations outside GSS-API; once
      resolved, however, the value of such an explicit name will remain
      constant.


(2) Section 7.20. gss_inquire_context
    Remove fatal rountine error GSS_S_CONTEXT_EXPIRED


(3) Section 7.10. gss_display_name
    adopt the exemption case from rfc2078bis-04 in
    which the nametype oid returned from gss_display_name() may be
    GSS_C_NO_OID (mechanisms with lazy name evaluation).


(4) Section 7.16. gss_import_name
    add the new major_status code GSS_S_BAD_MECH when importing exported
    names with an unrecognized mechanism oid in the generic framing.


(5) ability to request context attributes integ_req_flag and conf_req_flag
    in 7.19. gss_init_sec_context() to accomodate recent change to
    rfc2078bis, resulting from spnego discussions&requirements. 


(6) GSS_C_NT_HOSTBASED_SERVICE oid in gssapi.h sample header file

    Alignment with rfc2078bis:  tag this OID from the iana arc
    as "new, but deprecated" and put in GSS_KRB5_NT_HOSTBASED_SERVICE_NAME
    from MITs arc (rfc1964, section 2.1.2.) as the old and preferred
    OID for this purpose, we don't want to break the installed base of
    Kerberos5 gssapi mechanisms and others that already use MITs OID.

    Actually: rfc1964 indicates that GSS_C_NT_HOSTBASED_SERVICE refers
    to the same OID as GSS_KRB5_NT_HOSTBASED_SERVICE_NAME -- which
    (unfortunately) is no longer true since the assignment of the
    IANA-based oid...  

    Adding a comment into the sample header file with a pointer to the
    gssapi high level spec section 4 may also be helpful.
 

(7) GSS_C_NT_EXPORTED_NAME oid in gssapi.h sample header file

    I would suggest adding a comment to the sample header file
    which points to section 3.2 of the gssapi high level document.


(8) indicate in 5.9.1 GSS status codes (table 5.3) that the use of
    GSS_S_CONTINUE_NEEDED is restricted to the security context
    establishment calls.

    We had a discussion on the mailing list (18-21 july 1997) when it
    was discovered that MIT Kerberos returned GSS_S_CONTINUE_NEEDED
    from gss_display_status.  This was considered inappropriate and
    Theodore Ts'o proposed to add a clarifying statement into the spec.

    rfc2078bis discusses the use of GSS_S_CONTINUE_NEEDED in 1.2.1.1
    in connection with only the security context establishment calls.
    

(9) inappropriate usage restriction of 7.25. process_context_token

    The C-Bindings description of process_context_token says that
    it only applies to tokens emitted from gss_delete_sec_context,
    whereas rfc2078bis doesn't make this claim.  From the list discussion
    that I remember, some mechanism implementors want to be able to
    transfer a token with an error message back from the acceptor
    to the initiator when security context establishment fails.
    For authentications with an odd number of message exchanges,
    the final token will be sent from initiator to acceptor.
    But if the final gss_accept_sec_context fails, a resulting
    context-level (error) token could only be processed by the
    initiator calling gss_process_context_token() -- since his
    gss_init_sec_context() had already returned GSS_S_COMPLETE
    and is not expected to see another token.


(10) validity of context attributes when prot_ready_state is returned
     from 7.1. gss_accept_sec_context() and 7.19. gss_init_sec_context().

     rfc2078bis correctly reflects in section 1.2.7, last paragraph
     the requirement(s) for prot_ready_state:

     "When prot_ready_state is returned TRUE, mechanisms shall also set
      those context service indicator flags (deleg_state, mutual_state,
      replay_det_state, sequence_state, anon_state, trans_state,
      conf_avail, integ_avail) which represent facilities confirmed, at
      that time, to be available on the context being established.  In
      situations where prot_ready_state is returned before GSS_S_COMPLETE,
      it is possible that additional facilities may be confirmed and
      subsequently indicated when GSS_S_COMPLETE is returned."

     It is necessary for the flags to indicate only *confirmed*
     facilities, since when the application decides to use immediate
     message protection and send along (sensitive) data, the application
     must be able to match the context attributes against it's policy.

     The current C-Bindings description of the context attributes
     is very detailed, but specifies that all expected, not just the
     confirmed (i.e. guaranteed) features need to be returned.


(11) pairing of major_status codes GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN
     with GSS_S_FAILURE for 7.1. gss_accept_sec_context and
     7.19. gss_init_sec_context

     We had a lengthy discussion on the list of how to distinguish
     mandatory and advisory classification of the major_status values
     GSS_S_OLD_TOKEN, GSS_S_DUPLICATE_TOKEN, GSS_S_UNSEQ_TOKEN and
     GSS_S_GAP_TOKEN.  The resolution is basically captured in
     rfc2078bis, section 1.2.1.1 second paragraph:

     "Sequencing-related informatory major_status codes
      (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and
      GSS_S_GAP_TOKEN) can be indicated in conjunction with either
      GSS_S_COMPLETE or GSS_S_FAILURE status for GSS-API per-message calls.
      For context establishment calls, these sequencing-related codes will
      be indicated only in conjunction with GSS_S_FAILURE status (never in
      conjunction with GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and,
      therefore, always correspond to fatal failures if encountered during
      the context establishment phase."

     The (content of this) paragraph should be adopted by the C-Bindings.
     It may also be a good idea to mention the requirement for pairing
     GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN with GSS_S_FAILURE for
     the context establishment calls in the description of these
     calls where the major_status values are listed.

     It's probably not obvious, but the code example in the C-Bindings
     under 7.1. gss_accept_sec_context() already requires this pairing
     with GSS_S_FAILURE, because it uses the macro GSS_ERROR(maj_stat)
     to check for a fatal error, and this macro suppresses the
     informatory bits GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN.
     (As a result, the example does not abort reliably for GSS-API v1
      mechanisms.)


-Martin