This little document is about the current behavior of the GSSProxy and the
libgssapi interposer plugin.
Each is documented separately.

Note that the GSSProxy act as server not only for the interposer plugin but
also directly for the kernel and potentially for other clients, so the proxy
behavior may include additional behaviors not directly available to the
libgssapi interposer plugin.

NOTE:
This document should be upgraded every time we change the proxy or the plugin
behavior, however it is my experience that developers forget to do so, so here
we have also a timestamp from the last update:
20120910

If it is way too much in the past then something in the actual code may not
reflect this document anymore, and please yell at the current maintainer to
bring it up to date :-)


GSS Proxy
-----------------------------------------------------------------------------


Application based behavior:
Currently GSS Proxy can be configure to behave differently for each 'user'
connecting to it. By user here we really mean euid at this point (we are
planning to make it possible to act on a per-application basis provided SELinux
is used and each application has a different label that can be trasmitted via
SM Rights like calls).

The euid is obtained through a SCM Rigths call on the Unix Socket used to talk
to the proxy.

Each euid can have a config entry which can specify whether the euid is trusted
or not and based on specific mechanism some options. The currently only
supported mechanism is krb5. For this mechanism a euid specific keytab and
ccache can be specified.

When a 'user' is considered trusted it means it is allowed to command gss-proxy
to act on behalf of another user (for example init a context as a user
specified in an optional field in the protocol).

The following table represent the current thinking around default/allowed
behavior depending on the connecting peer:

--------------------------------------------------------------------
|  Operation   |       Initiate       |         Accept             |
|Peer          |                      |                            |
--------------------------------------------------------------------
|              |With ccache available | Never allow to accept for  |
|euid not      |always try to init    | unconfigured euids         |
|explicitly    |                      |                            |
|configured in |Use default ccache    |                            |
|gssproxy.conf |defined in [global]   |                            |
|              |                      |                            |
|              |Never use keytab      |                            |
---------------|----------------------|-----------------------------
|              |With ccache available | If keytab is explicitly    |
|euid X        |always try to init    | configured always allow to |
|(referenced   |                      | try to accept via proxy    |
| explicitly   |When keytab available |                            |
| in a config  |init with keytab only |                            |
| section)     |if following option   |                            |
|              |is set to True:       |                            |
|              |krb5_init_with_keytab |                            |
|              |defaults to False     |                            |
---------------|----------------------|-----------------------------
|              |                      | If keytab is explicitly    |
|euid 0        |                      | configured always allow to |
|              |                      | try to accept via proxy    |
|              |                      |                            |
|              |                      | Allow to fallback to host  |
|              |                      | keytab if not configured ? |
--------------------------------------------------------------------



Credentials:
At the moment the GSS Proxy cannot be fully stateless due to limitations in
GSSAPI (they are being addressed in MIT 1.11). The gss-proxy keeps a list of
credential structs in a ring buffer and sends applications an encrypted token to
reference them when the same credential needs to be used across multiple calls.

Contexts:
Context are always exported to the clients once obtained.
Currently both lucid-type contexts and native MIT format contexts are
supported.







libgssapi Interposer Plugin
-----------------------------------------------------------------------------

The Interposer plugin currently tries to perform local only operations first
and falls back to try proxy communication if it can't obtain
contexts/credentials using local calls.
Also an environment variable can be used to change this behavior somewhat
(NOTE: still inconsistent while developing the feature). The variable is
called: GSSPROXY_BEHAVIOR and allowed values are: LOCAL_ONLY, LOCAL_FIRST,
REMOTE_ONLY, REMOTE_FIRST.

Currently only a hardcoded set of mechanism is supported, however in future it
is planned that the supported set of mechanism to be queried from the gssproxy
and/or the configuration file instead.


