|
Packit |
fd8b60 |
.. _ccache_definition:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Credential cache
|
|
Packit |
fd8b60 |
================
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
A credential cache (or "ccache") holds Kerberos credentials while they
|
|
Packit |
fd8b60 |
remain valid and, generally, while the user's session lasts, so that
|
|
Packit |
fd8b60 |
authenticating to a service multiple times (e.g., connecting to a web
|
|
Packit |
fd8b60 |
or mail server more than once) doesn't require contacting the KDC
|
|
Packit |
fd8b60 |
every time.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
A credential cache usually contains one initial ticket which is
|
|
Packit |
fd8b60 |
obtained using a password or another form of identity verification.
|
|
Packit |
fd8b60 |
If this ticket is a ticket-granting ticket, it can be used to obtain
|
|
Packit |
fd8b60 |
additional credentials without the password. Because the credential
|
|
Packit |
fd8b60 |
cache does not store the password, less long-term damage can be done
|
|
Packit |
fd8b60 |
to the user's account if the machine is compromised.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
A credentials cache stores a default client principal name, set when
|
|
Packit |
fd8b60 |
the cache is created. This is the name shown at the top of the
|
|
Packit |
fd8b60 |
:ref:`klist(1)` *-A* output.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Each normal cache entry includes a service principal name, a client
|
|
Packit |
fd8b60 |
principal name (which, in some ccache types, need not be the same as
|
|
Packit |
fd8b60 |
the default), lifetime information, and flags, along with the
|
|
Packit |
fd8b60 |
credential itself. There are also other entries, indicated by special
|
|
Packit |
fd8b60 |
names, that store additional information.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
ccache types
|
|
Packit |
fd8b60 |
------------
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
The credential cache interface, like the :ref:`keytab_definition` and
|
|
Packit |
fd8b60 |
:ref:`rcache_definition` interfaces, uses `TYPE:value` strings to
|
|
Packit |
fd8b60 |
indicate the type of credential cache and any associated cache naming
|
|
Packit |
fd8b60 |
data to use.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
There are several kinds of credentials cache supported in the MIT
|
|
Packit |
fd8b60 |
Kerberos library. Not all are supported on every platform. In most
|
|
Packit |
fd8b60 |
cases, it should be correct to use the default type built into the
|
|
Packit |
fd8b60 |
library.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#. **API** is only implemented on Windows. It communicates with a
|
|
Packit |
fd8b60 |
server process that holds the credentials in memory for the user,
|
|
Packit |
fd8b60 |
rather than writing them to disk.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#. **DIR** points to the storage location of the collection of the
|
|
Packit |
fd8b60 |
credential caches in *FILE:* format. It is most useful when dealing
|
|
Packit |
fd8b60 |
with multiple Kerberos realms and KDCs. For release 1.10 the
|
|
Packit |
fd8b60 |
directory must already exist. In post-1.10 releases the
|
|
Packit |
fd8b60 |
requirement is for parent directory to exist and the current
|
|
Packit |
fd8b60 |
process must have permissions to create the directory if it does
|
|
Packit |
fd8b60 |
not exist. See :ref:`col_ccache` for details. New in release 1.10.
|
|
Packit |
fd8b60 |
The following residual forms are supported:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
* DIR:dirname
|
|
Packit |
fd8b60 |
* DIR::dirpath/filename - a single cache within the directory
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Switching to a ccache of the latter type causes it to become the
|
|
Packit |
fd8b60 |
primary for the directory.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#. **FILE** caches are the simplest and most portable. A simple flat
|
|
Packit |
fd8b60 |
file format is used to store one credential after another. This is
|
|
Packit |
fd8b60 |
the default ccache type if no type is specified in a ccache name.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#. **KCM** caches work by contacting a daemon process called ``kcm``
|
|
Packit |
fd8b60 |
to perform cache operations. If the cache name is just ``KCM:``,
|
|
Packit |
fd8b60 |
the default cache as determined by the KCM daemon will be used.
|
|
Packit |
fd8b60 |
Newly created caches must generally be named ``KCM:uid:name``,
|
|
Packit |
fd8b60 |
where *uid* is the effective user ID of the running process.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
KCM client support is new in release 1.13. A KCM daemon has not
|
|
Packit |
fd8b60 |
yet been implemented in MIT krb5, but the client will interoperate
|
|
Packit |
fd8b60 |
with the KCM daemon implemented by Heimdal. macOS 10.7 and higher
|
|
Packit |
fd8b60 |
provides a KCM daemon as part of the operating system, and the
|
|
Packit |
fd8b60 |
**KCM** cache type is used as the default cache on that platform in
|
|
Packit |
fd8b60 |
a default build.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#. **KEYRING** is Linux-specific, and uses the kernel keyring support
|
|
Packit |
fd8b60 |
to store credential data in unswappable kernel memory where only
|
|
Packit |
fd8b60 |
the current user should be able to access it. The following
|
|
Packit |
fd8b60 |
residual forms are supported:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
* KEYRING:name
|
|
Packit |
fd8b60 |
* KEYRING:process:name - process keyring
|
|
Packit |
fd8b60 |
* KEYRING:thread:name - thread keyring
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Starting with release 1.12 the *KEYRING* type supports collections.
|
|
Packit |
fd8b60 |
The following new residual forms were added:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
* KEYRING:session:name - session keyring
|
|
Packit |
fd8b60 |
* KEYRING:user:name - user keyring
|
|
Packit |
fd8b60 |
* KEYRING:persistent:uidnumber - persistent per-UID collection.
|
|
Packit |
fd8b60 |
Unlike the user keyring, this collection survives after the user
|
|
Packit |
fd8b60 |
logs out, until the cache credentials expire. This type of
|
|
Packit |
fd8b60 |
ccache requires support from the kernel; otherwise, it will fall
|
|
Packit |
fd8b60 |
back to the user keyring.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
See :ref:`col_ccache` for details.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#. **MEMORY** caches are for storage of credentials that don't need to
|
|
Packit |
fd8b60 |
be made available outside of the current process. For example, a
|
|
Packit |
fd8b60 |
memory ccache is used by :ref:`kadmin(1)` to store the
|
|
Packit |
fd8b60 |
administrative ticket used to contact the admin server. Memory
|
|
Packit |
fd8b60 |
ccaches are faster than file ccaches and are automatically
|
|
Packit |
fd8b60 |
destroyed when the process exits.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#. **MSLSA** is a Windows-specific cache type that accesses the
|
|
Packit |
fd8b60 |
Windows credential store.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. _col_ccache:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Collections of caches
|
|
Packit |
fd8b60 |
---------------------
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Some credential cache types can support collections of multiple
|
|
Packit |
fd8b60 |
caches. One of the caches in the collection is designated as the
|
|
Packit |
fd8b60 |
*primary* and will be used when the collection is resolved as a cache.
|
|
Packit |
fd8b60 |
When a collection-enabled cache type is the default cache for a
|
|
Packit |
fd8b60 |
process, applications can search the specified collection for a
|
|
Packit |
fd8b60 |
specific client principal, and GSSAPI applications will automatically
|
|
Packit |
fd8b60 |
select between the caches in the collection based on criteria such as
|
|
Packit |
fd8b60 |
the target service realm.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Credential cache collections are new in release 1.10, with support
|
|
Packit |
fd8b60 |
from the **DIR** and **API** ccache types. Starting in release 1.12,
|
|
Packit |
fd8b60 |
collections are also supported by the **KEYRING** ccache type.
|
|
Packit |
fd8b60 |
Collections are supported by the **KCM** ccache type in release 1.13.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Tool alterations to use cache collection
|
|
Packit |
fd8b60 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
* :ref:`kdestroy(1)` *-A* will destroy all caches in the collection.
|
|
Packit |
fd8b60 |
* If the default cache type supports switching, :ref:`kinit(1)`
|
|
Packit |
fd8b60 |
*princname* will search the collection for a matching cache and
|
|
Packit |
fd8b60 |
store credentials there, or will store credentials in a new unique
|
|
Packit |
fd8b60 |
cache of the default type if no existing cache for the principal
|
|
Packit |
fd8b60 |
exists. Either way, kinit will switch to the selected cache.
|
|
Packit |
fd8b60 |
* :ref:`klist(1)` *-l* will list the caches in the collection.
|
|
Packit |
fd8b60 |
* :ref:`klist(1)` *-A* will show the content of all caches in the
|
|
Packit |
fd8b60 |
collection.
|
|
Packit |
fd8b60 |
* :ref:`kswitch(1)` *-p princname* will search the collection for a
|
|
Packit |
fd8b60 |
matching cache and switch to it.
|
|
Packit |
fd8b60 |
* :ref:`kswitch(1)` *-c cachename* will switch to a specified cache.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Default ccache name
|
|
Packit |
fd8b60 |
-------------------
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
The default credential cache name is determined by the following, in
|
|
Packit |
fd8b60 |
descending order of priority:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#. The **KRB5CCNAME** environment variable. For example,
|
|
Packit |
fd8b60 |
``KRB5CCNAME=DIR:/mydir/``.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#. The **default_ccache_name** profile variable in :ref:`libdefaults`.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#. The hardcoded default, |ccache|.
|