Skip to content

Commit

Permalink
Edit ccache_def.rst
Browse files Browse the repository at this point in the history 
Re-fill to 70 columns.  Replace non-ascii apostrophes with ASCII ones.
Edit wording slightly.

(cherry picked from commit 482869d)

ticket: 7782
version_fixed: 1.11.5
status: resolved
  • Loading branch information
@greghudson @tlyu
greghudson authored and tlyu committed Nov 26, 2013
1 parent c4284d0 commit 5905145
Showing 1 changed file with 83 additions and 79 deletions.
162 changes: 83 additions & 79 deletions doc/basic/ccache_def.rst
View file
Original file line number Diff line number Diff line change
@@ -1,62 +1,65 @@
.. _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 (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 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.
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.
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, that 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.
: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.
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.
#. **API** is only implemented on Windows. 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:
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
Expand All @@ -67,67 +70,68 @@ correct to use the default type built into the library.

* 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.
* 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.
#. **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. Memory
ccaches are faster than file ccaches and are automatically
destroyed when the process exits.

#. **MSLSA** is a Windows-specific cache type that actually accesses the Windows
credential store, similar to the *KEYRING* type for Linux.
#. **MSLSA** is a Windows-specific cache type that accesses the
Windows credential store.


.. _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.
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.
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:`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:`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 default credential cache name is determined by the following, in
descending order of priority:

#. The **KRB5CCNAME** environment variable.
For example, *KRB5CCNAME=DIR:/mydir/*
#. The **KRB5CCNAME** environment variable. For example,
``KRB5CCNAME=DIR:/mydir/``.

#. The **default_ccache_name** profile variable in :ref:`libdefaults`.

Expand Down

0 comments on commit 5905145

Please sign in to comment.