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