Add doc about current and future planned behavior

1 files changed, 111 insertions, 0 deletions

diff --git a/proxy/docs/Behavior b/proxy/docs/Behavior
new file mode 100644
index 0000000..7ee93fe
--- /dev/null
+++ b/proxy/docs/Behavior
@@ -0,0 +1,111 @@
+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.
+
+