.. _ccselect_plugin:

Credential cache selection interface (ccselect)
===============================================

The ccselect interface allows modules to control how credential caches
are chosen when a GSSAPI client contacts a service.  For a detailed
description of the ccselect interface, see the header file
``<krb5/ccselect_plugin.h>``.

The primary ccselect method is **choose**, which accepts a server
principal as input and returns a ccache and/or principal name as
output.  A module can use the krb5_cccol APIs to iterate over the
cache collection in order to find an appropriate ccache to use.

.. TODO: add reference to the admin guide for ccaches and cache
   collections when we have appropriate sections.

A module can create and destroy per-library-context state objects by
implementing the **init** and **fini** methods.  State objects have
the type krb5_ccselect_moddata, which is an abstract pointer type.  A
module should typically cast this to an internal type for the state
object.

A module can have one of two priorities, "authoritative" or
"heuristic".  Results from authoritative modules, if any are
available, will take priority over results from heuristic modules.  A
module communicates its priority as a result of the **init** method.