A Kerberos credential (also called a "Kerberos ticket") is a time-limited token issued by a KDC which authenticates the entity named by the credential's client identity to the service named by the credential's service identity.
The kim_credential_t object contains a single Kerberos credential. KIM credentials objects are always copies of credentials, not references to credentials stored in the cache collection. Modifying credential objects in the ccache collection will not change any existing KIM credential objects.
KIM credential APIs are intended for applications and system tools which manage credentials for the user. They are not a substitute for krb5 and GSSAPI functions which obtain service credentials for the purpose of authenticating a client to an application server.
- Note:
- Many of the APIs listed below have equivalent functions which operate on ccaches. In most cases applications will want to use the ccache versions of these APIs since they automatically store any newly created credentials. See KIM CCache Overview for more information.
KIM provides the
kim_credential_create_new() API for acquiring new credentials. Credentials can either be obtained for a specific client identity or by specifying
KIM_IDENTITY_ANY to allow the user to choose. Typically callers of this API obtain the client identity using
kim_selection_hints_get_identity(). Depending on the kim_options specified,
kim_credential_create_new() may present a GUI or command line prompt to obtain information from the user.
KIM provides the kim_credential_create_from_keytab() to create credentials using a keytab. A keytab is an on-disk copy of a client identity's secret key. Typically sites use keytabs for client identities that identify a machine or service and protect the keytab with disk permissions. Because a keytab is sufficient to obtain credentials, keytabs will normally only be readable by root, Administrator or some other privileged account. Typically applications use credentials obtained from keytabs to obtain credentials for batch processes. These keytabs and credentials are usually for a special identity used for the batch process rather than a user identity.
A credential with a start time in the future (ie: after the issue date) is called a post-dated credential. Because the KDC administrator may wish to disable a identity, once the start time is reached, all post-dated credentials must be validated before they can be used. Otherwise an attacker using a compromised account could acquire lots of post-dated credentials to circumvent the acccount being disabled.
KIM provides the kim_credential_validate() API to validate a credential. Note that this API replaces the credential object with a new validated credential object. If you wish to store this API in the ccache collection you must either call kim_credential_store() on the validated credential or use kim_ccache_validate() instead.
A renewable credential can be used to obtain a new identical credential without resending secret information (such as a password) to the KDC. A credential may only be renewed during its renewal lifetime and while valid.
KIM provides the kim_credential_renew() API to renew a credential. Note that this API replaces the credential object with a new renewed credential object. If you wish to store this API in the ccache collection you must either call kim_credential_store() on the renewed credential or use kim_ccache_renew() instead.
KIM credential objects may be stored in the ccache collection using
kim_credential_store(). This function runs any KIM authentication plugins on the credential and if the plugins return successfully, creates a new ccache for the credential's client identity in the cache collection and stores the credential in that ccache. Any existing ccaches and credentials for that client identity will be overwritten.
kim_credential_store() may optionally return a kim_ccache_t object for the new ccache if you need to perform further operations on the new ccache.
Most of the time if you plan to store the credentials you are manipulating, you should use one of KIM ccache APIs. These functions perform the same operations except that they also call kim_credential_store() any time the credential object changes. See KIM CCache Overview for more information.
KIM provides a simple iterator API for iterating over the credentials in a ccache. First, call
kim_credential_iterator_create() to obtain an iterator for a ccache. Then loop calling
kim_credential_iterator_next() until either you find the credential you are looking for or the API returns a NULL credential, indicating that there are no more credentials in the ccache. When you are done with the iterator, call
kim_credential_iterator_free().
- Note:
- kim_credential_iterator_next() returns credential objects which must be freed with kim_credential_free() to avoid leaking memory.
When a program acquires TGT credentials for the purpose of authenticating itself to the machine it is running on, it is insufficient for the machine to assume that the caller is authorized just because it got credentials. Instead, the credentials must be verified using a key the local machine. The reason this is necessary is because an attacker can trick the machine into obtaining credentials from any KDC, including malicious ones with the same realm name as the local machine's realm. This exploit is called the Zanarotti attack.
In order to avoid the Zanarotti attack, the local machine must authenticate the process in the same way an application server would authenticate a client. Like an application server, the local machine must have its own identity in its realm and a keytab for that identity on its local disk. However, rather than forcing system daemons to use the network-oriented calls in the krb5 and GSS APIs, KIM provides the kim_credential_verify() API to verify credentials directly.
The most common reason for using kim_credential_verify() is user login. If the local machine wants to use Kerberos to verify the username and password provided by the user, it must call kim_credential_verify() on the credentials it obtains to make sure they are really from a KDC it trusts. Another common case is a server which is only using Kerberos internally. For example an LDAP or web server might use a username and password obtained over the network to get Kerberos credentials. In order to make sure they aren't being tricked into talking to the wrong KDC, these servers must also call kim_credential_verify().
The Zanarotti attack is only a concern if the act of accessing the machine gives the process special access. Thus a managed cluster machine with Kerberos-authenticated networked home directories does not need to call kim_credential_verify(). Even though an attacker can log in as any user on the cluster machine, the attacker can't actually access any of the user's data or use any of their privileges because those are all authenticated via Kerberized application servers (and thus require actually having credentials for the real local realm).
kim_credential_verify() provides an option to return success even if the machine's host key is not present. This option exists for sites which have a mix of different machines, some of which are vulnerable to the Zanarotti attack and some are not. If this option is used, it is the responsiblity of the machine's maintainer to obtain a keytab for their machine if it needs one.
- kim_credential_is_tgt() returns whether the credential is a TGT (ie: "ticket-granting ticket"). TGTs are credentials for the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>". These credentials allow the entity named by the client identity to obtain additional service credentials without resending shared secrets (such as a password) to the KDC. Kerberos uses TGTs to provide single sign-on authentication.
- kim_credential_get_start_time() returns when the credential will become valid. Credentials may be "post-dated" which means that their lifetime starts sometime in the future. Note that when a post-dated credential's start time is reached, the credential must be validated. See Validating Credentials for more information.
- kim_credential_get_expiration_time() returns when the credential will expire. Credentials are time limited by the lifetime of the credential. While you can request a credential of any lifetime, the KDC limits the credential lifetime to a administrator-defined maximum. Typically credential lifetime range from 10 to 21 hours.
- kim_credential_get_renewal_expiration_time() returns when the credential will no longer be renewable. Valid credentials may be renewed up until their renewal expiration time. Renewing credentials acquires a fresh set of credentials with a full lifetime without resending secrets to the KDC (such as a password). If credentials are not renewable, this function will return an error.
See
KIM Credential Reference Documentation and
KIM Credential Iterator Reference Documentation for information on specific APIs.
