1.. _ccache_definition: 2 3Credential cache 4================ 5 6A credential cache (or "ccache") holds Kerberos credentials while they 7remain valid and, generally, while the user's session lasts, so that 8authenticating to a service multiple times (e.g., connecting to a web 9or mail server more than once) doesn't require contacting the KDC 10every time. 11 12A credential cache usually contains one initial ticket which is 13obtained using a password or another form of identity verification. 14If this ticket is a ticket-granting ticket, it can be used to obtain 15additional credentials without the password. Because the credential 16cache does not store the password, less long-term damage can be done 17to the user's account if the machine is compromised. 18 19A credentials cache stores a default client principal name, set when 20the cache is created. This is the name shown at the top of the 21:ref:`klist(1)` *-A* output. 22 23Each normal cache entry includes a service principal name, a client 24principal name (which, in some ccache types, need not be the same as 25the default), lifetime information, and flags, along with the 26credential itself. There are also other entries, indicated by special 27names, that store additional information. 28 29 30ccache types 31------------ 32 33The credential cache interface, like the :ref:`keytab_definition` and 34:ref:`rcache_definition` interfaces, uses `TYPE:value` strings to 35indicate the type of credential cache and any associated cache naming 36data to use. 37 38There are several kinds of credentials cache supported in the MIT 39Kerberos library. Not all are supported on every platform. In most 40cases, it should be correct to use the default type built into the 41library. 42 43#. **API** is only implemented on Windows. It communicates with a 44 server process that holds the credentials in memory for the user, 45 rather than writing them to disk. 46 47#. **DIR** points to the storage location of the collection of the 48 credential caches in *FILE:* format. It is most useful when dealing 49 with multiple Kerberos realms and KDCs. For release 1.10 the 50 directory must already exist. In post-1.10 releases the 51 requirement is for parent directory to exist and the current 52 process must have permissions to create the directory if it does 53 not exist. See :ref:`col_ccache` for details. New in release 1.10. 54 The following residual forms are supported: 55 56 * DIR:dirname 57 * DIR::dirpath/filename - a single cache within the directory 58 59 Switching to a ccache of the latter type causes it to become the 60 primary for the directory. 61 62#. **FILE** caches are the simplest and most portable. A simple flat 63 file format is used to store one credential after another. This is 64 the default ccache type if no type is specified in a ccache name. 65 66#. **KCM** caches work by contacting a daemon process called ``kcm`` 67 to perform cache operations. If the cache name is just ``KCM:``, 68 the default cache as determined by the KCM daemon will be used. 69 Newly created caches must generally be named ``KCM:uid:name``, 70 where *uid* is the effective user ID of the running process. 71 72 KCM client support is new in release 1.13. A KCM daemon has not 73 yet been implemented in MIT krb5, but the client will interoperate 74 with the KCM daemon implemented by Heimdal. macOS 10.7 and higher 75 provides a KCM daemon as part of the operating system, and the 76 **KCM** cache type is used as the default cache on that platform in 77 a default build. 78 79#. **KEYRING** is Linux-specific, and uses the kernel keyring support 80 to store credential data in unswappable kernel memory where only 81 the current user should be able to access it. The following 82 residual forms are supported: 83 84 * KEYRING:name 85 * KEYRING:process:name - process keyring 86 * KEYRING:thread:name - thread keyring 87 88 Starting with release 1.12 the *KEYRING* type supports collections. 89 The following new residual forms were added: 90 91 * KEYRING:session:name - session keyring 92 * KEYRING:user:name - user keyring 93 * KEYRING:persistent:uidnumber - persistent per-UID collection. 94 Unlike the user keyring, this collection survives after the user 95 logs out, until the cache credentials expire. This type of 96 ccache requires support from the kernel; otherwise, it will fall 97 back to the user keyring. 98 99 See :ref:`col_ccache` for details. 100 101#. **MEMORY** caches are for storage of credentials that don't need to 102 be made available outside of the current process. For example, a 103 memory ccache is used by :ref:`kadmin(1)` to store the 104 administrative ticket used to contact the admin server. Memory 105 ccaches are faster than file ccaches and are automatically 106 destroyed when the process exits. 107 108#. **MSLSA** is a Windows-specific cache type that accesses the 109 Windows credential store. 110 111 112.. _col_ccache: 113 114Collections of caches 115--------------------- 116 117Some credential cache types can support collections of multiple 118caches. One of the caches in the collection is designated as the 119*primary* and will be used when the collection is resolved as a cache. 120When a collection-enabled cache type is the default cache for a 121process, applications can search the specified collection for a 122specific client principal, and GSSAPI applications will automatically 123select between the caches in the collection based on criteria such as 124the target service realm. 125 126Credential cache collections are new in release 1.10, with support 127from the **DIR** and **API** ccache types. Starting in release 1.12, 128collections are also supported by the **KEYRING** ccache type. 129Collections are supported by the **KCM** ccache type in release 1.13. 130 131 132Tool alterations to use cache collection 133~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 134 135* :ref:`kdestroy(1)` *-A* will destroy all caches in the collection. 136* If the default cache type supports switching, :ref:`kinit(1)` 137 *princname* will search the collection for a matching cache and 138 store credentials there, or will store credentials in a new unique 139 cache of the default type if no existing cache for the principal 140 exists. Either way, kinit will switch to the selected cache. 141* :ref:`klist(1)` *-l* will list the caches in the collection. 142* :ref:`klist(1)` *-A* will show the content of all caches in the 143 collection. 144* :ref:`kswitch(1)` *-p princname* will search the collection for a 145 matching cache and switch to it. 146* :ref:`kswitch(1)` *-c cachename* will switch to a specified cache. 147 148 149Default ccache name 150------------------- 151 152The default credential cache name is determined by the following, in 153descending order of priority: 154 155#. The **KRB5CCNAME** environment variable. For example, 156 ``KRB5CCNAME=DIR:/mydir/``. 157 158#. The **default_ccache_name** profile variable in :ref:`libdefaults`. 159 160#. The hardcoded default, |ccache|. 161