diff options
-rw-r--r-- | doc/basic/ccache_def.rst | 134 | ||||
-rw-r--r-- | 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 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 |