diff options
author | Greg Hudson <ghudson@mit.edu> | 2013-11-22 16:53:35 -0500 |
---|---|---|
committer | Greg Hudson <ghudson@mit.edu> | 2013-11-22 17:04:48 -0500 |
commit | 482869d393807d02668cf49ce74666d682cf77a6 (patch) | |
tree | e37724dfbb5abd4df7ab5c14be6c4866ff19c301 /doc/basic/ccache_def.rst | |
parent | 251f94621328277044e3ae1a10ecd3ddfdda1dbb (diff) | |
download | krb5-482869d393807d02668cf49ce74666d682cf77a6.tar.gz krb5-482869d393807d02668cf49ce74666d682cf77a6.tar.xz krb5-482869d393807d02668cf49ce74666d682cf77a6.zip |
Edit ccache_def.rst
Re-fill to 70 columns. Replace non-ascii apostrophes with ASCII ones.
Edit wording slightly.
ticket: 7776
Diffstat (limited to 'doc/basic/ccache_def.rst')
-rw-r--r-- | doc/basic/ccache_def.rst | 162 |
1 files changed, 83 insertions, 79 deletions
diff --git a/doc/basic/ccache_def.rst b/doc/basic/ccache_def.rst index 476f21fa8a..85a06d6642 100644 --- a/doc/basic/ccache_def.rst +++ b/doc/basic/ccache_def.rst @@ -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 @@ -67,21 +70,23 @@ 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: @@ -89,45 +94,44 @@ correct to use the default type built into the library. 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`. |