Subject: (il)legal mutations of gssapi objects

From: Martin Rex <[email-masked]>
Date: Fri, 7 Nov 1997 21:08:53 +0100 (MEZ)

Since there seem to be differing opinions about what silent
mutations are (il)legal for the gssapi-defined objects,
we may have to add some words to the specifications to
prevent further/future confusion for mechanism implementers
and applications programmers.

Here is my proposed list of legal and illegal actions concerning
gssapi objects in the ANSI-C environment:

Some of the objects are exposed with their internal structure
some are only referenced by an abstract handle.

Exposed object types:
   gss_OID, gss_OID_set, gss_buffer_t, gss_channel_bindings_t,
   int, bool, OM_uint32, gss_qop_t, gss_cred_usage_t

   Rules for the exposed object types:

     - pure input objects to gssapi routines are strictly readonly
       to the mechanism

     - those parts of in-out and output objects that consist of
       mechanism-allocated memory are strictly readonly to the application

     - objects that are supplied as parameters to a gssapi routine
       may only be accessed/used by the gssapi mechanism during the
       execution of this routine, independent of who originally
       created individual components.

     - when a gssapi routine returns an object containing
       mechanism-allocated memory to the application, all
       change/modification/release control is unconditionally turned
       over to the application.  However, this change/modification/release
       control is strictly limited to other gssapi routines where
       these objects are passed as in-out (modify) parameters.

     - existence of a mechanism-created gss_OID_set and gss_buffer_t
       objects ends when the application calls the respective
       release call with this object.

  example of obviously illegal mechanism behaviour:
    - application call gss_indicate_mechs() and receives an OID_set
      containing OID_mechA and OID_mechB and saves the pointer for
      for future use.
    - due to some external event another gssapi mechanism is added
      to the system
    - the application looks at its saved pointer again and suddenly
      finds a set of 3 OIDs, additionally containing OID_mechC

  expected correct mechanism behaviour (when the gssapi-interface, that
  the application talks to, is capable of runtime configuration changes):
    - the next call to gss_indicate_mechs() will return a different
      pointer to a different OID_set containing all 3 mechanism OIDs.

Abstract object types, referenced by a handle:
   gss_name_t, gss_cred_id_t, gss_ctx_id_t

   The abstract handles are used as an abstraction from individual
   differing implementations with different purposes and needs.

   Rules:
    - for each handle there is a special value that indicates that
      the handle does not reference an object:
          gss_name_t           GSS_C_NO_NAME
          gss_cred_id_t        GSS_C_NO_CREDENTIAL
          gss_ctx_id_t         GSS_C_NO_CONTEXT

    - for some of the gssapi routines, this special value indicates
      a request for a local default object of that type.
      This is for convenience of the application, so that it doesn't
      have to manage that object (creation/deletion).  Creation and
      deletion of substitute virtual objects with "local default"
      characteristics is completely implementation defined, it
      may be limited to the scope of a single gssapi routine.

    - only the gssapi mechanism is able to create, modify and release
      abstract objects.

    - some characteristics of the abstract objects are exposed by
      individual gssapi routines provided by the mechanism.

    - whenever an abstract object is created by a gssapi mechanism and
      its handle is *returned* to the application via an output parameter,
      change/modification/release control for all exposed characteristics
      is unconditionally rendered to the application, EXCEPT for:

         - lifetime of credentials (and components thereof)
         - general validity of credentials (or components)
         - lifetime of security context
         - general validity of security context

      However, modification and release of these objects is strictly
      limited to gssapi routines.

    - the changes in lifetimes of credentials are a local matter.
      Although the lifetime of a credential may change unexpectedly
      with external events like credential refresh, the exposed
      characteristics (see below) of any gss_cred_id_t under control
      of the application MUST NOT change.  Each gss_cred_id_t under
      control of the application where this is impossible, must
      be invalidated by the gssapi mechanism in such a way that it
      will be unfunctional/unusable when being used in future calls of
      the application (except for gss_release_cred()).

    - it is VERY STRONGLY recommended that lifetimes of security
      contexts are monotonically decreasing.  If a security context
      expires, it should remain expired until it is deleted on
      request of the application.  An expired context is VERY STRONGLY
      recommended to retain its exposed characteristics -- to offer
      the applicaton a possibility to create a new security context
      with the exact same characteristics as the expired one,
      a concept referred to as "security context refresh".
     
    - Partly established security contexts may not to be able
      to expose all context characteristics.  For all characteristics
      they do expose, it is recommended that they carry them over
      into the fully established state.
      
    - Currently exposed characteristics of abstract gssapi objects:

         gss_name_t:       the gss_name_t handle value
         *internal name*   (gss_name_t)       name type
	                   (gss_buffer_t)     printable name ***)

         gss_name_t:       the gss_name_t handle value
         *canonical name*  (gss_name_t)       name type
	                   (gss_buffer_t)     exported name
                           (gss_OID)          mechanism OID
                           (gss_buffer_t)     printable name ***)

         gss_cred_id_t:   the gss_cred_id_t handle value
                          (gss_name_t)        owner name (initiator)
                          (gss_name_t)        owner name (acceptor)
                          (gss_OID_set)       list of mechanism
			  (gss_cred_usage_t)  cred usage

         gss_ctx_id_t:    the gss_ctx_id_t handle value
                          (gss_name_t)        initiator name  (canonical)
			  (gss_name_t)        acceptor name   (canonical)
			  (OM_uint32)         context attribute flags
			  (gss_OID)           mechanism OID
                          (boolean)           locally initiated flag
                          (boolean)           partly established flag
			   
      ***) the "printable name" part of a name is only semantically
           static, not syntactically.  :-|

-Martin

---

From: Marc Horowitz <[email-masked]>
Date: 10 Nov 1997 15:58:43 -0500

Martin Rex <[email-masked]> writes:

>> You are already on the right track with the smartcard.  And your
>> "invalidate a credential" is what I was trying to explain.
>> 
>> If the credential can be refreshed, replaced or removed by external events
>> like:
>> 
>>  - pulling out smartcard A and (1) re-inserting smart card A
>>                            or  (2) inserting smartcard B,
>>                            or  (3) leaving reader empty
>> 
>>  - using kinit (4) with the same principal name
>>             or (5) with a different principal name
>>             or (6) using kdestroy or a wrong principal/passwd to kinit
>> 
>> then only a change in the credentials lifetime
>> (GSS_S_CREDENTIALS_EXPIRED) or the overall validity of the
>> credential is ok (GSS_S_DEFECTIVE_CREDENTIAL); changing the
>> principal or credentials owner under the covers for an explicit
>> credential handle held by the application must be considered broken
>> behaviour for a gssapi mechanism.

Ok, this makes sense, and I agree.

>> According to the discussion on the list a while ago, MIT Kerberos
>> didn't handle (5) appropriately -- has this been fixed?

I don't believe so.

		Marc

---

From: Marc Horowitz <[email-masked]>
Date: 10 Nov 1997 14:51:20 -0500

>>        mechanism-allocated memory are strictly readonly to the application

this seems to conflict with the next quote.  How can the memory be
readonly to the application, while the application has
change/modification/release control?

>>        these objects are passed as in-out (modify) parameters.

I'm not sure what you mean by this.  Can you clarify, or give an
example?

>>       limited to gssapi routines.

You keep talking about how the application has c/m/r control, but how
only gssapi routines can c/m/r the object.  I think what you mean is
that the application may only change the objects by making library
calls, and that the library may not change the exposed parts of the
objects except as a result of an application call.  If this is
correct, I find your wording somewhat obscure.

>>       of the application MUST NOT change.  

It may be necessary under some circumstances (smartcards in
particular) to invalidate a credential or context unexpectedly (such
as when the user removes the smartcard).  Otherwise, I think this is
fine.

>>						Each gss_cred_id_t under

Can you explain this further?

		Marc

---

From: Martin Rex <[email-masked]>
Date: Mon, 10 Nov 1997 21:43:36 +0100 (MEZ)

Marc Horowitz wrote:
> >>       change/release control for all exposed characteristics
> You keep talking about how the application has c/r control, but how
> only gssapi routines can c/r the object.  I think what you mean is

This is what I mean.
I'm sorry if my wording is obscure.

then only a change in the credentials lifetime (GSS_S_CREDENTIALS_EXPIRED)
or the overall validity of the credential is ok (GSS_S_DEFECTIVE_CREDENTIAL);
changing the principal or credentials owner under the covers for an
explicit credential handle held by the application must be considered
broken behaviour for a gssapi mechanism.

-Martin

---

From: "Theodore Y. Ts'o" <[email-masked]>
Date: Sat, 15 Nov 1997 20:52:40 -0500

From: Marc Horowitz <[email-masked]>
   Date: 10 Nov 1997 15:58:43 -0500

   I don't believe so.

I just checked in a change to the MIT source tree to deal with this
case, so it'll be fixed in the next release.

						- Ted