2
* Copyright 2005-2006 Massachusetts Institute of Technology.
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.
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.
32
#include <kim/kim_types.h>
35
* \page kim_ccache_overview KIM CCache Overview
37
* \section kim_ccache_introduction Introduction
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.
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.
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.
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.
66
* \section kim_credential_cache_collection Acquiring a CCache from the Cache Collection
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().
76
* \note #kim_ccache_iterator_next() returns ccache objects which
77
* must be freed with #kim_ccache_free() to avoid leaking memory.
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().
85
* \section kim_ccache_acquire_default Acquiring Credentials from the Default CCache
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.
96
* \section kim_ccache_acquire_new Acquiring New Credentials in a CCache
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.
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().
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.
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
136
* \section kim_ccache_validate Validating Credentials in a CCache
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.
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.
150
* \section kim_ccache_renew Renewing Credentials in a CCache
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
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.
162
* \section kim_ccache_verify Verifying Credentials in a CCache
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.
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.
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().
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).
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.
208
* \section kim_ccache_properties Examining CCache Properties
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.
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.
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().
223
* \li #kim_ccache_get_client_identity()
224
* returns the ccache's client identity.
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.
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.
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
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.
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.
263
* See \ref kim_ccache_reference and \ref kim_ccache_iterator_reference for
264
* information on specific APIs.
269
* \defgroup kim_ccache_iterator_reference KIM CCache Iterator Reference Documentation
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.
278
kim_error kim_ccache_iterator_create (kim_ccache_iterator *out_ccache_iterator);
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
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.
288
kim_error kim_ccache_iterator_next (kim_ccache_iterator in_ccache_iterator,
289
kim_ccache *out_ccache);
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.
295
void kim_ccache_iterator_free (kim_ccache_iterator *io_ccache_iterator);
300
* \defgroup kim_ccache_reference KIM CCache Reference Documentation
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.
315
kim_error kim_ccache_create_new (kim_ccache *out_ccache,
316
kim_identity in_client_identity,
317
kim_options in_options);
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..
335
kim_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);
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.
351
kim_error kim_ccache_create_new_if_needed (kim_ccache *out_ccache,
352
kim_identity in_client_identity,
353
kim_options in_options);
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.
370
kim_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);
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.
385
kim_error kim_ccache_create_from_client_identity (kim_ccache *out_ccache,
386
kim_identity in_client_identity);
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.
399
kim_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);
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.
410
kim_error kim_ccache_create_from_default (kim_ccache *out_ccache);
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.
420
kim_error kim_ccache_create_from_display_name (kim_ccache *out_ccache,
421
kim_string in_display_name);
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.
433
kim_error kim_ccache_create_from_type_and_name (kim_ccache *out_ccache,
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.
445
kim_error kim_ccache_create_from_krb5_ccache (kim_ccache *out_ccache,
446
krb5_context in_krb5_context,
447
krb5_ccache in_krb5_ccache);
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.
456
kim_error kim_ccache_copy (kim_ccache *out_ccache,
457
kim_ccache in_ccache);
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.
468
kim_error kim_ccache_compare (kim_ccache in_ccache,
469
kim_ccache in_compare_to_ccache,
470
kim_comparison *out_comparison);
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.
480
kim_error kim_ccache_get_krb5_ccache (kim_ccache in_ccache,
481
krb5_context in_krb5_context,
482
krb5_ccache *out_krb5_ccache);
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.
490
kim_error kim_ccache_get_name (kim_ccache in_ccache,
491
kim_string *out_name);
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.
499
kim_error kim_ccache_get_type (kim_ccache in_ccache,
500
kim_string *out_type);
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.
511
kim_error kim_ccache_get_display_name (kim_ccache in_ccache,
512
kim_string *out_display_name);
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.
521
kim_error kim_ccache_get_client_identity (kim_ccache in_ccache,
522
kim_identity *out_client_identity);
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.
536
kim_error kim_ccache_get_valid_credential (kim_ccache in_ccache,
537
kim_credential *out_credential);
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
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.
550
kim_error kim_ccache_get_state (kim_ccache in_ccache,
551
kim_credential_state *out_state);
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.
560
kim_error kim_ccache_get_start_time (kim_ccache in_ccache,
561
kim_time *out_start_time);
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.
570
kim_error kim_ccache_get_expiration_time (kim_ccache in_ccache,
571
kim_time *out_expiration_time);
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.
580
kim_error kim_ccache_get_renewal_expiration_time (kim_ccache in_ccache,
581
kim_time *out_renewal_expiration_time);
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.
590
kim_error kim_ccache_get_options (kim_ccache in_ccache,
591
kim_options *out_options);
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.
600
kim_error kim_ccache_set_default (kim_ccache io_ccache);
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.
615
kim_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);
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.
626
kim_error kim_ccache_renew (kim_ccache in_ccache,
627
kim_options in_options);
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.
635
kim_error kim_ccache_validate (kim_ccache in_ccache,
636
kim_options in_options);
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.
645
kim_error kim_ccache_destroy (kim_ccache *io_ccache);
648
* \param io_ccache a ccache object to be freed. Set to NULL on exit.
649
* \brief Free memory associated with a ccache.
651
void kim_ccache_free (kim_ccache *io_ccache);
659
#endif /* KIM_CCACHE_H */
added
removed
src/include/kim/kim_ccache.h
