diff options
Diffstat (limited to 'src/include')
| -rw-r--r-- | src/include/kim/kim_credential.h | 1004 | ||||
| -rw-r--r-- | src/include/kim/kim_identity.h | 21 | ||||
| -rw-r--r-- | src/include/kim/kim_options.h | 147 | ||||
| -rw-r--r-- | src/include/kim/kim_ui_plugin.h | 55 |
4 files changed, 573 insertions, 654 deletions
diff --git a/src/include/kim/kim_credential.h b/src/include/kim/kim_credential.h index ed58a72ae..88ccc5dce 100644 --- a/src/include/kim/kim_credential.h +++ b/src/include/kim/kim_credential.h @@ -32,484 +32,532 @@ extern "C" { #include <kim/kim_types.h> #include <krb5.h> - /*! - * \addtogroup kim_types_reference - * @{ - */ - - /*! - * Possible credential states. Credentials may be: - * \li valid - The credential can be used. - * \li expired - The credential's lifetime has been exceeded. - * \li not_yet_valid - The credential is post dated and the time when - * it becomes valid has not yet been reached. - * \li needs_validation - The credential is post-dated and although - * the time when it becomes valid has been reached - * it has not yet been validated. - * \li address_mismatch - The credential contains IP address(es) which do - * not match the host's local address(es). - */ - enum kim_credential_state_enum { - kim_credentials_state_valid = 0, - kim_credentials_state_expired = 1, - kim_credentials_state_not_yet_valid = 2, - kim_credentials_state_needs_validation = 3, - kim_credentials_state_address_mismatch = 4 - }; - - /*! - * The state of a credential. See #kim_credential_state_enum for - * possible values. - */ - typedef int kim_credential_state; - - /*! @} */ - - /*! - * \page kim_credential_overview KIM Credential Overview - * - * \section kim_credential_introduction Introduction - * - * A Kerberos credential (also called a "Kerberos ticket") is a time-limited - * token issued by a KDC which authenticates the entity named by the credential's - * client identity to the service named by the credential's service identity. - * - * The kim_credential object contains a single Kerberos credential. KIM credentials - * objects are always copies of credentials, not references to credentials - * stored in the cache collection. Modifying credential objects in the ccache - * collection will not change any existing KIM credential objects. - * - * KIM credential APIs are intended for applications and system - * tools which manage credentials for the user. They are not a substitute for - * krb5 and GSSAPI functions which obtain service credentials for the purpose - * of authenticating a client to an application server. - * - * \note Many of the APIs listed below have equivalent functions which - * operate on ccaches. In most cases applications will want to use the - * ccache versions of these APIs since they automatically store any - * newly created credentials. See \ref kim_ccache_overview for more - * information. - * - * - * \section kim_credential_acquire_new Acquiring New Credentials - * - * KIM provides the #kim_credential_create_new() API for acquiring new - * credentials. Credentials can either be obtained for a specific - * client identity or by specifying #KIM_IDENTITY_ANY to allow - * the user to choose. Typically callers of this API obtain the client - * identity using #kim_selection_hints_get_identity(). Depending on the - * kim_options specified, #kim_credential_create_new() may present a - * GUI or command line prompt to obtain information from the user. - * - * KIM provides the #kim_credential_create_from_keytab() to create credentials - * using a keytab. A keytab is an on-disk copy of a client identity's secret - * key. Typically sites use keytabs for client identities that identify a - * machine or service and protect the keytab with disk permissions. Because - * a keytab is sufficient to obtain credentials, keytabs will normally only - * be readable by root, Administrator or some other privileged account. - * Typically applications use credentials obtained from keytabs to obtain - * credentials for batch processes. These keytabs and credentials are usually - * for a special identity used for the batch process rather than a user - * identity. - * - * - * \section kim_credential_validate Validating Credentials - * - * A credential with a start time in the future (ie: after the issue date) - * is called a post-dated credential. Because the KDC administrator may - * wish to disable a identity, once the start time is reached, all post-dated - * credentials must be validated before they can be used. Otherwise an - * attacker using a compromised account could acquire lots of post-dated - * credentials to circumvent the acccount being disabled. - * - * KIM provides the #kim_credential_validate() API to validate a credential. - * Note that this API replaces the credential object with a new validated - * credential object. If you wish to store the new credential in the - * ccache collection you must either call #kim_credential_store() on the - * validated credential or use #kim_ccache_validate() instead. - * - * - * \section kim_credential_renew Renewing Credentials - * - * A renewable credential can be used to obtain a new identical credential - * without resending secret information (such as a password) to the KDC. - * A credential may only be renewed during its renewal lifetime and while - * valid. - * - * KIM provides the #kim_credential_renew() API to renew a credential. - * Note that this API replaces the credential object with a new renewed - * credential object. If you wish to store the new credential in the - * ccache collection you must either call #kim_credential_store() on the - * renewed credential or use #kim_ccache_renew() instead. - * - * - * \section kim_credential_storing Storing Credentials in the Cache Collection - * - * KIM credential objects may be stored in the ccache collection using - * #kim_credential_store(). This function runs any KIM authentication - * plugins on the credential and if the plugins return successfully, creates a - * new ccache for the credential's client identity in the cache collection - * and stores the credential in that ccache. Any existing ccaches and credentials - * for that client identity will be overwritten. #kim_credential_store() may - * optionally return a kim_ccache object for the new ccache if you need to perform - * further operations on the new ccache. - * - * Most of the time if you plan to store the credentials you are manipulating, you - * should use one of KIM ccache APIs. These functions perform the same operations - * except that they also call #kim_credential_store() any time the credential object - * changes. See \ref kim_ccache_overview for more information. - * - * - * \section kim_credential_iterator Iterating over the Credentials in a CCache - * - * KIM provides a simple iterator API for iterating over the credentials - * in a ccache. First, call #kim_credential_iterator_create() to obtain - * an iterator for a ccache. Then loop calling #kim_credential_iterator_next() - * until either you find the credential you are looking for or the API - * returns a NULL credential, indicating that there are no more - * credentials in the ccache. When you are done with the iterator, call - * #kim_credential_iterator_free(). - * - * \note #kim_credential_iterator_next() returns credential objects which - * must be freed with #kim_credential_free() to avoid leaking memory. - * - * - * \section kim_credential_verify Verifying Credentials - * - * When a program acquires TGT credentials for the purpose of authenticating - * itself to the machine it is running on, it is insufficient for the machine - * to assume that the caller is authorized just because it got credentials. - * Instead, the credentials must be verified using a key the local machine. - * The reason this is necessary is because an attacker can trick the - * machine into obtaining credentials from any KDC, including malicious ones - * with the same realm name as the local machine's realm. This exploit is - * called the Zanarotti attack. - * - * In order to avoid the Zanarotti attack, the local machine must authenticate - * the process in the same way an application server would authenticate a client. - * Like an application server, the local machine must have its own identity in - * its realm and a keytab for that identity on its local disk. However, - * rather than forcing system daemons to use the network-oriented calls in the - * krb5 and GSS APIs, KIM provides the #kim_credential_verify() API to - * verify credentials directly. - * - * The most common reason for using #kim_credential_verify() is user login. - * If the local machine wants to use Kerberos to verify the username and password - * provided by the user, it must call #kim_credential_verify() on the credentials - * it obtains to make sure they are really from a KDC it trusts. Another common - * case is a server which is only using Kerberos internally. For example an - * LDAP or web server might use a username and password obtained over the network - * to get Kerberos credentials. In order to make sure they aren't being tricked - * into talking to the wrong KDC, these servers must also call - * #kim_credential_verify(). - * - * The Zanarotti attack is only a concern if the act of accessing the machine - * gives the process special access. Thus a managed cluster machine with - * Kerberos-authenticated networked home directories does not need to call - * #kim_credential_verify(). Even though an attacker can log in as any user on - * the cluster machine, the attacker can't actually access any of the user's data - * or use any of their privileges because those are all authenticated via - * Kerberized application servers (and thus require actually having credentials - * for the real local realm). - * - * #kim_credential_verify() provides an option to - * return success even if the machine's host key is not present. This option - * exists for sites which have a mix of different machines, some of which are - * vulnerable to the Zanarotti attack and some are not. If this option is used, - * it is the responsiblity of the machine's maintainer to obtain a keytab - * for their machine if it needs one. - * - * - * \section kim_credential_properties Examining Credential Properties - * - * \li #kim_credential_get_client_identity() - * returns the credential's client identity. - * - * \li #kim_credential_get_service_identity() - * returns the credential's service identity. - * - * \li #kim_credential_is_tgt() - * returns whether the credential is a TGT (ie: "ticket-granting ticket"). TGTs are - * credentials for the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>". - * These credentials allow the entity named by the client identity to obtain - * additional service credentials without resending shared secrets (such as a password) - * to the KDC. Kerberos uses TGTs to provide single sign-on authentication. - * - * \li #kim_credential_is_valid() - * returns whether the credential is valid and if not why the credential is not valid. - * - * \li #kim_credential_get_start_time() - * returns when the credential will become valid. - * Credentials may be "post-dated" which means that their lifetime starts sometime - * in the future. Note that when a post-dated credential's start time is reached, - * the credential must be validated. See \ref kim_credential_validate for more information. - * - * \li #kim_credential_get_expiration_time() - * returns when the credential will expire. - * Credentials are time limited by the lifetime of the credential. While you can - * request a credential of any lifetime, the KDC limits the credential lifetime - * to a administrator-defined maximum. Typically credential lifetime range from 10 - * to 21 hours. - * - * \li #kim_credential_get_renewal_expiration_time() - * returns when the credential will no longer be renewable. - * Valid credentials may be renewed up until their renewal expiration time. - * Renewing credentials acquires a fresh set of credentials with a full lifetime - * without resending secrets to the KDC (such as a password). If credentials are - * not renewable, this function will return an error. - * - * - * See \ref kim_credential_reference and \ref kim_credential_iterator_reference for - * information on specific APIs. - */ - - /*! - * \defgroup kim_credential_iterator_reference KIM Credential Iterator Reference Documentation - * @{ - */ - - /*! - * \param out_credential_iterator on exit, a credential iterator object for \a in_ccache. - * Must be freed with kim_credential_iterator_free(). - * \param in_ccache a ccache object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get a credential iterator to enumerate credentials in a ccache. - */ - - kim_error kim_credential_iterator_create (kim_credential_iterator *out_credential_iterator, - kim_ccache in_ccache); - - /*! - * \param in_credential_iterator a credential iterator object. - * \param out_credential on exit, the next credential in the ccache iterated by - * \a in_credential_iterator. Must be freed with - * kim_credential_free(). If there are no more credentials - * this argument will be set to NULL. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the next credential in a ccache. - */ - - kim_error kim_credential_iterator_next (kim_credential_iterator in_credential_iterator, - kim_credential *out_credential); - - /*! - * \param io_credential_iterator a credential iterator object to be freed. Set to NULL on exit. - * \brief Free memory associated with a credential iterator. - */ - void kim_credential_iterator_free (kim_credential_iterator *io_credential_iterator); - - /*!@}*/ - - /*! - * \defgroup kim_credential_reference KIM Credential Reference Documentation - * @{ - */ - - /*! - * \param out_credential on exit, a new credential object containing a newly acquired - * initial credential. Must be freed with kim_credential_free(). - * \param in_client_identity a client identity to obtain a credential for. Specify NULL to - * allow the user to choose the identity - * \param in_options options to control credential acquisition. - * \note Depending on the kim_options specified, #kim_credential_create_new() may - * present a GUI or command line prompt to obtain information from the user. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Acquire a new initial credential. - * \sa kim_ccache_create_new - */ - kim_error kim_credential_create_new (kim_credential *out_credential, - kim_identity in_client_identity, - kim_options in_options); - - /*! - * \param out_credential on exit, a new credential object containing an initial credential - * for \a in_identity obtained using \a in_keytab. - * Must be freed with kim_credential_free(). - * \param in_identity a client identity to obtain a credential for. Specify NULL for - * the first identity in the keytab. - * \param in_options options to control credential acquisition. - * \param in_keytab a path to a keytab. Specify NULL for the default keytab location. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Acquire a new initial credential from a keytab. - * \sa kim_ccache_create_from_keytab - */ - kim_error kim_credential_create_from_keytab (kim_credential *out_credential, - kim_identity in_identity, - kim_options in_options, - kim_string in_keytab); - - /*! - * \param out_credential on exit, a new credential object which is a copy of \a in_krb5_creds. - * Must be freed with kim_credential_free(). - * \param in_krb5_context the krb5 context used to create \a in_krb5_creds. - * \param in_krb5_creds a krb5 credential object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Copy a credential from a krb5 credential object. - */ - kim_error kim_credential_create_from_krb5_creds (kim_credential *out_credential, - krb5_context in_krb5_context, - krb5_creds *in_krb5_creds); - - /*! - * \param out_credential on exit, a new credential object which is a copy of \a in_credential. - * Must be freed with kim_credential_free(). - * \param in_credential a credential object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Copy a credential object. - */ - kim_error kim_credential_copy (kim_credential *out_credential, - kim_credential in_credential); - - /*! - * \param in_credential a credential object. - * \param in_krb5_context a krb5 context which will be used to create \a out_krb5_creds. - * \param out_krb5_creds on exit, a new krb5 creds object which is a copy of \a in_credential. - * Must be freed with krb5_free_creds(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get a krb5 credentials object for a credential object. - */ - kim_error kim_credential_get_krb5_creds (kim_credential in_credential, - krb5_context in_krb5_context, - krb5_creds **out_krb5_creds); - - /*! - * \param in_credential a credential object. - * \param out_client_identity on exit, an identity object containing the client identity of - * \a in_credential. Must be freed with kim_identity_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the client identity of a credential object. - */ - kim_error kim_credential_get_client_identity (kim_credential in_credential, - kim_identity *out_client_identity); - - /*! - * \param in_credential a credential object. - * \param out_service_identity on exit, an identity object containing the service identity of - * \a in_credential. Must be freed with kim_identity_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the service identity of a credential object. - */ - kim_error kim_credential_get_service_identity (kim_credential in_credential, - kim_identity *out_service_identity); - - /*! - * \param in_credential a credential object. - * \param out_is_tgt on exit, whether or not the credential is a TGT. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Check if a credential is a ticket granting ticket. - */ - kim_error kim_credential_is_tgt (kim_credential in_credential, - kim_boolean *out_is_tgt); - - /*! - * \param in_credential a credential object. - * \param out_state on exit, the state of the credential. See #kim_credential_state_enum - * for the possible values of \a out_state. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Check the state of a credential (valid, expired, postdated, etc). - */ - kim_error kim_credential_get_state (kim_credential in_credential, - kim_credential_state *out_state); - - /*! - * \param in_credential a credential object. - * \param out_start_time on exit, the time when \a in_credential becomes valid. - * May be in the past or future. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the time when the credentials become valid. - * \sa kim_ccache_get_start_time - */ - kim_error kim_credential_get_start_time (kim_credential in_credential, - kim_time *out_start_time); - - /*! - * \param in_credential a credential object. - * \param out_expiration_time on exit, the time when \a in_credential will expire. - * May be in the past or future. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the time when the credentials will expire. - * \sa kim_ccache_get_expiration_time - */ - kim_error kim_credential_get_expiration_time (kim_credential in_credential, - kim_time *out_expiration_time); - - /*! - * \param in_credential a credential object. - * \param out_renewal_expiration_time on exit, the time when \a in_credential will no longer - * be renewable. May be in the past or future. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the time when the credentials will no longer be renewable. - * \sa kim_ccache_get_renewal_expiration_time - */ - kim_error kim_credential_get_renewal_expiration_time (kim_credential in_credential, - kim_time *out_renewal_expiration_time); - - - /*! - * \param in_credential a credential object. - * \param in_client_identity a client identity. - * \param out_ccache on exit, a ccache object containing \a in_credential with the client - * identity \a in_client_identity. Must be freed with kim_ccache_free(). - * Specify NULL if you don't want this return value. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Store a credential in a ccache in the cache collection. - */ - kim_error kim_credential_store (kim_credential in_credential, - kim_identity in_client_identity, - kim_ccache *out_ccache); - - /*! - * \param in_credential a TGT credential to be verified. - * \param in_service_identity a service identity to look for in the keytab. Specify - * KIM_IDENTITY_ANY to use the default service identity - * (usually host/<host's FQDN>@<host's local realm>). - * \param in_keytab a path to a keytab. Specify NULL for the default keytab location. - * \param in_fail_if_no_service_key whether or not the absence of a key for \a in_service_identity - * in the host's keytab will cause a failure. - * \note specifying FALSE for \a in_fail_if_no_service_key may expose the calling program to - * the Zanarotti attack if the host has no keytab installed. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Verify a TGT credential. - * \sa kim_ccache_verify - */ - kim_error kim_credential_verify (kim_credential in_credential, - kim_identity in_service_identity, - kim_string in_keytab, - kim_boolean in_fail_if_no_service_key); - - /*! - * \param io_credential a TGT credential to be renewed. On exit, the old credential - * object will be freed and \a io_credential will be replaced - * with a new renewed credential. The new credential must be freed - * with kim_credential_free(). - * \param in_options initial credential options. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Renew a TGT credential. - * \sa kim_ccache_renew - */ - kim_error kim_credential_renew (kim_credential *io_credential, - kim_options in_options); - - /*! - * \param io_credential a credential object to be validated. On exit, the old credential - * object will be freed and \a io_credential will be replaced - * with a new validated credential. The new credential must be freed - * with kim_credential_free(). - * \param in_options initial credential options. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Validate a TGT credential. - * \sa kim_ccache_validate - */ - kim_error kim_credential_validate (kim_credential *io_credential, - kim_options in_options); - - /*! - * \param io_credential the credential object to be freed. Set to NULL on exit. - * \brief Free memory associated with a credential object. - */ - void kim_credential_free (kim_credential *io_credential); - - /*!@}*/ +/*! + * \addtogroup kim_types_reference + * @{ + */ + +/*! + * Possible credential states. Credentials may be: + * \li valid - The credential can be used. + * \li expired - The credential's lifetime has been exceeded. + * \li not_yet_valid - The credential is post dated and the time when + * it becomes valid has not yet been reached. + * \li needs_validation - The credential is post-dated and although + * the time when it becomes valid has been reached + * it has not yet been validated. + * \li address_mismatch - The credential contains IP address(es) which do + * not match the host's local address(es). + */ +enum kim_credential_state_enum { + kim_credentials_state_valid = 0, + kim_credentials_state_expired = 1, + kim_credentials_state_not_yet_valid = 2, + kim_credentials_state_needs_validation = 3, + kim_credentials_state_address_mismatch = 4 +}; + +/*! + * The state of a credential. See #kim_credential_state_enum for + * possible values. + */ +typedef int kim_credential_state; + +/*! @} */ + +/*! + * \page kim_credential_overview KIM Credential Overview + * + * \section kim_credential_introduction Introduction + * + * A Kerberos credential (also called a "Kerberos ticket") is a time-limited + * token issued by a KDC which authenticates the entity named by the credential's + * client identity to the service named by the credential's service identity. + * + * The kim_credential object contains a single Kerberos credential. KIM credentials + * objects are always copies of credentials, not references to credentials + * stored in the cache collection. Modifying credential objects in the ccache + * collection will not change any existing KIM credential objects. + * + * KIM credential APIs are intended for applications and system + * tools which manage credentials for the user. They are not a substitute for + * krb5 and GSSAPI functions which obtain service credentials for the purpose + * of authenticating a client to an application server. + * + * \note Many of the APIs listed below have equivalent functions which + * operate on ccaches. In most cases applications will want to use the + * ccache versions of these APIs since they automatically store any + * newly created credentials. See \ref kim_ccache_overview for more + * information. + * + * + * \section kim_credential_acquire_new Acquiring New Credentials + * + * KIM provides the #kim_credential_create_new() API for acquiring new + * credentials. Credentials can either be obtained for a specific + * client identity or by specifying #KIM_IDENTITY_ANY to allow + * the user to choose. Typically callers of this API obtain the client + * identity using #kim_selection_hints_get_identity(). Depending on the + * kim_options specified, #kim_credential_create_new() may present a + * GUI or command line prompt to obtain information from the user. + * + * KIM provides the #kim_credential_create_from_keytab() to create credentials + * using a keytab. A keytab is an on-disk copy of a client identity's secret + * key. Typically sites use keytabs for client identities that identify a + * machine or service and protect the keytab with disk permissions. Because + * a keytab is sufficient to obtain credentials, keytabs will normally only + * be readable by root, Administrator or some other privileged account. + * Typically applications use credentials obtained from keytabs to obtain + * credentials for batch processes. These keytabs and credentials are usually + * for a special identity used for the batch process rather than a user + * identity. + * + * + * \section kim_credential_validate Validating Credentials + * + * A credential with a start time in the future (ie: after the issue date) + * is called a post-dated credential. Because the KDC administrator may + * wish to disable a identity, once the start time is reached, all post-dated + * credentials must be validated before they can be used. Otherwise an + * attacker using a compromised account could acquire lots of post-dated + * credentials to circumvent the acccount being disabled. + * + * KIM provides the #kim_credential_validate() API to validate a credential. + * Note that this API replaces the credential object with a new validated + * credential object. If you wish to store the new credential in the + * ccache collection you must either call #kim_credential_store() on the + * validated credential or use #kim_ccache_validate() instead. + * + * + * \section kim_credential_renew Renewing Credentials + * + * A renewable credential can be used to obtain a new identical credential + * without resending secret information (such as a password) to the KDC. + * A credential may only be renewed during its renewal lifetime and while + * valid. + * + * KIM provides the #kim_credential_renew() API to renew a credential. + * Note that this API replaces the credential object with a new renewed + * credential object. If you wish to store the new credential in the + * ccache collection you must either call #kim_credential_store() on the + * renewed credential or use #kim_ccache_renew() instead. + * + * + * \section kim_credential_storing Storing Credentials in the Cache Collection + * + * KIM credential objects may be stored in the ccache collection using + * #kim_credential_store(). This function runs any KIM authentication + * plugins on the credential and if the plugins return successfully, creates a + * new ccache for the credential's client identity in the cache collection + * and stores the credential in that ccache. Any existing ccaches and credentials + * for that client identity will be overwritten. #kim_credential_store() may + * optionally return a kim_ccache object for the new ccache if you need to perform + * further operations on the new ccache. + * + * Most of the time if you plan to store the credentials you are manipulating, you + * should use one of KIM ccache APIs. These functions perform the same operations + * except that they also call #kim_credential_store() any time the credential object + * changes. See \ref kim_ccache_overview for more information. + * + * + * \section kim_credential_iterator Iterating over the Credentials in a CCache + * + * KIM provides a simple iterator API for iterating over the credentials + * in a ccache. First, call #kim_credential_iterator_create() to obtain + * an iterator for a ccache. Then loop calling #kim_credential_iterator_next() + * until either you find the credential you are looking for or the API + * returns a NULL credential, indicating that there are no more + * credentials in the ccache. When you are done with the iterator, call + * #kim_credential_iterator_free(). + * + * \note #kim_credential_iterator_next() returns credential objects which + * must be freed with #kim_credential_free() to avoid leaking memory. + * + * + * \section kim_credential_verify Verifying Credentials + * + * When a program acquires TGT credentials for the purpose of authenticating + * itself to the machine it is running on, it is insufficient for the machine + * to assume that the caller is authorized just because it got credentials. + * Instead, the credentials must be verified using a key the local machine. + * The reason this is necessary is because an attacker can trick the + * machine into obtaining credentials from any KDC, including malicious ones + * with the same realm name as the local machine's realm. This exploit is + * called the Zanarotti attack. + * + * In order to avoid the Zanarotti attack, the local machine must authenticate + * the process in the same way an application server would authenticate a client. + * Like an application server, the local machine must have its own identity in + * its realm and a keytab for that identity on its local disk. However, + * rather than forcing system daemons to use the network-oriented calls in the + * krb5 and GSS APIs, KIM provides the #kim_credential_verify() API to + * verify credentials directly. + * + * The most common reason for using #kim_credential_verify() is user login. + * If the local machine wants to use Kerberos to verify the username and password + * provided by the user, it must call #kim_credential_verify() on the credentials + * it obtains to make sure they are really from a KDC it trusts. Another common + * case is a server which is only using Kerberos internally. For example an + * LDAP or web server might use a username and password obtained over the network + * to get Kerberos credentials. In order to make sure they aren't being tricked + * into talking to the wrong KDC, these servers must also call + * #kim_credential_verify(). + * + * The Zanarotti attack is only a concern if the act of accessing the machine + * gives the process special access. Thus a managed cluster machine with + * Kerberos-authenticated networked home directories does not need to call + * #kim_credential_verify(). Even though an attacker can log in as any user on + * the cluster machine, the attacker can't actually access any of the user's data + * or use any of their privileges because those are all authenticated via + * Kerberized application servers (and thus require actually having credentials + * for the real local realm). + * + * #kim_credential_verify() provides an option to + * return success even if the machine's host key is not present. This option + * exists for sites which have a mix of different machines, some of which are + * vulnerable to the Zanarotti attack and some are not. If this option is used, + * it is the responsiblity of the machine's maintainer to obtain a keytab + * for their machine if it needs one. + * + * + * \section kim_credential_properties Examining Credential Properties + * + * \li #kim_credential_get_client_identity() + * returns the credential's client identity. + * + * \li #kim_credential_get_service_identity() + * returns the credential's service identity. + * + * \li #kim_credential_is_tgt() + * returns whether the credential is a TGT (ie: "ticket-granting ticket"). TGTs are + * credentials for the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>". + * These credentials allow the entity named by the client identity to obtain + * additional service credentials without resending shared secrets (such as a password) + * to the KDC. Kerberos uses TGTs to provide single sign-on authentication. + * + * \li #kim_credential_is_valid() + * returns whether the credential is valid and if not why the credential is not valid. + * + * \li #kim_credential_get_start_time() + * returns when the credential will become valid. + * Credentials may be "post-dated" which means that their lifetime starts sometime + * in the future. Note that when a post-dated credential's start time is reached, + * the credential must be validated. See \ref kim_credential_validate for more information. + * + * \li #kim_credential_get_expiration_time() + * returns when the credential will expire. + * Credentials are time limited by the lifetime of the credential. While you can + * request a credential of any lifetime, the KDC limits the credential lifetime + * to a administrator-defined maximum. Typically credential lifetime range from 10 + * to 21 hours. + * + * \li #kim_credential_get_renewal_expiration_time() + * returns when the credential will no longer be renewable. + * Valid credentials may be renewed up until their renewal expiration time. + * Renewing credentials acquires a fresh set of credentials with a full lifetime + * without resending secrets to the KDC (such as a password). If credentials are + * not renewable, this function will return an error. + * + * + * See \ref kim_credential_reference and \ref kim_credential_iterator_reference for + * information on specific APIs. + */ + +/*! + * \defgroup kim_credential_iterator_reference KIM Credential Iterator Reference Documentation + * @{ + */ + +/*! + * \param out_credential_iterator on exit, a credential iterator object for \a in_ccache. + * Must be freed with kim_credential_iterator_free(). + * \param in_ccache a ccache object. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Get a credential iterator to enumerate credentials in a ccache. + */ + +kim_error kim_credential_iterator_create (kim_credential_iterator *out_credential_iterator, + kim_ccache in_ccache); + +/*! + * \param in_credential_iterator a credential iterator object. + * \param out_credential on exit, the next credential in the ccache iterated by + * \a in_credential_iterator. Must be freed with + * kim_credential_free(). If there are no more credentials + * this argument will be set to NULL. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Get the next credential in a ccache. + */ + +kim_error kim_credential_iterator_next (kim_credential_iterator in_credential_iterator, + kim_credential *out_credential); + +/*! + * \param io_credential_iterator a credential iterator object to be freed. Set to NULL on exit. + * \brief Free memory associated with a credential iterator. + */ +void kim_credential_iterator_free (kim_credential_iterator *io_credential_iterator); + +/*!@}*/ + +/*! + * \defgroup kim_credential_reference KIM Credential Reference Documentation + * @{ + */ + +/*! + * \param out_credential on exit, a new credential object containing a newly acquired + * initial credential. Must be freed with kim_credential_free(). + * \param in_client_identity a client identity to obtain a credential for. Specify NULL to + * allow the user to choose the identity + * \param in_options options to control credential acquisition. + * \note Depending on the kim_options specified, #kim_credential_create_new() may + * present a GUI or command line prompt to obtain information from the user. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Acquire a new initial credential. + * \sa kim_ccache_create_new + */ +kim_error kim_credential_create_new (kim_credential *out_credential, + kim_identity in_client_identity, + kim_options in_options); + +/*! + * \param out_credential on exit, a new credential object containing an initial credential + * for \a in_identity obtained using \a in_keytab. + * Must be freed with kim_credential_free(). + * \param in_identity a client identity to obtain a credential for. Specify NULL for + * the first identity in the keytab. + * \param in_options options to control credential acquisition. + * \param in_keytab a path to a keytab. Specify NULL for the default keytab location. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Acquire a new initial credential from a keytab. + * \sa kim_ccache_create_from_keytab + */ +kim_error kim_credential_create_from_keytab (kim_credential *out_credential, + kim_identity in_identity, + kim_options in_options, + kim_string in_keytab); + +/*! + * \param out_credential on exit, a new credential object which is a copy of \a in_krb5_creds. + * Must be freed with kim_credential_free(). + * \param in_krb5_context the krb5 context used to create \a in_krb5_creds. + * \param in_krb5_creds a krb5 credential object. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Copy a credential from a krb5 credential object. + */ +kim_error kim_credential_create_from_krb5_creds (kim_credential *out_credential, + krb5_context in_krb5_context, + krb5_creds *in_krb5_creds); + +/*! + * \param out_credential on exit, a new credential object containing a change + * password credential for \a in_identity. + * Must be freed with kim_credential_free(). + * \param in_identity a client identity to obtain a change password credential for. + * \param in_old_password the current password for \a in_identity. May be + * an expired password. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Obtain a credential for changing an identity's password. + * \sa kim_credential_change_password + */ +kim_error kim_credential_create_for_change_password (kim_credential *out_credential, + kim_identity in_identity, + kim_string in_old_password); + +/*! + * \param out_credential on exit, a new credential object which is a copy of \a in_credential. + * Must be freed with kim_credential_free(). + * \param in_credential a credential object. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Copy a credential object. + */ +kim_error kim_credential_copy (kim_credential *out_credential, + kim_credential in_credential); + +/*! + * \param in_credential a credential object. + * \param in_krb5_context a krb5 context which will be used to create \a out_krb5_creds. + * \param out_krb5_creds on exit, a new krb5 creds object which is a copy of \a in_credential. + * Must be freed with krb5_free_creds(). + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Get a krb5 credentials object for a credential object. + */ +kim_error kim_credential_get_krb5_creds (kim_credential in_credential, + krb5_context in_krb5_context, + krb5_creds **out_krb5_creds); + +/*! + * \param in_credential a credential object. + * \param out_client_identity on exit, an identity object containing the client identity of + * \a in_credential. Must be freed with kim_identity_free(). + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Get the client identity of a credential object. + */ +kim_error kim_credential_get_client_identity (kim_credential in_credential, + kim_identity *out_client_identity); + +/*! + * \param in_credential a credential object. + * \param out_service_identity on exit, an identity object containing the service identity of + * \a in_credential. Must be freed with kim_identity_free(). + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Get the service identity of a credential object. + */ +kim_error kim_credential_get_service_identity (kim_credential in_credential, + kim_identity *out_service_identity); + +/*! + * \param in_credential a credential object. + * \param out_is_tgt on exit, whether or not the credential is a TGT. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Check if a credential is a ticket granting ticket. + */ +kim_error kim_credential_is_tgt (kim_credential in_credential, + kim_boolean *out_is_tgt); + +/*! + * \param in_credential a credential object. + * \param out_state on exit, the state of the credential. See #kim_credential_state_enum + * for the possible values of \a out_state. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Check the state of a credential (valid, expired, postdated, etc). + */ +kim_error kim_credential_get_state (kim_credential in_credential, + kim_credential_state *out_state); + +/*! + * \param in_credential a credential object. + * \param out_start_time on exit, the time when \a in_credential becomes valid. + * May be in the past or future. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Get the time when the credentials become valid. + * \sa kim_ccache_get_start_time + */ +kim_error kim_credential_get_start_time (kim_credential in_credential, + kim_time *out_start_time); + +/*! + * \param in_credential a credential object. + * \param out_expiration_time on exit, the time when \a in_credential will expire. + * May be in the past or future. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Get the time when the credentials will expire. + * \sa kim_ccache_get_expiration_time + */ +kim_error kim_credential_get_expiration_time (kim_credential in_credential, + kim_time *out_expiration_time); + +/*! + * \param in_credential a credential object. + * \param out_renewal_expiration_time on exit, the time when \a in_credential will no longer + * be renewable. May be in the past or future. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Get the time when the credentials will no longer be renewable. + * \sa kim_ccache_get_renewal_expiration_time + */ +kim_error kim_credential_get_renewal_expiration_time (kim_credential in_credential, + kim_time *out_renewal_expiration_time); + + +/*! + * \param in_credential a credential object. + * \param in_client_identity a client identity. + * \param out_ccache on exit, a ccache object containing \a in_credential with the client + * identity \a in_client_identity. Must be freed with kim_ccache_free(). + * Specify NULL if you don't want this return value. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Store a credential in a ccache in the cache collection. + */ +kim_error kim_credential_store (kim_credential in_credential, + kim_identity in_client_identity, + kim_ccache *out_ccache); + +/*! + * \param in_credential a TGT credential to be verified. + * \param in_service_identity a service identity to look for in the keytab. Specify + * KIM_IDENTITY_ANY to use the default service identity + * (usually host/<host's FQDN>@<host's local realm>). + * \param in_keytab a path to a keytab. Specify NULL for the default keytab location. + * \param in_fail_if_no_service_key whether or not the absence of a key for \a in_service_identity + * in the host's keytab will cause a failure. + * \note specifying FALSE for \a in_fail_if_no_service_key may expose the calling program to + * the Zanarotti attack if the host has no keytab installed. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Verify a TGT credential. + * \sa kim_ccache_verify + */ +kim_error kim_credential_verify (kim_credential in_credential, + kim_identity in_service_identity, + kim_string in_keytab, + kim_boolean in_fail_if_no_service_key); + +/*! + * \param io_credential a TGT credential to be renewed. On exit, the old credential + * object will be freed and \a io_credential will be replaced + * with a new renewed credential. The new credential must be freed + * with kim_credential_free(). + * \param in_options initial credential options. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Renew a TGT credential. + * \sa kim_ccache_renew + */ +kim_error kim_credential_renew (kim_credential *io_credential, + kim_options in_options); + +/*! + * \param io_credential a credential object to be validated. On exit, the old credential + * object will be freed and \a io_credential will be replaced + * with a new validated credential. The new credential must be freed + * with kim_credential_free(). + * \param in_options initial credential options. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Validate a TGT credential. + * \sa kim_ccache_validate + */ +kim_error kim_credential_validate (kim_credential *io_credential, + kim_options in_options); + +/*! + * \param in_credential a credential object containing a change + * password credential. Use + * #kim_credential_change_password to obtain + * a change password credential. + * \param in_identity an identity to change the password for. May + * be different than the identity the credential + * is for. + * \param in_new_password the password to change the identity to. + * \param out_rejected_err on exit, 0 if the password change was + * successful or an error describing why the + * new password was rejected. + * \param out_rejected_message on exit, if \a out_rejected_err is non-zero + * this argument will contain an error message + * for \a out_rejected_err. Pass NULL if you + * do not want this error string. Must be + * freed with #kim_string_free(); + * \param out_rejected_description on exit, if \a out_rejected_err is non-zero + * this argument will contain an string describing + * why \a in_new_password was rejected. Pass NULL + * if you do not want this error string. Must be + * freed with #kim_string_free(); + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Change an identity's password. + * \sa kim_credential_create_for_change_password + */ +kim_error kim_credential_change_password (kim_credential in_credential, + kim_identity in_identity, + kim_string in_new_password, + kim_error *out_rejected_err, + kim_string *out_rejected_message, + kim_string *out_rejected_description); + +/*! + * \param io_credential the credential object to be freed. Set to NULL on exit. + * \brief Free memory associated with a credential object. + */ +void kim_credential_free (kim_credential *io_credential); + +/*!@}*/ #ifdef __cplusplus diff --git a/src/include/kim/kim_identity.h b/src/include/kim/kim_identity.h index 4461c3163..f09c24aa7 100644 --- a/src/include/kim/kim_identity.h +++ b/src/include/kim/kim_identity.h @@ -256,29 +256,12 @@ kim_error kim_identity_get_krb5_principal (kim_identity in_identity, /*! * \param in_identity an identity object whose password will be changed. - * \param in_options initial credential options to be used if a new credential is obtained. * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. * \brief Change the password for an identity. * \note kim_identity_change_password() will acquire a temporary credential to change - * the password. It uses the \a in_options structure to obtain information about the desired - * prompter and current password. + * the password. */ -kim_error kim_identity_change_password (kim_identity in_identity, - kim_options in_options); - -/*! - * \param in_identity an identity object whose password will be changed. - * \param in_options initial credential options to be used if a new credential is obtained. - * \param in_new_password a string representation of the identity's new password. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Change the password for an identity to a caller-provided new password. - * \note kim_identity_change_password_with_passwords() will acquire a temporary credential - * to change the password. It uses the \a in_options structure to obtain information about - * the desired prompter and current password. - */ -kim_error kim_identity_change_password_to_password (kim_identity in_identity, - kim_options in_options, - kim_string in_new_password); +kim_error kim_identity_change_password (kim_identity in_identity); /*! * \param io_identity the identity object to be freed. Set to NULL on exit. diff --git a/src/include/kim/kim_options.h b/src/include/kim/kim_options.h index f5b975cf3..2c82b3ef5 100644 --- a/src/include/kim/kim_options.h +++ b/src/include/kim/kim_options.h @@ -46,70 +46,6 @@ extern "C" { */ #define KIM_OPTIONS_START_IMMEDIATELY ((kim_time_t) 0) -/*! - * The type of prompt which needs to be displayed. - * This value determines what type of user interface is displayed. - * See \ref kim_options_custom_prompt_callback for more information. - */ -typedef uint32_t kim_prompt_type; - -enum kim_prompt_type_enum { - kim_prompt_type_password = 0, - kim_prompt_type_challenge = 1 -}; - -/*! - * The prompt callback used to display a prompt to the user. - * See \ref kim_options_custom_prompt_callback for more information. - */ -typedef kim_error (*kim_prompt_callback) (kim_prompt_type in_type, - kim_string in_title, - kim_string in_message, - kim_string in_description, - char **out_reply); - -/*! - * The default prompt callback. - * See \ref kim_options_custom_prompt_callback for more information. - */ -kim_error kim_prompt_callback_default (kim_prompt_type in_type, - kim_string in_title, - kim_string in_message, - kim_string in_description, - char **out_reply); - -/*! - * The graphical prompt callback. - * See \ref kim_options_custom_prompt_callback for more information. - */ -kim_error kim_prompt_callback_gui (kim_prompt_type in_type, - kim_string in_title, - kim_string in_message, - kim_string in_description, - char **out_reply); - -/*! - * The command line prompt callback. - * See \ref kim_options_custom_prompt_callback for more information. - */ -kim_error kim_prompt_callback_cli (kim_prompt_type in_type, - kim_string in_title, - kim_string in_message, - kim_string in_description, - char **out_reply); - -/*! - * The prompt callback which always returns an error. - * Use to turn off prompting entirely. - * \note Using this callback may prevent the user from authenicating. - * See \ref kim_options_custom_prompt_callback for more information. - */ -kim_error kim_prompt_callback_none (kim_prompt_type in_type, - kim_string in_title, - kim_string in_message, - kim_string in_description, - char **out_reply); - /*! @} */ /*! @@ -126,34 +62,6 @@ kim_error kim_prompt_callback_none (kim_prompt_type in_type, * KIM options fall into two major categories: options for controlling how credentials are * acquired and options for controlling what properties the newly acquired credentials will have: * - * \section kim_options_credential_acquisition Options for Controlling Credential Acquisition - * - * In order to acquire credentials, Kerberos needs to obtain one or more secrets from the user. - * These secrets may be a certificate, password, SecurID pin, or information from a smart card. - * If obtaining the secret requires interaction with the user, the Kerberos libraries call a - * "prompter callback" to display a dialog or command line prompt to request information from - * the user. If you want to provide your own custom dialogs or command line prompts, - * the KIM APIs provide a mechanism for replacing the default prompt callbacks with your own. - * - * \subsection kim_options_custom_prompt_callback Providing a Custom Prompt Callback - * - * All secrets are obtained from the user through a #kim_prompt_callback_t. By default, - * options use #kim_prompt_callback_default, which presents a dialog to request - * information from the user, or if no graphical access is available, a command line prompt. - * - * KIM also provides three other callbacks: #kim_prompt_callback_gui only presents - * a dialog and returns an error if there is no graphical access. #kim_prompt_callback_cli - * only presents a command line interface and returns an error if there is no controlling - * terminal available. #kim_prompt_callback_none always returns an error. - * - * Using #kim_options_set_prompt_callback(), you can change the prompt callback to one of - * the above callbacks or a callback you have defined yourself. Callbacks are called in a - * loop, one for each prompt. Because network traffic may occur between calls to the prompt - * callback, your prompt interface should support time passing between calls to the prompter. - * If you are defining a callback yourself, you should also set your own options data with - * #kim_options_set_data() for storing state between calls. Options data is a caller - * defined pointer value -- the Kerberos libaries make no use of it. - * * \section kim_options_credential_properties Options for Controlling Credential Properties * * Kerberos credentials have a number of different properties which can be requested @@ -286,61 +194,6 @@ kim_error kim_options_copy (kim_options *out_options, kim_options in_options); /*! - * \param io_options an options object to modify. - * \param in_prompt_callback a prompt callback function. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the prompt callback for obtaining information from the user. - * \par Default value - * #kim_prompt_callback_default - * \sa kim_options_get_prompt_callback() - */ -kim_error kim_options_set_prompt_callback (kim_options io_options, - kim_prompt_callback in_prompt_callback); - -/*! - * \param in_options an options object. - * \param out_prompt_callback on exit, the prompt callback specified by in_options. - * Does not need to be freed but may become invalid when - * \a in_options is freed. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the prompt callback for obtaining information from the user. - * \par Default value - * #kim_prompt_callback_default - * \sa kim_options_set_prompt_callback() - */ -kim_error kim_options_get_prompt_callback (kim_options in_options, - kim_prompt_callback *out_prompt_callback); - -/*! - * \param io_options an options object to modify. - * \param in_data a pointer to caller-specific data. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set caller-specific data for use in library callbacks. - * \note This option can be used by the caller to store a pointer to data needed when handling a - * callback. The KIM library does not use this options data in any way. - * \par Default value - * NULL (no data is set by default) - * \sa kim_options_get_data() - */ -kim_error kim_options_set_data (kim_options io_options, - const void *in_data); - -/*! - * \param in_options an options object. - * \param out_data on exit, the pointer to caller specific data specified by in_options. - * Does not need to be freed but may become invalid when \a in_options is freed. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get caller-specific data for use in library callbacks. - * \note This option can be used by the caller to store a pointer to data needed when handling a - * callback. The KIM library does not use this options data in any way. - * \par Default value - * NULL (no data is set by default) - * \sa kim_options_set_data() - */ -kim_error kim_options_get_data (kim_options in_options, - const void **out_data); - -/*! * \param io_options an options object to modify. * \param in_start_time a start date (in seconds since January 1, 1970). Set to * #KIM_OPTIONS_START_IMMEDIATELY for the acquired credential to be valid diff --git a/src/include/kim/kim_ui_plugin.h b/src/include/kim/kim_ui_plugin.h index d7fd6e1b7..b7d48ad89 100644 --- a/src/include/kim/kim_ui_plugin.h +++ b/src/include/kim/kim_ui_plugin.h @@ -29,7 +29,28 @@ extern "C" { #endif +/*! + * The type of prompt which needs to be displayed. + * This value determines what type of user interface is displayed. + * See \ref kim_options_custom_prompt_callback for more information. + */ +typedef uint32_t kim_prompt_type; + +enum kim_prompt_type_enum { + kim_prompt_type_password = 0, + kim_prompt_type_preauth = 1 +}; + /* + * Plugins for Controlling Identity Selection and Credential Acquisition + * + * In order to acquire credentials, Kerberos needs to obtain one or more secrets from the user. + * These secrets may be a certificate, password, SecurID pin, or information from a smart card. + * If obtaining the secret requires interaction with the user, the Kerberos libraries call a + * "prompter callback" to display a dialog or command line prompt to request information from + * the user. If you want to provide your own custom dialogs or command line prompts, + * the KIM APIs provide a plugin mechanism for replacing the default prompt ui with your own. + * * The function table / structure which a KIM ui plugin module must export * as "kim_ui_0". If the interfaces work correctly, future versions of the * table will add either more callbacks or more arguments to callbacks, and @@ -49,9 +70,19 @@ typedef struct kim_ui_plugin_ftable_v0 { * this ui. */ kim_error (*init) (void **out_context); + /* Present UI which allows the user to enter a new identity. + * This is typically called when the user selects a "new tickets" + * control or menu item from a ticket management utility. + * If this UI calls into KIM to get new credentials it may + * call auth_prompt below. */ + kim_error (*enter_identity) (void *in_context, + kim_identity *out_identity); + /* Present UI to select which identity to use. + * This is typically called the first time an application tries to use + * Kerberos and is used to establish a hints preference for the application. * If this UI calls into KIM to get new credentials it may - * call acquire_new_credentials below. */ + * call auth_prompt below. */ kim_error (*select_identity) (void *in_context, kim_selection_hints in_hints, kim_identity *out_identity); @@ -60,13 +91,14 @@ typedef struct kim_ui_plugin_ftable_v0 { kim_error (*auth_prompt) (void *in_context, kim_identity in_identity, kim_prompt_type in_type, + kim_boolean in_hide_reply, kim_string in_title, kim_string in_message, kim_string in_description, char **out_reply); /* Prompt to change the identity's password. - * May be combined with an auth prompt if additional auth is required, + * May be combined with an auth_prompt if additional auth is required, * eg: SecurID pin. * If in_old_password_expired is true, this callback is in response * to an expired password error. If this is the case the same context @@ -79,15 +111,18 @@ typedef struct kim_ui_plugin_ftable_v0 { char **out_verify_password); /* Display an error to the user; may be called after any of the prompts */ - kim_error (*display_error) (void *in_context, - kim_identity in_identity, - kim_error in_error, - kim_string in_error_message, - kim_string in_error_description); + kim_error (*handle_error) (void *in_context, + kim_identity in_identity, + kim_error in_error, + kim_string in_error_message, + kim_string in_error_description); - /* Free strings returned by the UI */ - void (*free_string) (void *in_context, - char *io_string); + /* Free strings returned by the UI. Will be called once for each string + * returned from a plugin callback. If you have returned a string twice + * just make sure your free function checks for NULL and sets the pointer + * to NULL when done freeing memory. */ + void (*free_string) (void *in_context, + char **io_string); /* Called after the last prompt (even on error) to allow the UI to * free allocated resources associated with its context. */ |