krb5 commit: Added a new ccache doc to "Kerberos V5 concepts"
Zhanna A Tsitkova
tsitkova at MIT.EDU
Fri Nov 22 14:41:08 EST 2013
https://github.com/krb5/krb5/commit/251f94621328277044e3ae1a10ecd3ddfdda1dbb
commit 251f94621328277044e3ae1a10ecd3ddfdda1dbb
Author: Zhanna Tsitkov <tsitkova at mit.edu>
Date: Fri Nov 22 14:02:57 2013 -0500
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
doc/basic/ccache_def.rst | 134 ++++++++++++++++++++++++++++++++++++++++++++++
doc/basic/index.rst | 1 +
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 0000000..476f21f
--- /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 e7a6930..87a9b54 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
More information about the cvs-krb5
mailing list