Added a new ccache doc to "Kerberos V5 concepts"

This is to add a short introductory document on credential
caches to the Concepts section of Kerberos documentation.

ticket: 7776 (new)
target_version: 1.12
tags: pullup

2 files changed, 135 insertions, 0 deletions

diff --git a/doc/basic/ccache_def.rst b/doc/basic/ccache_def.rst
new file mode 100644
index 0000000000..476f21fa8a
--- /dev/null
+++ b/doc/basic/ccache_def.rst
@@ -0,0 +1,134 @@
+.. _ccache_definition:
+
+Credential cache
+=================
+
+A credential cache (or "ccache") holds Kerberos credentials while they remain
+valid and, generally, while the user's session lasts, so that authenticating
+to a service multiple times (e.g., connecting to a web or mail server more
+than once) doesn't require contacting the KDC every time.
+
+A credential cache usually contains one initial ticket which is obtained
+using a password or another form of identity verification.  If this
+ticket is a ticket-granting ticket, it can be used to obtain additional
+credentials without the password.  Because the credential cache does not
+store the password, less long-term damage can be done to the user’s
+account if the machine is compromised.
+
+A credentials cache stores a default client principal name, set when the cache
+is created.  This is the name shown at the top of the :ref:`klist(1)` *-A*
+output.
+
+Each normal cache entry includes a service principal name, a client principal
+name (which, in some ccache types, need not be the same as the default),
+lifetime information, and flags, along with the credential itself.  There are
+also other entries indicated by special names which store additional
+information.
+
+
+ccache types
+------------
+
+The credential cache interface, like the :ref:`keytab_definition` and
+:ref:`rcache_definition` interfaces, uses `TYPE:value` strings to indicate the
+type of credential cache and any associated cache naming data to use.
+
+There are several kinds of credentials cache supported in the MIT Kerberos
+library.  Not all are supported on every platform.  In most cases, it should be
+correct to use the default type built into the library.
+
+#. **API** is implemented only on Windows platform.  It communicates with a
+   server process that holds the credentials in memory for the user, rather
+   than writing them to disk.
+
+#. **DIR** points to the storage location of the collection of the
+   credential caches in *FILE:* format. It is most useful when dealing with
+   multiple Kerberos realms and KDCs.  For release 1.10 the directory must
+   already exist.  In post-1.10 releases the requirement is for parent
+   directory to exist and the current process must have permissions to create
+   the directory if it does not exist. See :ref:`col_ccache` for details.
+   New in release 1.10.
+
+#. **FILE** caches are the simplest and most portable. A simple flat file
+   format is used to store one credential after another.  This is the default
+   ccache type.
+
+#. **KEYRING** is Linux-specific, and uses the kernel keyring support to store
+   credential data in unswappable kernel memory where only the current user
+   should be able to access it.
+   The following residual forms are supported:
+
+   * KEYRING:name
+   * KEYRING:process:name - process keyring
+   * KEYRING:thread:name -  thread keyring
+
+   Starting with release 1.12 the *KEYRING* type supports collections.
+   The following new residual forms were added:
+
+   * KEYRING:session:name - session keyring
+   * KEYRING:user:name - user keyring
+   * KEYRING:persistent:uidnumber - persistent per-UID collection.  Unlike
+     the user keyring, this collection survives after the user logs out,
+     until the cache credentials expire.  This type of ccache requires
+     support from the kernel; otherwise, it will fall back to the user keyring.
+
+   See :ref:`col_ccache` for details.
+
+#. **MEMORY** caches are for storage of credentials that don’t need to be
+   made available outside of the current process.  For example, a *MEMORY*
+   ccache is used by :ref:`kadmin(1)` to store the administrative ticket
+   used to contact the admin server.  It's a bit faster, it doesn't write
+   anything to disk, and it's trivial to destroy when you're done with it.
+
+#. **MSLSA** is a Windows-specific cache type that actually accesses the Windows
+   credential store, similar to the *KEYRING* type for Linux.
+
+
+.. _col_ccache:
+
+Collections of caches
+---------------------
+
+Some credential cache types can support collections of multiple caches.
+One of the caches in the collection is designated as the *primary* and
+will be used when the collection is resolved as a cache.  When a
+collection-enabled cache type is the default cache for a process,
+applications can search the specified collection for a specific client
+principal, and GSSAPI applications will automatically select between the
+caches in the collection based on criteria such as the target service realm.
+
+Credential cache collections are new in release 1.10, with support from the
+**DIR** and **API** ccache types.  In release 1.12, the **KEYRING** ccache
+type also supports collections.
+
+Tool alterations to use cache collection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* :ref:`kdestroy(1)` *-A*  will destroy all caches in the collection.
+* If the default cache type supports switching, :ref:`kinit(1)` *princname*
+  will search the collection for a matching cache and store credentials
+  there, or will store credentials in a new unique cache of the default type
+  if no existing cache for the principal exists. Either way, kinit will switch
+  to the selected cache.
+* :ref:`klist(1)` *-l* will list the caches in the collection.
+* :ref:`klist(1)` *-A* will show the content of all caches in the collection.
+* :ref:`kswitch(1)` *-p princname* will search the collection for a matching
+  cache and switch to it.
+* :ref:`kswitch(1)` *-c cachename* will switch to a specified cache.
+
+
+
+Default ccache name
+-------------------
+
+The default ccache name is OS specific. It can be overridden by the
+**KRB5CCNAME** environment variable.
+
+The placement of the credential cache file is determined by the following:
+
+#. The **KRB5CCNAME** environment variable.
+   For example, *KRB5CCNAME=DIR:/mydir/*
+
+#. The **default_ccache_name** profile variable in :ref:`libdefaults`.
+
+#. The hardcoded default, |ccache|.
diff --git a/doc/basic/index.rst b/doc/basic/index.rst
index e7a69301d2..87a9b5472f 100644
--- a/doc/basic/index.rst
+++ b/doc/basic/index.rst
@@ -7,6 +7,7 @@ Kerberos V5 concepts
 .. toctree::
    :maxdepth: 1
 
+   ccache_def
    keytab_def
    rcache_def
    stash_file_def