1/*
2 * Copyright 2005-2006 Massachusetts Institute of Technology.
3 * All Rights Reserved.
4 *
5 * Export of this software from the United States of America may
6 * require a specific license from the United States Government.
7 * It is the responsibility of any person or organization contemplating
8 * export to obtain such a license before exporting.
9 *
10 * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
11 * distribute this software and its documentation for any purpose and
12 * without fee is hereby granted, provided that the above copyright
13 * notice appear in all copies and that both that copyright notice and
14 * this permission notice appear in supporting documentation, and that
15 * the name of M.I.T. not be used in advertising or publicity pertaining
16 * to distribution of the software without specific, written prior
17 * permission.  Furthermore if you modify this software you must label
18 * your software as modified software and not distribute it in such a
19 * fashion that it might be confused with the original M.I.T. software.
20 * M.I.T. makes no representations about the suitability of
21 * this software for any purpose.  It is provided "as is" without express
22 * or implied warranty.
23 */
24
25#ifndef KIM_CCACHE_H
26#define KIM_CCACHE_H
27
28#ifdef __cplusplus
29extern "C" {
30#endif
31
32#include <Kerberos/kim_types.h>
33
34/*!
35 * \page kim_ccache_overview KIM CCache Overview
36 *
37 * \section kim_ccache_introduction Introduction
38 *
39 * Kerberos credentials are stored in "ccaches" (short for "credentials caches").
40 * The set of all ccaches which the KIM can use is called the "cache collection".
41 * Each ccache has a name and type which uniquely identify it in the cache
42 * collection and a client identity.  The ccache's client identity is the
43 * identity whose credentials are stored in the ccache.  This allows for easy
44 * lookup of all the credentials for a given identity.
45 *
46 * KIM attempts to preserve a one-to-one relationship between client identities
47 * and ccaches.  If the KIM is used to manipulate the cache collection, there
48 * will be one ccache per identity.  However, because low-level APIs allow callers
49 * to create multiple ccaches for the same client identity or a single ccache
50 * containing credentials for different client identities, KIM handles those
51 * situations.  In general when searching KIM will find the first ccache matching
52 * the requested client identity.  It will not find credentials for the requested
53 * client identity if they are in a ccache with a different client identity.
54 *
55 * The kim_ccache_t object is a reference to a ccache in the cache collection.
56 * If other applications make changes to the the ccache pointed to by a KIM ccache
57 * object, the object will immediately show those changes.  KIM performs locking
58 * on the cache collection to prevent deadlocks and maintain a consistent behavior
59 * when multiple applications attempt to modify the cache collection.
60 *
61 * \note KIM ccache APIs are intended for applications and system
62 * tools which manage credentials for the user.  They are not a substitute for
63 * krb5 and GSSAPI functions which obtain service credentials for the purpose
64 * of authenticating a client to an application server.
65 *
66 * \section kim_credential_cache_collection Acquiring a CCache from the Cache Collection
67 *
68 * KIM provides a simple iterator API for iterating over the ccaches
69 * in the cache collection.  First, call #kim_ccache_iterator_create() to obtain
70 * an iterator for the cache collection.  Then loop calling
71 * #kim_ccache_iterator_next() until either you find the ccache you are looking
72 * for or the API returns a NULL ccache, indicating that there are no more
73 * ccaches in the cache collection.  When you are done with the iterator, call
74 * #kim_ccache_iterator_free().
75 *
76 * \note #kim_ccache_iterator_next() returns ccache objects which
77 * must be freed with #kim_ccache_free() to avoid leaking memory.
78 *
79 * KIM also provides a convenient API #kim_ccache_create_from_client_identity()
80 * which returns the ccache for a specific client identity, if any exists.
81 * Typically callers of this API obtain the client identity using
82 * #kim_selection_hints_get_identity().
83 *
84 *
85 * \section kim_ccache_acquire_default Acquiring Credentials from the Default CCache
86 *
87 * #kim_ccache_create_from_default() returns the default ccache.
88 * The default ccache is a legacy concept which was replaced by selection
89 * hints.  Prior to the existence of selection hints, applications always
90 * looked at the default ccache for credentials.  By setting the system default
91 * ccache, users could manually control which credentials each application used.
92 * As the number of ccaches and applications has grown, this mechanism has become
93 * unusable.  You should avoid using this API whenever possible.
94 *
95 *
96 * \section kim_ccache_acquire_new Acquiring New Credentials in a CCache
97 *
98 * KIM provides the #kim_ccache_create_new() API for acquiring new
99 * credentials and storing them in a ccache.  Credentials can either be
100 * obtained for a specific client identity or by specifying
101 * #KIM_IDENTITY_ANY to allow the user to choose.  Typically
102 * callers of this API obtain the client identity using
103 * #kim_selection_hints_get_identity().  Depending on the kim_options
104 * specified, #kim_ccache_create_new() may present a GUI or command line
105 * prompt to obtain information from the user.
106 *
107 * #kim_ccache_create_new_if_needed()
108 * searches the cache collection for a ccache for the client identity
109 * and if no appropriate ccache is available, attempts to acquire
110 * new credentials and store them in a new ccache.  Depending on the
111 * kim_options specified, #kim_ccache_create_new_if_needed() may
112 * present a GUI or command line prompt to obtain information from the
113 * user. This function exists for convenience and to avoid code duplication.
114 * It can be trivially implemented using
115 * #kim_ccache_create_from_client_identity() and #kim_ccache_create_new().
116 *
117 * For legacy password-based Kerberos environments KIM also provides
118 * #kim_ccache_create_new_with_password() and
119 * #kim_ccache_create_new_if_needed_with_password().  You should not use these
120 * functions unless you know that they will only be used in environments using
121 * passwords.  Otherwise users without passwords may be prompted for them.
122 *
123 * KIM provides the #kim_ccache_create_from_keytab() to create credentials
124 * using a keytab and store them in the cache collection. A keytab is an
125 * on-disk copy of a client identity's secret key.  Typically sites use
126 * keytabs for client identities that identify a machine or service and
127 * protect the keytab with disk permissions.  Because a keytab is
128 * sufficient to obtain credentials, keytabs will normally only be readable
129 * by root, Administrator or some other privileged account.
130 * Typically applications use credentials obtained from keytabs to obtain
131 * credentials for batch processes.  These keytabs and credentials are usually
132 * for a special identity used for the batch process rather than a user
133 * identity.
134 *
135 *
136 * \section kim_ccache_validate Validating Credentials in a CCache
137 *
138 * A credential with a start time in the future (ie: after the issue date)
139 * is called a post-dated credential.  Because the KDC administrator may
140 * wish to disable a identity, once the start time is reached, all post-dated
141 * credentials must be validated before they can be used.  Otherwise an
142 * attacker using a compromised account could acquire lots of post-dated
143 * credentials to circumvent the acccount being disabled.
144 *
145 * KIM provides the #kim_ccache_validate() API to validate the TGT
146 * credential in a ccache. Note that this API replaces any existing
147 * credentials with the validated credential.
148 *
149 *
150 * \section kim_ccache_renew Renewing Credentials in a CCache
151 *
152 * A renewable credential can be used to obtain a new identical credential
153 * without resending secret information (such as a password) to the KDC.
154 * A credential may only be renewed during its renewal lifetime and while
155 * valid.
156 *
157 * KIM provides the #kim_ccache_renew() API to renew the TGT credential
158 * in a ccache. Note that this API replaces any existing credentials with the
159 * renewed credential.
160 *
161 *
162 * \section kim_ccache_verify Verifying Credentials in a CCache
163 *
164 * When a program acquires TGT credentials for the purpose of authenticating
165 * itself to the machine it is running on, it is insufficient for the machine
166 * to assume that the caller is authorized just because it got credentials.
167 * Instead, the credentials must be verified using a key the local machine.
168 * The reason this is necessary is because an attacker can trick the
169 * machine into obtaining credentials from any KDC, including malicious ones
170 * with the same realm name as the local machine's realm.  This exploit is
171 * called the Zanarotti attack.
172 *
173 * In order to avoid the Zanarotti attack, the local machine must authenticate
174 * the process in the same way an application server would authenticate a client.
175 * Like an application server, the local machine must have its own identity in
176 * its realm and a keytab for that identity on its local disk.    However,
177 * rather than forcing system daemons to use the network-oriented calls in the
178 * krb5 and GSS APIs, KIM provides the #kim_ccache_verify() API to
179 * verify credentials directly.
180 *
181 * The most common reason for using #kim_ccache_verify() is user login.
182 * If the local machine wants to use Kerberos to verify the username and password
183 * provided by the user, it must call #kim_ccache_verify() on the credentials
184 * it obtains to make sure they are really from a KDC it trusts.  Another common
185 * case is a server which is only using Kerberos internally.  For example an
186 * LDAP or web server might use a username and password obtained over the network
187 * to get Kerberos credentials.  In order to make sure they aren't being tricked
188 * into talking to the wrong KDC, these servers must also call
189 * #kim_ccache_verify().
190 *
191 * The Zanarotti attack is only a concern if the act of accessing the machine
192 * gives the process special access.  Thus a managed cluster machine with
193 * Kerberos-authenticated networked home directories does not need to call
194 * #kim_ccache_verify().  Even though an attacker can log in as any user on
195 * the cluster machine, the attacker can't actually access any of the user's data
196 * or use any of their privileges because those are all authenticated via
197 * Kerberized application servers (and thus require actually having credentials
198 * for the real local realm).
199 *
200 * #kim_ccache_verify() provides an option to
201 * return success even if the machine's host key is not present.  This option
202 * exists for sites which have a mix of different machines, some of which are
203 * vulnerable to the Zanarotti attack and some are not.  If this option is used,
204 * it is the responsiblity of the machine's maintainer to obtain a keytab
205 * for their machine if it needs one.
206 *
207 *
208 * \section kim_ccache_properties Examining CCache Properties
209 *
210 * \li #kim_ccache_get_type() returns the type of the ccache.  Types include
211 * "API" for CCAPI ccaches, "FILE" for file-based ccaches and "MEMORY" for
212 * single-process in-memory ccaches.
213 *
214 * \li #kim_ccache_get_name() returns the name of the ccache.  A ccache's name
215 * identifies the ccache uniquely among ccaches of the same type.  Note that
216 * two ccaches with different types may have the same name.
217 *
218 * \li #kim_ccache_get_display_name() returns a display string which uniquely
219 * identifies a ccache.  A ccache display name is of the form "<type>:<name>"
220 * and can be displayed to the user or used as an argument to certain krb5
221 * APIs, such as krb5_cc_resolve().
222 *
223 * \li #kim_ccache_get_client_identity()
224 * returns the ccache's client identity.
225 *
226 * \li #kim_ccache_get_valid_credential()
227 * returns the first valid TGT in the ccache for its client identity.
228 * If there are no TGTs in the ccache, it returns the first
229 * valid non-TGT credential for the ccache's client identity.
230 * TGT credentials (ie: "ticket-granting tickets") are credentials for
231 * the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>".
232 * These credentials allow the entity named by the client identity to obtain
233 * additional credentials without resending shared secrets (such as a password)
234 * to the KDC. Kerberos uses TGTs to provide single sign-on authentication.
235 *
236 * \li #kim_ccache_get_start_time()
237 * returns when the credential's in a ccache will become valid.
238 * Credentials may be "post-dated" which means that their lifetime starts sometime
239 * in the future.  Note that when a post-dated credential's start time is reached,
240 * the credential must be validated.  See \ref kim_credential_validate for more information.
241 *
242 * \li #kim_ccache_get_expiration_time()
243 * returns when the credential's in a ccache will expire.
244 * Credentials are time limited by the lifetime of the credential.  While you can
245 * request a credential of any lifetime, the KDC limits the credential lifetime
246 * to a administrator-defined maximum.  Typically credential lifetime range from 10
247 * to 21 hours.
248 *
249 * \li #kim_ccache_get_renewal_expiration_time()
250 * returns when the credential's in a ccache will no longer be renewable.
251 * Valid credentials may be renewed up until their renewal expiration time.
252 * Renewing credentials acquires a fresh set of credentials with a full lifetime
253 * without resending secrets to the KDC (such as a password).  If credentials are
254 * not renewable, this function will return an error.
255 *
256 * \li #kim_ccache_get_options()
257 * returns a kim_options object with the credential options of the credentials
258 * in the ccache.  This function is intended to be used when adding
259 * an identity with existing credentials to the favorite identities list.
260 * By passing in the options returned by this call, future requests for the
261 * favorite identity will use the same credential options.
262 *
263 * See \ref kim_ccache_reference and \ref kim_ccache_iterator_reference for
264 * information on specific APIs.
265 */
266
267
268/*!
269 * \defgroup kim_ccache_iterator_reference KIM CCache Iterator Reference Documentation
270 * @{
271 */
272
273/*!
274 * \param out_ccache_iterator on exit, a ccache iterator object for the cache collection.
275 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
276 * \brief Get a ccache iterator to enumerate ccaches in the cache collection.
277 */
278kim_error kim_ccache_iterator_create (kim_ccache_iterator *out_ccache_iterator);
279
280/*!
281 * \param in_ccache_iterator a ccache iterator object.
282 * \param out_ccache         on exit, the next ccache in the cache collection. If there are
283 *                           no more ccaches in the cache collection this argument will be
284 *                           set to NULL.
285 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
286 * \brief Get the next ccache in the cache collection.
287 */
288kim_error kim_ccache_iterator_next (kim_ccache_iterator  in_ccache_iterator,
289                                      kim_ccache          *out_ccache);
290
291/*!
292 * \param io_ccache_iterator a ccache iterator object to be freed.  Set to NULL on exit.
293 * \brief Free memory associated with a ccache iterator.
294 */
295void kim_ccache_iterator_free (kim_ccache_iterator *io_ccache_iterator);
296
297/*!@}*/
298
299/*!
300 * \defgroup kim_ccache_reference KIM CCache Reference Documentation
301 * @{
302 */
303
304/*!
305 * \param out_ccache          on exit, a new cache object for a ccache containing a newly acquired
306 *      		      initial credential.  Must be freed with kim_ccache_free().
307 * \param in_client_identity  a client identity to obtain a credential for.   Specify KIM_IDENTITY_ANY to
308 *                            allow the user to choose.
309 * \param in_options          options to control credential acquisition.
310 * \note #kim_ccache_create_new() may
311 * present a GUI or command line prompt to obtain information from the user.
312 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
313 * \brief Acquire a new initial credential and store it in a ccache.
314 */
315kim_error kim_ccache_create_new (kim_ccache          *out_ccache,
316                                 kim_identity         in_client_identity,
317                                 kim_options          in_options);
318
319/*!
320 * \param out_ccache          on exit, a new cache object for a ccache containing a newly acquired
321 *      		      initial credential.  Must be freed with kim_ccache_free().
322 * \param in_client_identity  a client identity to obtain a credential for.   Specify KIM_IDENTITY_ANY to
323 *                            allow the user to choose.
324 * \param in_options          options to control credential acquisition.
325 * \param in_password         a password to be used while obtaining credentials.
326 * \note #kim_ccache_create_new_with_password() exists to support
327 * legacy password-based Kerberos environments.  You should not use this
328 * function unless you know that it will only be used in environments using passwords.
329 * This function may also present a GUI or command line prompt to obtain
330 * additional information needed to obtain credentials (eg: SecurID pin).
331 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
332 * \brief Acquire a new initial credential and store it in a ccache
333 * using the provided password..
334 */
335kim_error kim_ccache_create_new_with_password (kim_ccache   *out_ccache,
336                                               kim_identity  in_client_identity,
337                                               kim_options   in_options,
338                                               kim_string    in_password);
339
340/*!
341 * \param out_ccache          on exit, a ccache object for a ccache containing a newly acquired
342 *                            initial credential. Must be freed with kim_ccache_free().
343 * \param in_client_identity  a client identity to obtain a credential for.
344 * \param in_options          options to control credential acquisition (if a credential is acquired).
345 * \note #kim_ccache_create_new_if_needed() may
346 * present a GUI or command line prompt to obtain information from the user.
347 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
348 * \brief Find a ccache containing a valid initial credential in the cache collection, or if
349 *        unavailable, acquire and store a new initial credential.
350 */
351kim_error kim_ccache_create_new_if_needed (kim_ccache   *out_ccache,
352                                           kim_identity  in_client_identity,
353                                           kim_options   in_options);
354
355/*!
356 * \param out_ccache          on exit, a ccache object for a ccache containing a newly acquired
357 *                            initial credential. Must be freed with kim_ccache_free().
358 * \param in_client_identity  a client identity to obtain a credential for.
359 * \param in_options          options to control credential acquisition (if a credential is acquired).
360 * \param in_password         a password to be used while obtaining credentials.
361 * \note #kim_ccache_create_new_if_needed_with_password() exists to support
362 * legacy password-based Kerberos environments.  You should not use this
363 * function unless you know that it will only be used in environments using passwords.
364 * This function may also present a GUI or command line prompt to obtain
365 * additional information needed to obtain credentials (eg: SecurID pin).
366 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
367 * \brief Find a ccache containing a valid initial credential in the cache collection, or if
368 *        unavailable, acquire and store a new initial credential using the provided password.
369 */
370kim_error kim_ccache_create_new_if_needed_with_password (kim_ccache   *out_ccache,
371                                                         kim_identity  in_client_identity,
372                                                         kim_options   in_options,
373                                                         kim_string    in_password);
374
375/*!
376 * \param out_ccache          on exit, a ccache object for a ccache containing a TGT
377 *                            credential. Must be freed with kim_ccache_free().
378 * \param in_client_identity  a client identity to find a ccache for.  If
379 *                            \a in_client_identity is #KIM_IDENTITY_ANY, this
380 *                            function returns the default ccache
381 *                            (ie: is equivalent to #kim_ccache_create_from_default()).
382 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
383 * \brief Find a ccache for a client identity in the cache collection.
384 */
385kim_error kim_ccache_create_from_client_identity (kim_ccache   *out_ccache,
386                                                  kim_identity  in_client_identity);
387
388/*!
389 * \param out_ccache      on exit, a new ccache object containing an initial credential
390 *      		  for the client identity \a in_identity obtained using in_keytab.
391 *      		  Must be freed with kim_ccache_free().
392 * \param in_identity     a client identity to obtain a credential for.  Specify NULL for
393 *      		  the first client identity in the keytab.
394 * \param in_options      options to control credential acquisition.
395 * \param in_keytab       a path to a keytab.  Specify NULL for the default keytab location.
396 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
397 * \brief Acquire a new initial credential from a keytab and store it in a ccache.
398 */
399kim_error kim_ccache_create_from_keytab (kim_ccache    *out_ccache,
400                                         kim_identity   in_identity,
401                                         kim_options    in_options,
402                                         kim_string     in_keytab);
403
404/*!
405 * \param out_ccache on exit, a ccache object for the default ccache.
406 *                   Must be freed with kim_ccache_free().
407 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
408 * \brief Get the default ccache.
409 */
410kim_error kim_ccache_create_from_default (kim_ccache *out_ccache);
411
412/*!
413 * \param out_ccache      on exit, a ccache object for the ccache identified by
414 *                        \a in_display_name.  Must be freed with kim_ccache_free().
415 * \param in_display_name a ccache display name string (ie: "TYPE:NAME").
416 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
417 * \note This API is used to obtain a kim_ccache for a ccache name entered by the user.
418 * \brief Get a ccache for a ccache display name.
419 */
420kim_error kim_ccache_create_from_display_name (kim_ccache  *out_ccache,
421                                               kim_string   in_display_name);
422
423/*!
424 * \param out_ccache  on exit, a ccache object for the ccache identified by
425 *                    \a in_type and \a in_name.  Must be freed with kim_ccache_free().
426 * \param in_type     a ccache type string.
427 * \param in_name     a ccache name string.
428 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
429 * \note This API is provided for backwards compatibilty with applications which are not
430 *       KIM-aware and should be avoided whenever possible.
431 * \brief Get a ccache for a ccache type and name.
432 */
433kim_error kim_ccache_create_from_type_and_name (kim_ccache  *out_ccache,
434                                                kim_string   in_type,
435                                                kim_string   in_name);
436
437/*!
438 * \param out_ccache      on exit, a new ccache object which is a copy of in_krb5_ccache.
439 *      		  Must be freed with kim_ccache_free().
440 * \param in_krb5_context the krb5 context used to create \a in_krb5_ccache.
441 * \param in_krb5_ccache  a krb5 ccache object.
442 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
443 * \brief Get a ccache for a krb5 ccache.
444 */
445kim_error kim_ccache_create_from_krb5_ccache (kim_ccache  *out_ccache,
446                                              krb5_context in_krb5_context,
447                                              krb5_ccache  in_krb5_ccache);
448
449/*!
450 * \param out_ccache on exit, the new ccache object which is a copy of in_ccache.
451 *      	     Must be freed with kim_ccache_free().
452 * \param in_ccache  a ccache object.
453 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
454 * \brief Copy a ccache.
455 */
456kim_error kim_ccache_copy (kim_ccache  *out_ccache,
457                           kim_ccache   in_ccache);
458
459/*!
460 * \param in_ccache             a ccache object.
461 * \param in_compare_to_ccache  a ccache object.
462 * \param out_comparison        on exit, a comparison of \a in_ccache and
463 *                              \a in_compare_to_ccache which determines whether
464 *                              or not the two ccache objects refer to the same ccache.
465 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
466 * \brief Compare ccache objects.
467 */
468kim_error kim_ccache_compare (kim_ccache      in_ccache,
469                              kim_ccache      in_compare_to_ccache,
470                              kim_comparison *out_comparison);
471
472/*!
473 * \param in_ccache        a ccache object.
474 * \param in_krb5_context  a krb5 context which will be used to create out_krb5_ccache.
475 * \param out_krb5_ccache  on exit, a new krb5 ccache object which is a copy of in_ccache.
476 *      		   Must be freed with krb5_cc_close() or krb5_cc_destroy().
477 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
478 * \brief Get a krb5 ccache for a ccache.
479 */
480kim_error kim_ccache_get_krb5_ccache (kim_ccache  in_ccache,
481                                      krb5_context  in_krb5_context,
482                                      krb5_ccache  *out_krb5_ccache);
483
484/*!
485 * \param in_ccache  a ccache object.
486 * \param out_name   on exit, the name string of \a in_ccache.
487 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
488 * \brief Get the name of a ccache.
489 */
490kim_error kim_ccache_get_name (kim_ccache  in_ccache,
491                               kim_string *out_name);
492
493/*!
494 * \param in_ccache  a ccache object.
495 * \param out_type   on exit, the type string of \a in_ccache.
496 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
497 * \brief Get the type of a ccache.
498 */
499kim_error kim_ccache_get_type (kim_ccache  in_ccache,
500                               kim_string *out_type);
501
502/*!
503 * \param in_ccache        a ccache object.
504 * \param out_display_name on exit, the type and name of \a in_ccache in a format appropriate for
505 *                         display to the user in command line programs.  (ie: "<type>:<name>")
506 *      		   Must be freed with kim_string_free().
507 *                         Note: this string can also be passed to krb5_cc_resolve().
508 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
509 * \brief Get the type and name for a ccache in display format.
510 */
511kim_error kim_ccache_get_display_name (kim_ccache  in_ccache,
512                                       kim_string *out_display_name);
513
514/*!
515 * \param in_ccache            a ccache object.
516 * \param out_client_identity  on exit, an identity object containing the client identity of
517 *      		       \a in_ccache. Must be freed with kim_identity_free().
518 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
519 * \brief Get the client identity for a ccache.
520 */
521kim_error kim_ccache_get_client_identity (kim_ccache    in_ccache,
522                                          kim_identity *out_client_identity);
523
524/*!
525 * \param in_ccache       a ccache object.
526 * \param out_credential  on exit, the first valid credential in \a in_ccache.
527 *      		  Must be freed with kim_credential_free().  Set to NULL
528 *                        if you only want return value, not the actual credential.
529 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
530 * \brief Get the first valid credential in a ccache.
531 * \note This function prefers valid TGT credentials.  If there are only non-valid TGTs
532 *       in the ccache, it will always return an error.  However, if there are no
533 *       TGTs at all, it will return the first valid non-TGT credential. If you only want
534 *       TGTs, use kim_credential_is_tgt() to verify that \a out_credential is a tgt.
535 */
536kim_error kim_ccache_get_valid_credential (kim_ccache      in_ccache,
537                                           kim_credential *out_credential);
538
539/*!
540 * \param in_ccache     a ccache object.
541 * \param out_state     on exit, the state of the credentials in \a in_ccache.
542 *                      See #kim_credential_state_enum for the possible values
543 *                      of \a out_state.
544 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
545 * \brief Check the state of the credentials in a ccache (valid, expired, postdated, etc).
546 * \note This function prefers TGT credentials.  If there are any TGTs in the
547 *       ccache, it will always return their state.  However, if there are no
548 *       TGTs at all, it will return the state of the first non-TGT credential.
549 */
550kim_error kim_ccache_get_state (kim_ccache            in_ccache,
551                                kim_credential_state *out_state);
552
553/*!
554 * \param in_ccache      a ccache object.
555 * \param out_start_time on exit, the time when the credentials in \a in_ccache
556 *                       become valid.  May be in the past or future.
557 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
558 * \brief Get the time when the credentials in the ccache become valid.
559 */
560kim_error kim_ccache_get_start_time (kim_ccache  in_ccache,
561                                     kim_time   *out_start_time);
562
563/*!
564 * \param in_ccache           a ccache object.
565 * \param out_expiration_time on exit, the time when the credentials in
566 *                            \a in_ccache will expire.  May be in the past or future.
567 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
568 * \brief Get the time when the credentials in the ccache will expire.
569 */
570kim_error kim_ccache_get_expiration_time (kim_ccache  in_ccache,
571                                          kim_time   *out_expiration_time);
572
573/*!
574 * \param in_ccache                   a ccache object.
575 * \param out_renewal_expiration_time on exit, the time when the credentials in \a in_ccache
576 *                                    will no longer be renewable. May be in the past or future.
577 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
578 * \brief Get the time when the credentials in the ccache will no longer be renewable.
579 */
580kim_error kim_ccache_get_renewal_expiration_time (kim_ccache  in_ccache,
581                                                  kim_time   *out_renewal_expiration_time);
582
583/*!
584 * \param in_ccache      a ccache object.
585 * \param out_options    on exit, an options object reflecting the ticket
586 *                       options of the credentials in \a in_ccache.
587 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
588 * \brief Get a kim_options object based on a ccache's credential attributes.
589 */
590kim_error kim_ccache_get_options (kim_ccache   in_ccache,
591                                  kim_options *out_options);
592
593/*!
594 * \param io_ccache a ccache object which will be set to the default ccache.
595 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
596 * \note This API is provided for backwards compatibilty with applications which are not
597 *       KIM-aware and should be avoided whenever possible.
598 * \brief Set a ccache to the default ccache.
599 */
600kim_error kim_ccache_set_default (kim_ccache io_ccache);
601
602/*!
603 * \param in_ccache              a ccache object containing the TGT credential to be verified.
604 * \param in_service_identity    a service identity to look for in the keytab.  Specify
605 *                               KIM_IDENTITY_ANY to use the default service identity
606 *                               (usually host/<host's FQDN>@<host's local realm>).
607 * \param in_keytab              a path to a keytab.  Specify NULL for the default keytab location.
608 * \param in_fail_if_no_service_key whether or not the absence of a key for \a in_service_identity
609 *                                  in the host's keytab will cause a failure.
610 * \note specifying FALSE for \a in_fail_if_no_service_key may expose the calling program to
611 * the Zanarotti attack if the host has no keytab installed.
612 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
613 * \brief Verify the TGT in a ccache.
614 */
615kim_error kim_ccache_verify (kim_ccache   in_ccache,
616                             kim_identity in_service_identity,
617                             kim_string   in_keytab,
618                             kim_boolean  in_fail_if_no_service_key);
619
620/*!
621 * \param in_ccache  a ccache object containing a TGT to be renewed.
622 * \param in_options initial credential options to be used if a new credential is obtained.
623 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
624 * \brief Renew the TGT in a ccache.
625 */
626kim_error kim_ccache_renew (kim_ccache  in_ccache,
627                            kim_options in_options);
628
629/*!
630 * \param in_ccache  a ccache object containing a TGT to be validated.
631 * \param in_options initial credential options.
632 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
633 * \brief Validate the TGT in a ccache.
634 */
635kim_error kim_ccache_validate (kim_ccache  in_ccache,
636                               kim_options in_options);
637
638/*!
639 * \param io_ccache  a ccache object to be destroyed.  Set to NULL on exit.
640 * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
641 * \brief Remove a ccache from the cache collection.
642 * \note Frees memory associated with the ccache.  Do not call kim_ccache_free()
643 *       after calling this function.
644 */
645kim_error kim_ccache_destroy (kim_ccache *io_ccache);
646
647/*!
648 * \param io_ccache a ccache object to be freed.  Set to NULL on exit.
649 * \brief Free memory associated with a ccache.
650 */
651void kim_ccache_free (kim_ccache *io_ccache);
652
653/*!@}*/
654
655#ifdef __cplusplus
656}
657#endif
658
659#endif /* KIM_CCACHE_H */
660