src/include/kim/kim_credential.h

   1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
   2 /*
   3  * Copyright 2005-2006 Massachusetts Institute of Technology.
   4  * All Rights Reserved.
   5  *
   6  * Export of this software from the United States of America may
   7  * require a specific license from the United States Government.
   8  * It is the responsibility of any person or organization contemplating
   9  * export to obtain such a license before exporting.
  10  *
  11  * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
  12  * distribute this software and its documentation for any purpose and
  13  * without fee is hereby granted, provided that the above copyright
  14  * notice appear in all copies and that both that copyright notice and
  15  * this permission notice appear in supporting documentation, and that
  16  * the name of M.I.T. not be used in advertising or publicity pertaining
  17  * to distribution of the software without specific, written prior
  18  * permission.  Furthermore if you modify this software you must label
  19  * your software as modified software and not distribute it in such a
  20  * fashion that it might be confused with the original M.I.T. software.
  21  * M.I.T. makes no representations about the suitability of
  22  * this software for any purpose.  It is provided "as is" without express
  23  * or implied warranty.
  24  */
  25
  26 #ifndef KIM_CREDENTIAL_H
  27 #define KIM_CREDENTIAL_H
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 #include <kim/kim_types.h>
  34 #include <krb5.h>
  35
  36 /*!
  37  * \addtogroup kim_types_reference
  38  * @{
  39  */
  40
  41 /*!
  42  * Possible credential states.  Credentials may be:
  43  * \li valid - The credential can be used.
  44  * \li expired - The credential's lifetime has been exceeded.
  45  * \li not_yet_valid - The credential is post dated and the time when
  46  *                     it becomes valid has not yet been reached.
  47  * \li needs_validation - The credential is post-dated and although
  48  *                        the time when it becomes valid has been reached
  49  *                        it has not yet been validated.
  50  * \li address_mismatch - The credential contains IP address(es) which do
  51  *                        not match the host's local address(es).
  52  */
  53 enum kim_credential_state_enum {
  54     kim_credentials_state_valid            = 0,
  55     kim_credentials_state_expired          = 1,
  56     kim_credentials_state_not_yet_valid    = 2,
  57     kim_credentials_state_needs_validation = 3,
  58     kim_credentials_state_address_mismatch = 4
  59 };
  60
  61 /*!
  62  * The state of a credential.  See #kim_credential_state_enum for
  63  * possible values.
  64  */
  65 typedef int kim_credential_state;
  66
  67 /*! @} */
  68
  69 /*!
  70  * \page kim_credential_overview KIM Credential Overview
  71  *
  72  * \section kim_credential_introduction Introduction
  73  *
  74  * A Kerberos credential (also called a "Kerberos ticket") is a time-limited
  75  * token issued by a KDC which authenticates the entity named by the credential's
  76  * client identity to the service named by the credential's service identity.
  77  *
  78  * The kim_credential object contains a single Kerberos credential.  KIM credentials
  79  * objects are always copies of credentials, not references to credentials
  80  * stored in the cache collection.  Modifying credential objects in the ccache
  81  * collection will not change any existing KIM credential objects.
  82  *
  83  * KIM credential APIs are intended for applications and system
  84  * tools which manage credentials for the user.  They are not a substitute for
  85  * krb5 and GSSAPI functions which obtain service credentials for the purpose
  86  * of authenticating a client to an application server.
  87  *
  88  * \note Many of the APIs listed below have equivalent functions which
  89  * operate on ccaches.  In most cases applications will want to use the
  90  * ccache versions of these APIs since they automatically store any
  91  * newly created credentials.  See \ref kim_ccache_overview for more
  92  * information.
  93  *
  94  *
  95  * \section kim_credential_acquire_new Acquiring New Credentials
  96  *
  97  * KIM provides the #kim_credential_create_new() API for acquiring new
  98  * credentials.  Credentials can either be obtained for a specific
  99  * client identity or by specifying #KIM_IDENTITY_ANY to allow
 100  * the user to choose.  Typically callers of this API obtain the client
 101  * identity using #kim_selection_hints_get_identity().  Depending on the
 102  * kim_options specified, #kim_credential_create_new() may present a
 103  * GUI or command line prompt to obtain information from the user.
 104  *
 105  * For legacy password-based Kerberos environments KIM also provides
 106  * #kim_credential_create_new_with_password().  You should not use this
 107  * function unless you know that it will only be used in environments using
 108  * passwords.  Otherwise users without passwords may be prompted for them.
 109  *
 110  * KIM provides the #kim_credential_create_from_keytab() to create credentials
 111  * using a keytab. A keytab is an on-disk copy of a client identity's secret
 112  * key.  Typically sites use keytabs for client identities that identify a
 113  * machine or service and protect the keytab with disk permissions.  Because
 114  * a keytab is sufficient to obtain credentials, keytabs will normally only
 115  * be readable by root, Administrator or some other privileged account.
 116  * Typically applications use credentials obtained from keytabs to obtain
 117  * credentials for batch processes.  These keytabs and credentials are usually
 118  * for a special identity used for the batch process rather than a user
 119  * identity.
 120  *
 121  *
 122  * \section kim_credential_validate Validating Credentials
 123  *
 124  * A credential with a start time in the future (ie: after the issue date)
 125  * is called a post-dated credential.  Because the KDC administrator may
 126  * wish to disable a identity, once the start time is reached, all post-dated
 127  * credentials must be validated before they can be used.  Otherwise an
 128  * attacker using a compromised account could acquire lots of post-dated
 129  * credentials to circumvent the acccount being disabled.
 130  *
 131  * KIM provides the #kim_credential_validate() API to validate a credential.
 132  * Note that this API replaces the credential object with a new validated
 133  * credential object.  If you wish to store the new credential in the
 134  * ccache collection you must either call #kim_credential_store() on the
 135  * validated credential or use #kim_ccache_validate() instead.
 136  *
 137  *
 138  * \section kim_credential_renew Renewing Credentials
 139  *
 140  * A renewable credential can be used to obtain a new identical credential
 141  * without resending secret information (such as a password) to the KDC.
 142  * A credential may only be renewed during its renewal lifetime and while
 143  * valid.
 144  *
 145  * KIM provides the #kim_credential_renew() API to renew a credential.
 146  * Note that this API replaces the credential object with a new renewed
 147  * credential object.  If you wish to store the new credential in the
 148  * ccache collection you must either call #kim_credential_store() on the
 149  * renewed credential or use #kim_ccache_renew() instead.
 150  *
 151  *
 152  * \section kim_credential_storing Storing Credentials in the Cache Collection
 153  *
 154  * KIM credential objects may be stored in the ccache collection using
 155  * #kim_credential_store().  This function runs any KIM authentication
 156  * plugins on the credential and if the plugins return successfully, creates a
 157  * new ccache for the credential's client identity in the cache collection
 158  * and stores the credential in that ccache.  Any existing ccaches and credentials
 159  * for that client identity will be overwritten.   #kim_credential_store() may
 160  * optionally return a kim_ccache object for the new ccache if you need to perform
 161  * further operations on the new ccache.
 162  *
 163  * Most of the time if you plan to store the credentials you are manipulating, you
 164  * should use one of KIM ccache APIs.  These functions perform the same operations
 165  * except that they also call #kim_credential_store() any time the credential object
 166  * changes.  See \ref kim_ccache_overview for more information.
 167  *
 168  *
 169  * \section kim_credential_iterator Iterating over the Credentials in a CCache
 170  *
 171  * KIM provides a simple iterator API for iterating over the credentials
 172  * in a ccache.  First, call #kim_credential_iterator_create() to obtain
 173  * an iterator for a ccache.  Then loop calling #kim_credential_iterator_next()
 174  * until either you find the credential you are looking for or the API
 175  * returns a NULL credential, indicating that there are no more
 176  * credentials in the ccache.  When you are done with the iterator, call
 177  * #kim_credential_iterator_free().
 178  *
 179  * \note #kim_credential_iterator_next() returns credential objects which
 180  * must be freed with #kim_credential_free() to avoid leaking memory.
 181  *
 182  *
 183  * \section kim_credential_verify Verifying Credentials
 184  *
 185  * When a program acquires TGT credentials for the purpose of authenticating
 186  * itself to the machine it is running on, it is insufficient for the machine
 187  * to assume that the caller is authorized just because it got credentials.
 188  * Instead, the credentials must be verified using a key the local machine.
 189  * The reason this is necessary is because an attacker can trick the
 190  * machine into obtaining credentials from any KDC, including malicious ones
 191  * with the same realm name as the local machine's realm.  This exploit is
 192  * called the Zanarotti attack.
 193  *
 194  * In order to avoid the Zanarotti attack, the local machine must authenticate
 195  * the process in the same way an application server would authenticate a client.
 196  * Like an application server, the local machine must have its own identity in
 197  * its realm and a keytab for that identity on its local disk.    However,
 198  * rather than forcing system daemons to use the network-oriented calls in the
 199  * krb5 and GSS APIs, KIM provides the #kim_credential_verify() API to
 200  * verify credentials directly.
 201  *
 202  * The most common reason for using #kim_credential_verify() is user login.
 203  * If the local machine wants to use Kerberos to verify the username and password
 204  * provided by the user, it must call #kim_credential_verify() on the credentials
 205  * it obtains to make sure they are really from a KDC it trusts.  Another common
 206  * case is a server which is only using Kerberos internally.  For example an
 207  * LDAP or web server might use a username and password obtained over the network
 208  * to get Kerberos credentials.  In order to make sure they aren't being tricked
 209  * into talking to the wrong KDC, these servers must also call
 210  * #kim_credential_verify().
 211  *
 212  * The Zanarotti attack is only a concern if the act of accessing the machine
 213  * gives the process special access.  Thus a managed cluster machine with
 214  * Kerberos-authenticated networked home directories does not need to call
 215  * #kim_credential_verify().  Even though an attacker can log in as any user on
 216  * the cluster machine, the attacker can't actually access any of the user's data
 217  * or use any of their privileges because those are all authenticated via
 218  * Kerberized application servers (and thus require actually having credentials
 219  * for the real local realm).
 220  *
 221  * #kim_credential_verify() provides an option to
 222  * return success even if the machine's host key is not present.  This option
 223  * exists for sites which have a mix of different machines, some of which are
 224  * vulnerable to the Zanarotti attack and some are not.  If this option is used,
 225  * it is the responsiblity of the machine's maintainer to obtain a keytab
 226  * for their machine if it needs one.
 227  *
 228  *
 229  * \section kim_credential_properties Examining Credential Properties
 230  *
 231  * \li #kim_credential_get_client_identity()
 232  *     returns the credential's client identity.
 233  *
 234  * \li #kim_credential_get_service_identity()
 235  *     returns the credential's service identity.
 236  *
 237  * \li #kim_credential_is_tgt()
 238  *     returns whether the credential is a TGT (ie: "ticket-granting ticket").  TGTs are
 239  *     credentials for the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>".
 240  *     These credentials allow the entity named by the client identity to obtain
 241  *     additional service credentials without resending shared secrets (such as a password)
 242  *     to the KDC. Kerberos uses TGTs to provide single sign-on authentication.
 243  *
 244  * \li #kim_credential_get_state()
 245  *     returns a #kim_credential_state containing the state of the credential.
 246  *     Possible values are:
 247  *     * kim_credentials_state_valid
 248  *     * kim_credentials_state_expired
 249  *     * kim_credentials_state_not_yet_valid
 250  *     * kim_credentials_state_needs_validation
 251  *     * kim_credentials_state_address_mismatch
 252  *
 253  * \li #kim_credential_get_start_time()
 254  *     returns when the credential will become valid.
 255  *     Credentials may be "post-dated" which means that their lifetime starts sometime
 256  *     in the future.  Note that when a post-dated credential's start time is reached,
 257  *     the credential must be validated.  See \ref kim_credential_validate for more information.
 258  *
 259  * \li #kim_credential_get_expiration_time()
 260  *     returns when the credential will expire.
 261  *     Credentials are time limited by the lifetime of the credential.  While you can
 262  *     request a credential of any lifetime, the KDC limits the credential lifetime
 263  *     to a administrator-defined maximum.  Typically credential lifetime range from 10
 264  *     to 21 hours.
 265  *
 266  * \li #kim_credential_get_renewal_expiration_time()
 267  *     returns when the credential will no longer be renewable.
 268  *     Valid credentials may be renewed up until their renewal expiration time.
 269  *     Renewing credentials acquires a fresh set of credentials with a full lifetime
 270  *     without resending secrets to the KDC (such as a password).  If credentials are
 271  *     not renewable, this function will return a renewal expiration time of 0.
 272  *
 273  * \li #kim_credential_get_options()
 274  *     returns a kim_options object with the credential options of the
 275  *     credential.  This function is intended to be used when adding
 276  *     an identity with existing credentials to the favorite identities list.
 277  *     By passing in the options returned by this call, future requests for the
 278  *     favorite identity will use the same credential options.
 279  *
 280  *
 281  * See \ref kim_credential_reference and \ref kim_credential_iterator_reference for
 282  * information on specific APIs.
 283  */
 284
 285 /*!
 286  * \defgroup kim_credential_iterator_reference KIM Credential Iterator Reference Documentation
 287  * @{
 288  */
 289
 290 /*!
 291  * \param out_credential_iterator on exit, a credential iterator object for \a in_ccache.
 292  *                                Must be freed with kim_credential_iterator_free().
 293  * \param in_ccache               a ccache object.
 294  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 295  * \brief Get a credential iterator to enumerate credentials in a ccache.
 296  */
 297
 298 kim_error kim_credential_iterator_create (kim_credential_iterator *out_credential_iterator,
 299                                           kim_ccache               in_ccache);
 300
 301 /*!
 302  * \param in_credential_iterator a credential iterator object.
 303  * \param out_credential         on exit, the next credential in the ccache iterated by
 304  *                               \a in_credential_iterator.   Must be freed with
 305  *                               kim_credential_free(). If there are no more credentials
 306  *                               this argument will be set to NULL.
 307  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 308  * \brief Get the next credential in a ccache.
 309  */
 310
 311 kim_error kim_credential_iterator_next (kim_credential_iterator  in_credential_iterator,
 312                                         kim_credential          *out_credential);
 313
 314 /*!
 315  * \param io_credential_iterator a credential iterator object to be freed.  Set to NULL on exit.
 316  * \brief Free memory associated with a credential iterator.
 317  */
 318 void kim_credential_iterator_free (kim_credential_iterator *io_credential_iterator);
 319
 320 /*!@}*/
 321
 322 /*!
 323  * \defgroup kim_credential_reference KIM Credential Reference Documentation
 324  * @{
 325  */
 326
 327 /*!
 328  * \param out_credential      on exit, a new credential object containing a newly acquired
 329  *                            initial credential.  Must be freed with kim_credential_free().
 330  * \param in_client_identity  a client identity to obtain a credential for.   Specify NULL to
 331  *                            allow the user to choose the identity
 332  * \param in_options          options to control credential acquisition.
 333  * \note #kim_credential_create_new() may
 334  * present a GUI or command line prompt to obtain information from the user.
 335  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 336  * \brief Acquire a new initial credential.
 337  * \sa kim_ccache_create_new
 338  */
 339 kim_error kim_credential_create_new (kim_credential *out_credential,
 340                                      kim_identity    in_client_identity,
 341                                      kim_options     in_options);
 342
 343 /*!
 344  * \param out_credential      on exit, a new credential object containing a newly acquired
 345  *                            initial credential.  Must be freed with kim_credential_free().
 346  * \param in_client_identity  a client identity to obtain a credential for.   Specify NULL to
 347  *                            allow the user to choose the identity
 348  * \param in_options          options to control credential acquisition.
 349  * \param in_password         a password to be used while obtaining the credential.
 350  * \note #kim_credential_create_new_with_password() exists to support
 351  * legacy password-based Kerberos environments.  You should not use this
 352  * function unless you know that it will only be used in environments using passwords.
 353  * This function may also present a GUI or command line prompt to obtain
 354  * additional information needed to obtain credentials (eg: SecurID pin).
 355  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 356  * \brief Acquire a new initial credential using the provided password.
 357  * \sa kim_ccache_create_new
 358  */
 359 kim_error kim_credential_create_new_with_password (kim_credential *out_credential,
 360                                                    kim_identity    in_client_identity,
 361                                                    kim_options     in_options,
 362                                                    kim_string      in_password);
 363
 364 /*!
 365  * \param out_credential  on exit, a new credential object containing an initial credential
 366  *                        for \a in_identity obtained using \a in_keytab.
 367  *                        Must be freed with kim_credential_free().
 368  * \param in_identity     a client identity to obtain a credential for.  Specify NULL for
 369  *                        the first identity in the keytab.
 370  * \param in_options      options to control credential acquisition.
 371  * \param in_keytab       a path to a keytab.  Specify NULL for the default keytab location.
 372  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 373  * \brief Acquire a new initial credential from a keytab.
 374  * \sa kim_ccache_create_from_keytab
 375  */
 376 kim_error kim_credential_create_from_keytab (kim_credential *out_credential,
 377                                              kim_identity    in_identity,
 378                                              kim_options     in_options,
 379                                              kim_string      in_keytab);
 380
 381 /*!
 382  * \param out_credential  on exit, a new credential object which is a copy of \a in_krb5_creds.
 383  *                        Must be freed with kim_credential_free().
 384  * \param in_krb5_context the krb5 context used to create \a in_krb5_creds.
 385  * \param in_krb5_creds   a krb5 credential object.
 386  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 387  * \brief Copy a credential from a krb5 credential object.
 388  */
 389 kim_error kim_credential_create_from_krb5_creds (kim_credential *out_credential,
 390                                                  krb5_context      in_krb5_context,
 391                                                  krb5_creds       *in_krb5_creds);
 392
 393 /*!
 394  * \param out_credential  on exit, a new credential object which is a copy of \a in_credential.
 395  *                        Must be freed with kim_credential_free().
 396  * \param in_credential   a credential object.
 397  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 398  * \brief Copy a credential object.
 399  */
 400 kim_error kim_credential_copy (kim_credential *out_credential,
 401                                kim_credential  in_credential);
 402
 403 /*!
 404  * \param in_credential    a credential object.
 405  * \param in_krb5_context  a krb5 context which will be used to create \a out_krb5_creds.
 406  * \param out_krb5_creds   on exit, a new krb5 creds object which is a copy of \a in_credential.
 407  *                         Must be freed with krb5_free_creds().
 408  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 409  * \brief Get a krb5 credentials object for a credential object.
 410  */
 411 kim_error kim_credential_get_krb5_creds (kim_credential   in_credential,
 412                                          krb5_context       in_krb5_context,
 413                                          krb5_creds       **out_krb5_creds);
 414
 415 /*!
 416  * \param in_credential        a credential object.
 417  * \param out_client_identity  on exit, an identity object containing the client identity of
 418  *                             \a in_credential. Must be freed with kim_identity_free().
 419  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 420  * \brief Get the client identity of a credential object.
 421  */
 422 kim_error kim_credential_get_client_identity (kim_credential  in_credential,
 423                                               kim_identity   *out_client_identity);
 424
 425 /*!
 426  * \param in_credential         a credential object.
 427  * \param out_service_identity  on exit, an identity object containing the service identity of
 428  *                              \a in_credential. Must be freed with kim_identity_free().
 429  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 430  * \brief Get the service identity of a credential object.
 431  */
 432 kim_error kim_credential_get_service_identity (kim_credential  in_credential,
 433                                                kim_identity   *out_service_identity);
 434
 435 /*!
 436  * \param in_credential a credential object.
 437  * \param out_is_tgt    on exit, whether or not the credential is a TGT.
 438  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 439  * \brief Check if a credential is a ticket granting ticket.
 440  */
 441 kim_error kim_credential_is_tgt (kim_credential  in_credential,
 442                                  kim_boolean     *out_is_tgt);
 443
 444 /*!
 445  * \param in_credential a credential object.
 446  * \param out_state     on exit, the state of the credential.  See #kim_credential_state_enum
 447  *                      for the possible values of \a out_state.
 448  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 449  * \brief Check the state of a credential (valid, expired, postdated, etc).
 450  */
 451 kim_error kim_credential_get_state (kim_credential        in_credential,
 452                                     kim_credential_state *out_state);
 453
 454 /*!
 455  * \param in_credential  a credential object.
 456  * \param out_start_time on exit, the time when \a in_credential becomes valid.
 457  *                       May be in the past or future.
 458  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 459  * \brief Get the time when the credentials become valid.
 460  * \sa kim_ccache_get_start_time
 461  */
 462 kim_error kim_credential_get_start_time (kim_credential  in_credential,
 463                                          kim_time       *out_start_time);
 464
 465 /*!
 466  * \param in_credential       a credential object.
 467  * \param out_expiration_time on exit, the time when \a in_credential will expire.
 468  *                            May be in the past or future.
 469  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 470  * \brief Get the time when the credentials will expire.
 471  * \sa kim_ccache_get_expiration_time
 472  */
 473 kim_error kim_credential_get_expiration_time (kim_credential  in_credential,
 474                                               kim_time       *out_expiration_time);
 475
 476 /*!
 477  * \param in_credential               a credential object.
 478  * \param out_renewal_expiration_time on exit, the time when \a in_credential will no longer
 479  *                                    be renewable. May be in the past or future.  If
 480  *                                    credentials are not renewable at all, returns 0.
 481  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 482  * \brief Get the time when the credentials will no longer be renewable.
 483  * \sa kim_ccache_get_renewal_expiration_time
 484  */
 485 kim_error kim_credential_get_renewal_expiration_time (kim_credential  in_credential,
 486                                                       kim_time       *out_renewal_expiration_time);
 487
 488 /*!
 489  * \param in_credential  a credential object.
 490  * \param out_options    on exit, an options object reflecting the ticket
 491  *                       options of \a in_credential.
 492  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 493  * \brief Get a kim_options object based on a credential's attributes.
 494  */
 495 kim_error kim_credential_get_options (kim_credential  in_credential,
 496                                       kim_options    *out_options);
 497
 498 /*!
 499  * \param in_credential       a credential object.
 500  * \param in_client_identity  a client identity.
 501  * \param out_ccache          on exit, a ccache object containing \a in_credential with the client
 502  *                            identity \a in_client_identity.  Must be freed with kim_ccache_free().
 503  *                            Specify NULL if you don't want this return value.
 504  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 505  * \brief Store a credential in a ccache in the cache collection.
 506  */
 507 kim_error kim_credential_store (kim_credential  in_credential,
 508                                 kim_identity    in_client_identity,
 509                                 kim_ccache     *out_ccache);
 510
 511 /*!
 512  * \param in_credential          a TGT credential to be verified.
 513  * \param in_service_identity    a service identity to look for in the keytab.  Specify
 514  *                               KIM_IDENTITY_ANY to use the default service identity
 515  *                               (usually host/<host's FQDN>@<host's local realm>).
 516  * \param in_keytab              a path to a keytab.  Specify NULL for the default keytab location.
 517  * \param in_fail_if_no_service_key whether or not the absence of a key for \a in_service_identity
 518  *                                  in the host's keytab will cause a failure.
 519  * \note specifying FALSE for \a in_fail_if_no_service_key may expose the calling program to
 520  * the Zanarotti attack if the host has no keytab installed.
 521  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 522  * \brief Verify a TGT credential.
 523  * \sa kim_ccache_verify
 524  */
 525 kim_error kim_credential_verify (kim_credential in_credential,
 526                                  kim_identity   in_service_identity,
 527                                  kim_string     in_keytab,
 528                                  kim_boolean    in_fail_if_no_service_key);
 529
 530 /*!
 531  * \param io_credential  a TGT credential to be renewed.  On exit, the old credential
 532  *                       object will be freed and \a io_credential will be replaced
 533  *                       with a new renewed credential.  The new credential must be freed
 534  *                       with kim_credential_free().
 535  * \param in_options     initial credential options.
 536  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 537  * \brief Renew a TGT credential.
 538  * \sa kim_ccache_renew
 539  */
 540 kim_error kim_credential_renew (kim_credential *io_credential,
 541                                 kim_options     in_options);
 542
 543 /*!
 544  * \param io_credential  a credential object to be validated. On exit, the old credential
 545  *                       object will be freed and \a io_credential will be replaced
 546  *                       with a new validated credential.  The new credential must be freed
 547  *                       with kim_credential_free().
 548  * \param in_options     initial credential options.
 549  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
 550  * \brief Validate a TGT credential.
 551  * \sa kim_ccache_validate
 552  */
 553 kim_error kim_credential_validate (kim_credential *io_credential,
 554                                    kim_options     in_options);
 555
 556 /*!
 557  * \param io_credential the credential object to be freed.  Set to NULL on exit.
 558  * \brief Free memory associated with a credential object.
 559  */
 560 void kim_credential_free (kim_credential *io_credential);
 561
 562 /*!@}*/
 563
 564
 565 #ifdef __cplusplus
 566 }
 567 #endif
 568
 569 #endif /* KIM_CREDENTIAL_H */