-
Notifications
You must be signed in to change notification settings - Fork 366
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
- Loading branch information
Showing
2 changed files
with
135 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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|. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -7,6 +7,7 @@ Kerberos V5 concepts | |
.. toctree:: | ||
:maxdepth: 1 | ||
|
||
ccache_def | ||
keytab_def | ||
rcache_def | ||
stash_file_def | ||
|