diff options
Diffstat (limited to 'src/include')
| -rw-r--r-- | src/include/k5-thread.h | 2 | ||||
| -rw-r--r-- | src/include/kim/kim.h | 170 | ||||
| -rw-r--r-- | src/include/kim/kim_ccache.h | 660 | ||||
| -rw-r--r-- | src/include/kim/kim_credential.h | 569 | ||||
| -rw-r--r-- | src/include/kim/kim_identity.h | 287 | ||||
| -rw-r--r-- | src/include/kim/kim_library.h | 84 | ||||
| -rw-r--r-- | src/include/kim/kim_options.h | 432 | ||||
| -rw-r--r-- | src/include/kim/kim_preferences.h | 420 | ||||
| -rw-r--r-- | src/include/kim/kim_selection_hints.h | 439 | ||||
| -rw-r--r-- | src/include/kim/kim_string.h | 123 | ||||
| -rw-r--r-- | src/include/kim/kim_types.h | 156 | ||||
| -rw-r--r-- | src/include/kim/kim_ui_plugin.h | 153 |
12 files changed, 0 insertions, 3495 deletions
diff --git a/src/include/k5-thread.h b/src/include/k5-thread.h index 0c90b55e9..17ef69ee7 100644 --- a/src/include/k5-thread.h +++ b/src/include/k5-thread.h @@ -406,10 +406,8 @@ typedef enum { K5_KEY_GSS_KRB5_SET_CCACHE_OLD_NAME, K5_KEY_GSS_KRB5_CCACHE_NAME, K5_KEY_GSS_KRB5_ERROR_MESSAGE, - K5_KEY_KIM_ERROR_MESSAGE, #if defined(__MACH__) && defined(__APPLE__) K5_KEY_IPC_CONNECTION_INFO, - K5_KEY_COM_ERR_REENTER, #endif K5_KEY_MAX } k5_key_t; diff --git a/src/include/kim/kim.h b/src/include/kim/kim.h deleted file mode 100644 index 7edb2a206..000000000 --- a/src/include/kim/kim.h +++ /dev/null @@ -1,170 +0,0 @@ -/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ -/* - * Copyright 2005-2006 Massachusetts Institute of Technology. - * All Rights Reserved. - * - * Export of this software from the United States of America may - * require a specific license from the United States Government. - * It is the responsibility of any person or organization contemplating - * export to obtain such a license before exporting. - * - * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - * distribute this software and its documentation for any purpose and - * without fee is hereby granted, provided that the above copyright - * notice appear in all copies and that both that copyright notice and - * this permission notice appear in supporting documentation, and that - * the name of M.I.T. not be used in advertising or publicity pertaining - * to distribution of the software without specific, written prior - * permission. Furthermore if you modify this software you must label - * your software as modified software and not distribute it in such a - * fashion that it might be confused with the original M.I.T. software. - * M.I.T. makes no representations about the suitability of - * this software for any purpose. It is provided "as is" without express - * or implied warranty. - */ - -#ifndef KIM_H -#define KIM_H - -#ifdef __cplusplus -extern "C" { -#endif - -#include <kim/kim_types.h> -#include <kim/kim_errors.h> -#include <kim/kim_string.h> -#include <kim/kim_identity.h> -#include <kim/kim_options.h> -#include <kim/kim_selection_hints.h> -#include <kim/kim_preferences.h> -#include <kim/kim_credential.h> -#include <kim/kim_ccache.h> - -/*! - * \mainpage Kerberos Identity Management (KIM) API Documentation - * - * \section introduction Introduction - * - * The Kerberos Identity Management API is a high level API for managing the selection - * and management of Kerberos credentials. It is intended for use by applications, - * credential management applications (eg: kinit, kpasswd, etc) and internally by the - * Kerberos libraries. Under some circumstances client applications may also benefit - * from the Kerberos Identity Management API. - * - * - * \section conventions API Conventions - * - * Although KIM currently only provides a C API, it attempts to make that API as - * object-oriented as possible. KIM functions are grouped by object and all of the - * object types are opaque, including errors. The reason for this is two-fold. First, - * the KIM API is rather large. Grouping functions by object allows the API to be - * broken up into smaller, more manageable chunks. Second, providing an object-like C - * API will make it easier to port to object oriented languages. - * - * Because C lacks classes and other object oriented syntax, KIM functions adhere to - * the following naming conventions to make functions easier to identify: - * - * \li Functions beginning with \b kim_object_create are constructors for an object of - * type kim_object. On success these functions return a newly allocated object which - * must later be freed by the caller. - * - * \li Functions of the form \b kim_object_copy are copy constructors. They instantiate - * a new object of kim_object from an object of the same type. - * - * \li Functions of the form \b kim_object_free are destructors for objects of type - * kim_object. - * - * \li Functions beginning with \b kim_object_get and \b kim_object_set - * examine and modify properties of objects of type kim_object. - * - * \li All KIM APIs except destructors and error management APIs return a - * KIM Error object (kim_error_t). - * - * - * \section terminology Terminology - * - * Kerberos organizes its authentication tokens by client identity (the name of the user) - * and service identity (the name of a service). The following terms are used throughout - * this documentation: - * - * \li <b>credential</b> - A token which authenticates a client identity to a - * service identity. - * - * \li <b>ccache</b> - Short for "credentials cache". A set of credentials for a single - * client identity. - * - * \li <b>cache collection</b> - The set of all credential caches. - * - * \li <b>default ccache</b> - A credentials cache that the Kerberos libraries will use - * if no ccache is specified by the caller. Use of the default - * ccache is now discouraged. Instead applications should use - * selection hints to choose an appropriate client identity. - * - * \section selection_api Client Identity Selection APIs - * - * KIM provides high level APIs for applications to select which client identity to - * use. Use of these APIs is intended to replace the traditional "default ccache" - * mechanism previously used by Kerberos. - * - * <B>KIM Selection Hints (kim_selection_hints_t)</B> controls options for selecting - * a client identity: - * - \subpage kim_selection_hints_overview - * - \subpage kim_selection_hints_reference - * - * <B>KIM Identity (kim_identity_t)</B> provides an immutable Kerberos identity object - * - \subpage kim_identity_overview - * - \subpage kim_identity_reference - * - * - * \section management_api Credential Management APIs - * - * KIM also provides APIs for acquiring new credentials over the network - * by contacting a KDC and for viewing and modifying the existing credentials - * in the cache collection - * - * Whether or not you use the credential or ccache APIs depends on - * whether you want KIM to store any newly acquired credentials in the - * cache collection. KIM ccache APIs always create a ccache in the cache - * collection containing newly acquired credentials whereas the KIM - * credential APIs just return a credential object. In general most - * callers want to store newly acquired credentials and should use the - * KIM ccache APIs when acquiring credentials. - * - * <B>KIM CCache (kim_ccache_t)</B> manipulates credential caches in the cache collection: - * - \subpage kim_ccache_overview - * - \subpage kim_ccache_reference - * - * <B>KIM Credential (kim_credential_t)</B> manipulates credentials: - * - \subpage kim_credential_overview - * - \subpage kim_credential_reference - * - * <B>KIM Options (kim_options_t)</B> control options for credential acquisition: - * - \subpage kim_options_overview - * - \subpage kim_options_reference - * - * <B>KIM Preferences (kim_preferences_t)</B> views and edits the current user's preferences: - * - \subpage kim_preferences_overview - * - \subpage kim_preferences_reference - * - * - * \section utility_apis Miscellaneous APIs - * - * The high and low level APIs depend on the following basic utility classes - * to manage generic types. - * - * <B>KIM String (kim_string_t)</B> provides memory management for an immutable string: - * - \subpage kim_string_overview - * - \subpage kim_string_reference - * - * - * - * \section types Types and Constants - * - * \li \subpage kim_types_reference - */ - -#ifdef __cplusplus -} -#endif - -#endif /* KIM_H */ diff --git a/src/include/kim/kim_ccache.h b/src/include/kim/kim_ccache.h deleted file mode 100644 index d2d0d1de0..000000000 --- a/src/include/kim/kim_ccache.h +++ /dev/null @@ -1,660 +0,0 @@ -/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ -/* - * Copyright 2005-2006 Massachusetts Institute of Technology. - * All Rights Reserved. - * - * Export of this software from the United States of America may - * require a specific license from the United States Government. - * It is the responsibility of any person or organization contemplating - * export to obtain such a license before exporting. - * - * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - * distribute this software and its documentation for any purpose and - * without fee is hereby granted, provided that the above copyright - * notice appear in all copies and that both that copyright notice and - * this permission notice appear in supporting documentation, and that - * the name of M.I.T. not be used in advertising or publicity pertaining - * to distribution of the software without specific, written prior - * permission. Furthermore if you modify this software you must label - * your software as modified software and not distribute it in such a - * fashion that it might be confused with the original M.I.T. software. - * M.I.T. makes no representations about the suitability of - * this software for any purpose. It is provided "as is" without express - * or implied warranty. - */ - -#ifndef KIM_CCACHE_H -#define KIM_CCACHE_H - -#ifdef __cplusplus -extern "C" { -#endif - -#include <kim/kim_types.h> - -/*! - * \page kim_ccache_overview KIM CCache Overview - * - * \section kim_ccache_introduction Introduction - * - * Kerberos credentials are stored in "ccaches" (short for "credentials caches"). - * The set of all ccaches which the KIM can use is called the "cache collection". - * Each ccache has a name and type which uniquely identify it in the cache - * collection and a client identity. The ccache's client identity is the - * identity whose credentials are stored in the ccache. This allows for easy - * lookup of all the credentials for a given identity. - * - * KIM attempts to preserve a one-to-one relationship between client identities - * and ccaches. If the KIM is used to manipulate the cache collection, there - * will be one ccache per identity. However, because low-level APIs allow callers - * to create multiple ccaches for the same client identity or a single ccache - * containing credentials for different client identities, KIM handles those - * situations. In general when searching KIM will find the first ccache matching - * the requested client identity. It will not find credentials for the requested - * client identity if they are in a ccache with a different client identity. - * - * The kim_ccache_t object is a reference to a ccache in the cache collection. - * If other applications make changes to the the ccache pointed to by a KIM ccache - * object, the object will immediately show those changes. KIM performs locking - * on the cache collection to prevent deadlocks and maintain a consistent behavior - * when multiple applications attempt to modify the cache collection. - * - * \note KIM ccache 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. - * - * \section kim_credential_cache_collection Acquiring a CCache from the Cache Collection - * - * KIM provides a simple iterator API for iterating over the ccaches - * in the cache collection. First, call #kim_ccache_iterator_create() to obtain - * an iterator for the cache collection. Then loop calling - * #kim_ccache_iterator_next() until either you find the ccache you are looking - * for or the API returns a NULL ccache, indicating that there are no more - * ccaches in the cache collection. When you are done with the iterator, call - * #kim_ccache_iterator_free(). - * - * \note #kim_ccache_iterator_next() returns ccache objects which - * must be freed with #kim_ccache_free() to avoid leaking memory. - * - * KIM also provides a convenient API #kim_ccache_create_from_client_identity() - * which returns the ccache for a specific client identity, if any exists. - * Typically callers of this API obtain the client identity using - * #kim_selection_hints_get_identity(). - * - * - * \section kim_ccache_acquire_default Acquiring Credentials from the Default CCache - * - * #kim_ccache_create_from_default() returns the default ccache. - * The default ccache is a legacy concept which was replaced by selection - * hints. Prior to the existence of selection hints, applications always - * looked at the default ccache for credentials. By setting the system default - * ccache, users could manually control which credentials each application used. - * As the number of ccaches and applications has grown, this mechanism has become - * unusable. You should avoid using this API whenever possible. - * - * - * \section kim_ccache_acquire_new Acquiring New Credentials in a CCache - * - * KIM provides the #kim_ccache_create_new() API for acquiring new - * credentials and storing them in a ccache. 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_ccache_create_new() may present a GUI or command line - * prompt to obtain information from the user. - * - * #kim_ccache_create_new_if_needed() - * searches the cache collection for a ccache for the client identity - * and if no appropriate ccache is available, attempts to acquire - * new credentials and store them in a new ccache. Depending on the - * kim_options specified, #kim_ccache_create_new_if_needed() may - * present a GUI or command line prompt to obtain information from the - * user. This function exists for convenience and to avoid code duplication. - * It can be trivially implemented using - * #kim_ccache_create_from_client_identity() and #kim_ccache_create_new(). - * - * For legacy password-based Kerberos environments KIM also provides - * #kim_ccache_create_new_with_password() and - * #kim_ccache_create_new_if_needed_with_password(). You should not use these - * functions unless you know that they will only be used in environments using - * passwords. Otherwise users without passwords may be prompted for them. - * - * KIM provides the #kim_ccache_create_from_keytab() to create credentials - * using a keytab and store them in the cache collection. 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_ccache_validate Validating Credentials in a CCache - * - * 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_ccache_validate() API to validate the TGT - * credential in a ccache. Note that this API replaces any existing - * credentials with the validated credential. - * - * - * \section kim_ccache_renew Renewing Credentials in a CCache - * - * 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_ccache_renew() API to renew the TGT credential - * in a ccache. Note that this API replaces any existing credentials with the - * renewed credential. - * - * - * \section kim_ccache_verify Verifying Credentials in a CCache - * - * 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_ccache_verify() API to - * verify credentials directly. - * - * The most common reason for using #kim_ccache_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_ccache_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_ccache_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_ccache_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_ccache_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_ccache_properties Examining CCache Properties - * - * \li #kim_ccache_get_type() returns the type of the ccache. Types include - * "API" for CCAPI ccaches, "FILE" for file-based ccaches and "MEMORY" for - * single-process in-memory ccaches. - * - * \li #kim_ccache_get_name() returns the name of the ccache. A ccache's name - * identifies the ccache uniquely among ccaches of the same type. Note that - * two ccaches with different types may have the same name. - * - * \li #kim_ccache_get_display_name() returns a display string which uniquely - * identifies a ccache. A ccache display name is of the form "<type>:<name>" - * and can be displayed to the user or used as an argument to certain krb5 - * APIs, such as krb5_cc_resolve(). - * - * \li #kim_ccache_get_client_identity() - * returns the ccache's client identity. - * - * \li #kim_ccache_get_valid_credential() - * returns the first valid TGT in the ccache for its client identity. - * If there are no TGTs in the ccache, it returns the first - * valid non-TGT credential for the ccache's client identity. - * TGT credentials (ie: "ticket-granting tickets") 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 credentials without resending shared secrets (such as a password) - * to the KDC. Kerberos uses TGTs to provide single sign-on authentication. - * - * \li #kim_ccache_get_start_time() - * returns when the credential's in a ccache 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_ccache_get_expiration_time() - * returns when the credential's in a ccache 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_ccache_get_renewal_expiration_time() - * returns when the credential's in a ccache 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. - * - * \li #kim_ccache_get_options() - * returns a kim_options object with the credential options of the credentials - * in the ccache. This function is intended to be used when adding - * an identity with existing credentials to the favorite identities list. - * By passing in the options returned by this call, future requests for the - * favorite identity will use the same credential options. - * - * See \ref kim_ccache_reference and \ref kim_ccache_iterator_reference for - * information on specific APIs. - */ - - -/*! - * \defgroup kim_ccache_iterator_reference KIM CCache Iterator Reference Documentation - * @{ - */ - -/*! - * \param out_ccache_iterator on exit, a ccache iterator object for the cache collection. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get a ccache iterator to enumerate ccaches in the cache collection. - */ -kim_error kim_ccache_iterator_create (kim_ccache_iterator *out_ccache_iterator); - -/*! - * \param in_ccache_iterator a ccache iterator object. - * \param out_ccache on exit, the next ccache in the cache collection. If there are - * no more ccaches in the cache collection 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 ccache in the cache collection. - */ -kim_error kim_ccache_iterator_next (kim_ccache_iterator in_ccache_iterator, - kim_ccache *out_ccache); - -/*! - * \param io_ccache_iterator a ccache iterator object to be freed. Set to NULL on exit. - * \brief Free memory associated with a ccache iterator. - */ -void kim_ccache_iterator_free (kim_ccache_iterator *io_ccache_iterator); - -/*!@}*/ - -/*! - * \defgroup kim_ccache_reference KIM CCache Reference Documentation - * @{ - */ - -/*! - * \param out_ccache on exit, a new cache object for a ccache containing a newly acquired - * initial credential. Must be freed with kim_ccache_free(). - * \param in_client_identity a client identity to obtain a credential for. Specify KIM_IDENTITY_ANY to - * allow the user to choose. - * \param in_options options to control credential acquisition. - * \note #kim_ccache_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 and store it in a ccache. - */ -kim_error kim_ccache_create_new (kim_ccache *out_ccache, - kim_identity in_client_identity, - kim_options in_options); - -/*! - * \param out_ccache on exit, a new cache object for a ccache containing a newly acquired - * initial credential. Must be freed with kim_ccache_free(). - * \param in_client_identity a client identity to obtain a credential for. Specify KIM_IDENTITY_ANY to - * allow the user to choose. - * \param in_options options to control credential acquisition. - * \param in_password a password to be used while obtaining credentials. - * \note #kim_ccache_create_new_with_password() exists to support - * legacy password-based Kerberos environments. You should not use this - * function unless you know that it will only be used in environments using passwords. - * This function may also present a GUI or command line prompt to obtain - * additional information needed to obtain credentials (eg: SecurID pin). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Acquire a new initial credential and store it in a ccache - * using the provided password.. - */ -kim_error kim_ccache_create_new_with_password (kim_ccache *out_ccache, - kim_identity in_client_identity, - kim_options in_options, - kim_string in_password); - -/*! - * \param out_ccache on exit, a ccache object for a ccache containing a newly acquired - * initial credential. Must be freed with kim_ccache_free(). - * \param in_client_identity a client identity to obtain a credential for. - * \param in_options options to control credential acquisition (if a credential is acquired). - * \note #kim_ccache_create_new_if_needed() 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 Find a ccache containing a valid initial credential in the cache collection, or if - * unavailable, acquire and store a new initial credential. - */ -kim_error kim_ccache_create_new_if_needed (kim_ccache *out_ccache, - kim_identity in_client_identity, - kim_options in_options); - -/*! - * \param out_ccache on exit, a ccache object for a ccache containing a newly acquired - * initial credential. Must be freed with kim_ccache_free(). - * \param in_client_identity a client identity to obtain a credential for. - * \param in_options options to control credential acquisition (if a credential is acquired). - * \param in_password a password to be used while obtaining credentials. - * \note #kim_ccache_create_new_if_needed_with_password() exists to support - * legacy password-based Kerberos environments. You should not use this - * function unless you know that it will only be used in environments using passwords. - * This function may also present a GUI or command line prompt to obtain - * additional information needed to obtain credentials (eg: SecurID pin). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Find a ccache containing a valid initial credential in the cache collection, or if - * unavailable, acquire and store a new initial credential using the provided password. - */ -kim_error kim_ccache_create_new_if_needed_with_password (kim_ccache *out_ccache, - kim_identity in_client_identity, - kim_options in_options, - kim_string in_password); - -/*! - * \param out_ccache on exit, a ccache object for a ccache containing a TGT - * credential. Must be freed with kim_ccache_free(). - * \param in_client_identity a client identity to find a ccache for. If - * \a in_client_identity is #KIM_IDENTITY_ANY, this - * function returns the default ccache - * (ie: is equivalent to #kim_ccache_create_from_default()). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Find a ccache for a client identity in the cache collection. - */ -kim_error kim_ccache_create_from_client_identity (kim_ccache *out_ccache, - kim_identity in_client_identity); - -/*! - * \param out_ccache on exit, a new ccache object containing an initial credential - * for the client identity \a in_identity obtained using in_keytab. - * Must be freed with kim_ccache_free(). - * \param in_identity a client identity to obtain a credential for. Specify NULL for - * the first client 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 and store it in a ccache. - */ -kim_error kim_ccache_create_from_keytab (kim_ccache *out_ccache, - kim_identity in_identity, - kim_options in_options, - kim_string in_keytab); - -/*! - * \param out_ccache on exit, a ccache object for the default ccache. - * Must be freed with kim_ccache_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the default ccache. - */ -kim_error kim_ccache_create_from_default (kim_ccache *out_ccache); - -/*! - * \param out_ccache on exit, a ccache object for the ccache identified by - * \a in_display_name. Must be freed with kim_ccache_free(). - * \param in_display_name a ccache display name string (ie: "TYPE:NAME"). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \note This API is used to obtain a kim_ccache for a ccache name entered by the user. - * \brief Get a ccache for a ccache display name. - */ -kim_error kim_ccache_create_from_display_name (kim_ccache *out_ccache, - kim_string in_display_name); - -/*! - * \param out_ccache on exit, a ccache object for the ccache identified by - * \a in_type and \a in_name. Must be freed with kim_ccache_free(). - * \param in_type a ccache type string. - * \param in_name a ccache name string. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \note This API is provided for backwards compatibilty with applications which are not - * KIM-aware and should be avoided whenever possible. - * \brief Get a ccache for a ccache type and name. - */ -kim_error kim_ccache_create_from_type_and_name (kim_ccache *out_ccache, - kim_string in_type, - kim_string in_name); - -/*! - * \param out_ccache on exit, a new ccache object which is a copy of in_krb5_ccache. - * Must be freed with kim_ccache_free(). - * \param in_krb5_context the krb5 context used to create \a in_krb5_ccache. - * \param in_krb5_ccache a krb5 ccache object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get a ccache for a krb5 ccache. - */ -kim_error kim_ccache_create_from_krb5_ccache (kim_ccache *out_ccache, - krb5_context in_krb5_context, - krb5_ccache in_krb5_ccache); - -/*! - * \param out_ccache on exit, the new ccache object which is a copy of in_ccache. - * Must be freed with kim_ccache_free(). - * \param in_ccache a ccache object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Copy a ccache. - */ -kim_error kim_ccache_copy (kim_ccache *out_ccache, - kim_ccache in_ccache); - -/*! - * \param in_ccache a ccache object. - * \param in_compare_to_ccache a ccache object. - * \param out_comparison on exit, a comparison of \a in_ccache and - * \a in_compare_to_ccache which determines whether - * or not the two ccache objects refer to the same ccache. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Compare ccache objects. - */ -kim_error kim_ccache_compare (kim_ccache in_ccache, - kim_ccache in_compare_to_ccache, - kim_comparison *out_comparison); - -/*! - * \param in_ccache a ccache object. - * \param in_krb5_context a krb5 context which will be used to create out_krb5_ccache. - * \param out_krb5_ccache on exit, a new krb5 ccache object which is a copy of in_ccache. - * Must be freed with krb5_cc_close() or krb5_cc_destroy(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get a krb5 ccache for a ccache. - */ -kim_error kim_ccache_get_krb5_ccache (kim_ccache in_ccache, - krb5_context in_krb5_context, - krb5_ccache *out_krb5_ccache); - -/*! - * \param in_ccache a ccache object. - * \param out_name on exit, the name string of \a in_ccache. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the name of a ccache. - */ -kim_error kim_ccache_get_name (kim_ccache in_ccache, - kim_string *out_name); - -/*! - * \param in_ccache a ccache object. - * \param out_type on exit, the type string of \a in_ccache. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the type of a ccache. - */ -kim_error kim_ccache_get_type (kim_ccache in_ccache, - kim_string *out_type); - -/*! - * \param in_ccache a ccache object. - * \param out_display_name on exit, the type and name of \a in_ccache in a format appropriate for - * display to the user in command line programs. (ie: "<type>:<name>") - * Must be freed with kim_string_free(). - * Note: this string can also be passed to krb5_cc_resolve(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the type and name for a ccache in display format. - */ -kim_error kim_ccache_get_display_name (kim_ccache in_ccache, - kim_string *out_display_name); - -/*! - * \param in_ccache a ccache object. - * \param out_client_identity on exit, an identity object containing the client identity of - * \a in_ccache. 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 for a ccache. - */ -kim_error kim_ccache_get_client_identity (kim_ccache in_ccache, - kim_identity *out_client_identity); - -/*! - * \param in_ccache a ccache object. - * \param out_credential on exit, the first valid credential in \a in_ccache. - * Must be freed with kim_credential_free(). Set to NULL - * if you only want return value, not the actual credential. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the first valid credential in a ccache. - * \note This function prefers valid TGT credentials. If there are only non-valid TGTs - * in the ccache, it will always return an error. However, if there are no - * TGTs at all, it will return the first valid non-TGT credential. If you only want - * TGTs, use kim_credential_is_tgt() to verify that \a out_credential is a tgt. - */ -kim_error kim_ccache_get_valid_credential (kim_ccache in_ccache, - kim_credential *out_credential); - -/*! - * \param in_ccache a ccache object. - * \param out_state on exit, the state of the credentials in \a in_ccache. - * 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 the credentials in a ccache (valid, expired, postdated, etc). - * \note This function prefers TGT credentials. If there are any TGTs in the - * ccache, it will always return their state. However, if there are no - * TGTs at all, it will return the state of the first non-TGT credential. - */ -kim_error kim_ccache_get_state (kim_ccache in_ccache, - kim_credential_state *out_state); - -/*! - * \param in_ccache a ccache object. - * \param out_start_time on exit, the time when the credentials in \a in_ccache - * become 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 in the ccache become valid. - */ -kim_error kim_ccache_get_start_time (kim_ccache in_ccache, - kim_time *out_start_time); - -/*! - * \param in_ccache a ccache object. - * \param out_expiration_time on exit, the time when the credentials in - * \a in_ccache 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 in the ccache will expire. - */ -kim_error kim_ccache_get_expiration_time (kim_ccache in_ccache, - kim_time *out_expiration_time); - -/*! - * \param in_ccache a ccache object. - * \param out_renewal_expiration_time on exit, the time when the credentials in \a in_ccache - * 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 in the ccache will no longer be renewable. - */ -kim_error kim_ccache_get_renewal_expiration_time (kim_ccache in_ccache, - kim_time *out_renewal_expiration_time); - -/*! - * \param in_ccache a ccache object. - * \param out_options on exit, an options object reflecting the ticket - * options of the credentials in \a in_ccache. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get a kim_options object based on a ccache's credential attributes. - */ -kim_error kim_ccache_get_options (kim_ccache in_ccache, - kim_options *out_options); - -/*! - * \param io_ccache a ccache object which will be set to the default ccache. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \note This API is provided for backwards compatibilty with applications which are not - * KIM-aware and should be avoided whenever possible. - * \brief Set a ccache to the default ccache. - */ -kim_error kim_ccache_set_default (kim_ccache io_ccache); - -/*! - * \param in_ccache a ccache object containing the 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 the TGT in a ccache. - */ -kim_error kim_ccache_verify (kim_ccache in_ccache, - kim_identity in_service_identity, - kim_string in_keytab, - kim_boolean in_fail_if_no_service_key); - -/*! - * \param in_ccache a ccache object containing a TGT to be renewed. - * \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 Renew the TGT in a ccache. - */ -kim_error kim_ccache_renew (kim_ccache in_ccache, - kim_options in_options); - -/*! - * \param in_ccache a ccache object containing a TGT to be validated. - * \param in_options initial credential options. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Validate the TGT in a ccache. - */ -kim_error kim_ccache_validate (kim_ccache in_ccache, - kim_options in_options); - -/*! - * \param io_ccache a ccache object to be destroyed. Set to NULL on exit. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Remove a ccache from the cache collection. - * \note Frees memory associated with the ccache. Do not call kim_ccache_free() - * after calling this function. - */ -kim_error kim_ccache_destroy (kim_ccache *io_ccache); - -/*! - * \param io_ccache a ccache object to be freed. Set to NULL on exit. - * \brief Free memory associated with a ccache. - */ -void kim_ccache_free (kim_ccache *io_ccache); - -/*!@}*/ - -#ifdef __cplusplus -} -#endif - -#endif /* KIM_CCACHE_H */ diff --git a/src/include/kim/kim_credential.h b/src/include/kim/kim_credential.h deleted file mode 100644 index bf065a8d2..000000000 --- a/src/include/kim/kim_credential.h +++ /dev/null @@ -1,569 +0,0 @@ -/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ -/* - * Copyright 2005-2006 Massachusetts Institute of Technology. - * All Rights Reserved. - * - * Export of this software from the United States of America may - * require a specific license from the United States Government. - * It is the responsibility of any person or organization contemplating - * export to obtain such a license before exporting. - * - * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - * distribute this software and its documentation for any purpose and - * without fee is hereby granted, provided that the above copyright - * notice appear in all copies and that both that copyright notice and - * this permission notice appear in supporting documentation, and that - * the name of M.I.T. not be used in advertising or publicity pertaining - * to distribution of the software without specific, written prior - * permission. Furthermore if you modify this software you must label - * your software as modified software and not distribute it in such a - * fashion that it might be confused with the original M.I.T. software. - * M.I.T. makes no representations about the suitability of - * this software for any purpose. It is provided "as is" without express - * or implied warranty. - */ - -#ifndef KIM_CREDENTIAL_H -#define KIM_CREDENTIAL_H - -#ifdef __cplusplus -extern "C" { -#endif - -#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. - * - * For legacy password-based Kerberos environments KIM also provides - * #kim_credential_create_new_with_password(). You should not use this - * function unless you know that it will only be used in environments using - * passwords. Otherwise users without passwords may be prompted for them. - * - * 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_get_state() - * returns a #kim_credential_state containing the state of the credential. - * Possible values are: - * * kim_credentials_state_valid - * * kim_credentials_state_expired - * * kim_credentials_state_not_yet_valid - * * kim_credentials_state_needs_validation - * * kim_credentials_state_address_mismatch - * - * \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 a renewal expiration time of 0. - * - * \li #kim_credential_get_options() - * returns a kim_options object with the credential options of the - * credential. This function is intended to be used when adding - * an identity with existing credentials to the favorite identities list. - * By passing in the options returned by this call, future requests for the - * favorite identity will use the same credential options. - * - * - * 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 #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 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. - * \param in_password a password to be used while obtaining the credential. - * \note #kim_credential_create_new_with_password() exists to support - * legacy password-based Kerberos environments. You should not use this - * function unless you know that it will only be used in environments using passwords. - * This function may also present a GUI or command line prompt to obtain - * additional information needed to obtain credentials (eg: SecurID pin). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Acquire a new initial credential using the provided password. - * \sa kim_ccache_create_new - */ -kim_error kim_credential_create_new_with_password (kim_credential *out_credential, - kim_identity in_client_identity, - kim_options in_options, - kim_string in_password); - -/*! - * \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. If - * credentials are not renewable at all, returns 0. - * \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 out_options on exit, an options object reflecting the ticket - * options of \a in_credential. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get a kim_options object based on a credential's attributes. - */ -kim_error kim_credential_get_options (kim_credential in_credential, - kim_options *out_options); - -/*! - * \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); - -/*!@}*/ - - -#ifdef __cplusplus -} -#endif - -#endif /* KIM_CREDENTIAL_H */ diff --git a/src/include/kim/kim_identity.h b/src/include/kim/kim_identity.h deleted file mode 100644 index caed0524a..000000000 --- a/src/include/kim/kim_identity.h +++ /dev/null @@ -1,287 +0,0 @@ -/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ -/* - * Copyright 2005-2006 Massachusetts Institute of Technology. - * All Rights Reserved. - * - * Export of this software from the United States of America may - * require a specific license from the United States Government. - * It is the responsibility of any person or organization contemplating - * export to obtain such a license before exporting. - * - * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - * distribute this software and its documentation for any purpose and - * without fee is hereby granted, provided that the above copyright - * notice appear in all copies and that both that copyright notice and - * this permission notice appear in supporting documentation, and that - * the name of M.I.T. not be used in advertising or publicity pertaining - * to distribution of the software without specific, written prior - * permission. Furthermore if you modify this software you must label - * your software as modified software and not distribute it in such a - * fashion that it might be confused with the original M.I.T. software. - * M.I.T. makes no representations about the suitability of - * this software for any purpose. It is provided "as is" without express - * or implied warranty. - */ - -#ifndef KIM_IDENTITY_H -#define KIM_IDENTITY_H - -#ifdef __cplusplus -extern "C" { -#endif - -#include <kim/kim_types.h> -#include <krb5.h> -#include <gssapi/gssapi.h> - -/*! - * \ingroup kim_types_reference - * Constant to specify any Kerberos identity is acceptable. - */ -#define KIM_IDENTITY_ANY ((kim_identity) NULL) - -/*! - * \page kim_identity_overview KIM Identity Overview - * - * \section kim_identity_introduction Introduction - * - * Identities in Kerberos are named by "principals". These identies may be people (users) - * or services (a server running on a host). When Kerberos issues credentials which - * authenticate one identity to another, the identity being authenticated is called - * the "client identity" and the identity being authenticated to is called the - * "service identity". - * - * Kerberos identities are made up of one or more components, as well as the Kerberos realm - * the entity belongs to. For client identities the first component is usually the client - * username (eg: "jdoe"). For service identities the first component is the name of the - * service (eg: "imap"). - * - * Kerberos identities have both a binary (opaque) representation and also a string - * representation. The string representation consists of the components separated by '/' - * followed by an '@' and then the realm. For example, the identity "jdoe/admin@EXAMPLE.COM" - * represents John Doe's administrator identity at the realm EXAMPLE.COM. Note that - * identity components may contain both '/' and '@' characters. When building a - * identity from its string representation these syntactic characters must be escaped - * with '\'. - * - * - * \section kim_identity_create_display Creating and Displaying Identities - * - * KIM Identities can be generated from components, their escaped string representation - * or from a krb5_principal. Once you have a KIM identity object, you can also get - * the component, string or krb5_principal representations back out: - * - * \li #kim_identity_create_from_components() creates an identity object from a list of components. - * \li #kim_identity_get_number_of_components() returns the number of components in an identity object. - * \li #kim_identity_get_component_at_index() return a component of an identity object. - * \li #kim_identity_get_realm() returns the identity's realm. - * - * \li #kim_identity_create_from_string() generates an identity object from an escaped string representation. - * \li #kim_identity_get_string() returns the identity's escaped string representation. - * \li #kim_identity_get_display_string() returns a non-escaped string for display to the user. - * This string cannot be passed into #kim_identity_create_from_string(). - * - * \li #kim_identity_create_from_krb5_principal() generates an identity object from a krb5_principal object. - * \li #kim_identity_get_krb5_principal() returns a krb5_principal object for an identity object. - * - * \note If you need to know if two identity objects refer to the same entity, use #kim_identity_compare(). - * - * - * \section kim_identity_selection Choosing a Client Identity - * - * Unfortunately most of the time applications don't know what client identity to use. - * Users may have identities for multiple Kerberos realms, as well as multiple identities - * in a single realm (such as a user and administrator identity). - * - * To solve this problem, #kim_selection_hints_get_identity() takes information - * from the application in the form of a selection hints object and returns the best - * matching client identity, if one is available. See \ref kim_selection_hints_overview - * for more information. - * - * - * \section kim_identity_password Changing a Identity's Password - * - * Many Kerberos sites use passwords for user accounts. Because passwords may be - * stolen or compromised, they must be frequently changed. KIM provides APIs to - * change the identity's password directly, and also handles changing the identity's - * password when it has expired. - * - * #kim_identity_change_password() presents a user interface to obtain the old and - * new passwords from the user. - * - * \note Not all identities have a password. Some sites use certificates (pkinit) - * and in the future there may be other authentication mechanisms (eg: smart cards). - * - * See \ref kim_identity_reference for information on specific APIs. - */ - -/*! - * \defgroup kim_identity_reference KIM Identity Reference Documentation - * @{ - */ - -/*! - * \param out_identity on exit, a new identity object. Must be freed with kim_identity_free(). - * \param in_string a string representation of a Kerberos identity. - * Special characters such as '/' and '@' must be escaped with '\'. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Create a identity from a string. - */ -kim_error kim_identity_create_from_string (kim_identity *out_identity, - kim_string in_string); - -/*! - * \param out_identity on exit, a new identity object. Must be freed with kim_identity_free(). - * \param in_realm a string representation of a Kerberos realm. - * \param in_1st_component a string representing the first component of the identity. - * \param ... zero or more strings of type kim_string_t representing additional components - * of the identity followed by a terminating NULL. Components will be assembled in - * order (ie: the 4th argument to kim_identity_create_from_components() will be - * the 2nd component of the identity). - * \note The last argument must be a NULL or kim_identity_create_from_components() may crash. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Create a identity from a realm and component strings. - */ -kim_error kim_identity_create_from_components (kim_identity *out_identity, - kim_string in_realm, - kim_string in_1st_component, - ...); - -/*! - * \param out_identity on exit, a new identity object which is a copy of \a in_krb5_principal. - * Must be freed with kim_identity_free(). - * \param in_krb5_context the krb5 context used to create \a in_krb5_principal. - * \param in_krb5_principal a krb5 principal object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Create an identity object from a krb5_principal. - */ -kim_error kim_identity_create_from_krb5_principal (kim_identity *out_identity, - krb5_context in_krb5_context, - krb5_principal in_krb5_principal); - -/*! - * \param out_identity on exit, a new identity object which is a copy of \a in_identity. - * Must be freed with kim_identity_free(). - * \param in_identity an identity object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Copy an identity object. - */ -kim_error kim_identity_copy (kim_identity *out_identity, - kim_identity in_identity); - - -/*! - * \param in_identity an identity object. - * \param in_compare_to_identity an identity object. - * \param out_comparison on exit, a comparison of \a in_identity and - * \a in_compare_to_identity which determines whether - * or not the two identities are equivalent and their - * sort order (for display to the user) if they are not. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Compare identity objects for equivalency. - */ -kim_error kim_identity_compare (kim_identity in_identity, - kim_identity in_compare_to_identity, - kim_comparison *out_comparison); -/*! - * \param in_identity an identity object. - * \param out_string on exit, a string representation of \a in_identity. - * Must be freed with kim_string_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the string representation of a identity. - * \note Special characters such as '@' and '/' will be escaped with '\'. - */ -kim_error kim_identity_get_string (kim_identity in_identity, - kim_string *out_string); - - -/*! - * \param in_identity an identity object. - * \param out_display_string on exit, a string representation of \a in_identity appropriate for - * display to the user. Must be freed with kim_string_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get a human-readable string representation of an identity. - * \note Special characters such as '/' and '@' are \em not escaped with '\'. As a result the - * string returned from this function cannot be used with kim_identity_create_from_string() - * because it does not uniquely specify a principal. - * The result of this function should \em only be used to display to the user. - */ -kim_error kim_identity_get_display_string (kim_identity in_identity, - kim_string *out_display_string); - -/*! - * \param in_identity an identity object. - * \param out_realm_string on exit, a string representation of \a in_identity's realm. - * Must be freed with kim_string_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the realm string of an identity. - */ -kim_error kim_identity_get_realm (kim_identity in_identity, - kim_string *out_realm_string); - -/*! - * \param in_identity an identity object. - * \param out_number_of_components on exit the number of components in \a in_identity. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the number of components of an identity. - */ -kim_error kim_identity_get_number_of_components (kim_identity in_identity, - kim_count *out_number_of_components); - -/*! - * \param in_identity an identity object. - * \param in_index the index of the desired component. Component indexes start at 0. - * \param out_component_string on exit, a string representation of the component in \a in_identity - * specified by \a in_index. Must be freed with kim_string_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the Nth component of an identity. - */ -kim_error kim_identity_get_component_at_index (kim_identity in_identity, - kim_count in_index, - kim_string *out_component_string); - -/*! - * \param in_identity an identity object. - * \param out_components on exit, a string of the non-realm components of \a in_identity - * separated by '/' characters. Must be freed with kim_string_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get a display string of the non-realm components of an identity. - */ -kim_error kim_identity_get_components_string (kim_identity in_identity, - kim_string *out_components); - -/*! - * \param in_identity an identity object. - * \param in_krb5_context a krb5 context object. - * \param out_krb5_principal on exit, a krb5_principal representation of \a in_identity - * allocated with \a in_krb5_context. Must be freed with - * krb5_free_principal() using \a in_krb5_context. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the krb5_principal representation of an identity. - */ -kim_error kim_identity_get_krb5_principal (kim_identity in_identity, - krb5_context in_krb5_context, - krb5_principal *out_krb5_principal); - -/*! - * \param in_identity an identity object whose password will be changed. - * \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. - */ -kim_error kim_identity_change_password (kim_identity in_identity); - -/*! - * \param io_identity the identity object to be freed. Set to NULL on exit. - * \brief Free memory associated with an identity. - */ -void kim_identity_free (kim_identity *io_identity); - -/*!@}*/ - -#ifdef __cplusplus -} -#endif - -#endif /* KIM_IDENTITY_H */ diff --git a/src/include/kim/kim_library.h b/src/include/kim/kim_library.h deleted file mode 100644 index c84063733..000000000 --- a/src/include/kim/kim_library.h +++ /dev/null @@ -1,84 +0,0 @@ -/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ -/* - * Copyright 2005-2008 Massachusetts Institute of Technology. - * All Rights Reserved. - * - * Export of this software from the United States of America may - * require a specific license from the United States Government. - * It is the responsibility of any person or organization contemplating - * export to obtain such a license before exporting. - * - * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - * distribute this software and its documentation for any purpose and - * without fee is hereby granted, provided that the above copyright - * notice appear in all copies and that both that copyright notice and - * this permission notice appear in supporting documentation, and that - * the name of M.I.T. not be used in advertising or publicity pertaining - * to distribution of the software without specific, written prior - * permission. Furthermore if you modify this software you must label - * your software as modified software and not distribute it in such a - * fashion that it might be confused with the original M.I.T. software. - * M.I.T. makes no representations about the suitability of - * this software for any purpose. It is provided "as is" without express - * or implied warranty. - */ - - -#ifndef KIM_LIBRARY_H -#define KIM_LIBRARY_H - -#include <kim/kim.h> - -/*! - * \defgroup kim_library_reference KIM Library Documentation - * @{ - */ - -/*! Do not present user interface */ -#define KIM_UI_ENVIRONMENT_NONE 0 -/*! Automatically determine what user interface is appropriate (default). */ -#define KIM_UI_ENVIRONMENT_AUTO 1 -/*! Present a graphical user interface */ -#define KIM_UI_ENVIRONMENT_GUI 2 -/*! Present a command line user interface */ -#define KIM_UI_ENVIRONMENT_CLI 3 - -/*! An integer describing the type of user interface to use. */ -typedef int kim_ui_environment; - -/*! - * \param in_ui_environment an integer value describing the type of user interface to use. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \note Set to KIM_UI_ENVIRONMENT_AUTO by default. - * \brief Tell KIM how to present UI from your application. - */ -kim_error kim_library_set_ui_environment (kim_ui_environment in_ui_environment); - -/*! - * \param in_allow_access a boolean containing whether or not to touch the user's home directory. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \note This API is usually used for Kerberos authenticated home directories to prevent a deadlock. - * \brief Tells KIM whether or not it is allowed to touch the user's home directory. - */ -kim_error kim_library_set_allow_home_directory_access (kim_boolean in_allow_access); - -/*! - * \param in_allow_automatic_prompting a boolean containing whether or not to prompt automatically. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Tells KIM whether or not it is allowed to automatically present user interface. - */ -kim_error kim_library_set_allow_automatic_prompting (kim_boolean in_allow_automatic_prompting); - -/*! - * \param in_application_name a string containing the localized name of your application. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \note On many operating systems KIM can determine the caller's application - * name automatically. This call exists for applications to use when those - * mechanisms fail or do not exist. - * \brief Set the name of your application for KIM to use for user interface. - */ -kim_error kim_library_set_application_name (kim_string in_application_name); - -/*!@}*/ - -#endif /* KIM_LIBRARY_H */ diff --git a/src/include/kim/kim_options.h b/src/include/kim/kim_options.h deleted file mode 100644 index 2b1343197..000000000 --- a/src/include/kim/kim_options.h +++ /dev/null @@ -1,432 +0,0 @@ -/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ -/* - * Copyright 2005-2006 Massachusetts Institute of Technology. - * All Rights Reserved. - * - * Export of this software from the United States of America may - * require a specific license from the United States Government. - * It is the responsibility of any person or organization contemplating - * export to obtain such a license before exporting. - * - * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - * distribute this software and its documentation for any purpose and - * without fee is hereby granted, provided that the above copyright - * notice appear in all copies and that both that copyright notice and - * this permission notice appear in supporting documentation, and that - * the name of M.I.T. not be used in advertising or publicity pertaining - * to distribution of the software without specific, written prior - * permission. Furthermore if you modify this software you must label - * your software as modified software and not distribute it in such a - * fashion that it might be confused with the original M.I.T. software. - * M.I.T. makes no representations about the suitability of - * this software for any purpose. It is provided "as is" without express - * or implied warranty. - */ - -#ifndef KIM_OPTIONS_H -#define KIM_OPTIONS_H - -#ifdef __cplusplus -extern "C" { -#endif - -#include <kim/kim_types.h> - -/*! - * \addtogroup kim_types_reference - * @{ - */ - -/*! - * Specifies the user's default options. - */ -#define KIM_OPTIONS_DEFAULT ((kim_options) NULL) - -/*! - * Specifies that credentials should be valid immediately. - */ -#define KIM_OPTIONS_START_IMMEDIATELY ((kim_time_t) 0) - -/*! @} */ - -/*! - * \page kim_options_overview KIM Options Overview - * - * \section kim_options_introduction Introduction - * - * Kerberos Identity Management Options (kim_options_t) allows you to control how - * the Kerberos library obtains credentials. When the options structure is initialized with - * #kim_options_create(), each option is filled in with a default value which can then be modified - * with the kim_options_set_*() APIs. If you only want to use the default values, you may pass - * #KIM_OPTIONS_DEFAULT into any KIM function that takes a kim_options_t. - * - * 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_properties Options for Controlling Credential Properties - * - * Kerberos credentials have a number of different properties which can be requested - * when credentials are acquired. These properties control when and for how long the - * credentials are valid and what you can do with them. - - * Note that setting these properties in the KIM options only changes what the Kerberos - * libraries \em request from the KDC. The KDC itself may choose not to honor your - * requested properties if they violate the site security policy. For example, most sites - * place an upper bound on how long credentials may be valid. If you request a credential - * lifetime longer than this upper bound, the KDC may return credentials with a shorter - * lifetime than you requested. - * - * \subsection kim_options_lifetimes Credential Lifetime - * - * Kerberos credentials have start time and a lifetime during which they are valid. - * Once the lifetime has passed, credentials "expire" and can no longer be used. - * - * The requested credential start time can be set with #kim_options_set_start_time() - * and examined with #kim_options_get_start_time(). The requested credential - * lifetime can be set with #kim_options_set_lifetime() and examined with - * #kim_options_get_lifetime(). - * - * \subsection kim_options_renewable Renewable Credentials - * - * Credentials with very long lifetimes are more convenient since the user does not - * have authenticate as often. Unfortunately they are also a higher security - * risk: if credentials are stolen they can be used until they expire. - * Credential renewal exists to compromise between these two conflicting goals. - * - * Renewable credentials are TGT credentials which can be used to obtain new - * TGT credentials without reauthenticating. By regularly renewing credentials - * the KDC has an opportunity to check to see if the client's credentials have been - * reported stolen and refuse to renew them. Renewable credentials have a "renewal - * lifetime" during which credentials can be renewed. This lifetime is relative - * to the original credential start time. If credentials are renewed shortly before - * the end of the renewal lifetime, their lifetime will be capped to the end of the - * renewal lifetime. - * - * Note that credentials must be valid to be renewed and therefore may not be - * an appropriate solution for all use cases. Sites which use renewable - * credentials often create helper processes running as the user which will - * automatically renew the user's credentials when they get close to expiration. - * - * Use #kim_options_set_renewable() to change whether or not the Kerberos libraries - * request renewable credentials and #kim_options_get_renewable() to find out the - * current setting. Use #kim_options_set_renewal_lifetime() to change the requested - * renewal lifetime and #kim_options_get_renewal_lifetime() to find out the current - * value. - * - * \subsection kim_options_addressless Addressless Credentials - * - * Traditionally Kerberos used the host's IP address as a mechanism to restrict - * the user's credentials to a specific host, thus making it harder to use stolen - * credentials. When authenticating to a remote service with credentials containing - * addresses, the remote service verifies that the client's IP address is one of the - * addresses listed in the credential. Unfortunately, modern network technologies - * such as NAT rewrite the IP address in transit, making it difficult to use - * credentials with addresses in them. As a result, most Kerberos sites now obtain - * addressless credentials. - * - * Use #kim_options_set_addressless() to change whether or not the Kerberos libraries - * request addressless credentials. Use #kim_options_get_addressless() to find out the - * current setting. - * - * \subsection kim_options_forwardable Forwardable Credentials - * - * Forwardable credentials are TGT credentials which can be forwarded to a service - * you have authenticated to. If the credentials contain IP addresses, the addresses - * are changed to reflect the service's IP address. Credential forwarding is most - * commonly used for Kerberos-authenticated remote login services. By forwarding - * TGT credentials through the remote login service, the user's credentials will - * appear on the remote host when the user logs in. - * - * The forwardable flag only applies to TGT credentials. - * - * Use #kim_options_set_forwardable() to change whether or not the Kerberos libraries - * request forwardable credentials. Use #kim_options_get_forwardable() to find out the - * current setting. - * - * \subsection kim_options_proxiable Proxiable Credentials - * - * Proxiable credentials are similar to forwardable credentials except that instead of - * forwarding the a TGT credential itself, a service credential is forwarded - * instead. Using proxiable credentials, a user can permit a service to perform - * a specific task as the user using one of the user's service credentials. - * - * Like forwardability, the proxiable flag only applies to TGT credentials. Unlike - * forwarded credentials, the IP address of proxiable credentials are not modified for - * the service when being proxied. This can be solved by also requesting addressless - * credentials. - * - * Use #kim_options_set_proxiable() to change whether or not the Kerberos libraries - * request proxiable credentials. Use #kim_options_get_proxiable() to find out the - * current setting. - * - * \subsection kim_options_service_name Service Name - * - * Normally users acquire TGT credentials (ie "ticket granting tickets") and then - * use those credentials to acquire service credentials. This allows Kerberos to - * provide single sign-on while still providing mutual authentication to services. - * However, sometimes you just want an initial credential for a service. KIM - * options allows you to set the service name with - * #kim_options_set_service_name() and query it with - * #kim_options_get_service_name(). - * - * See \ref kim_options_reference for information on specific APIs. - */ - -/*! - * \defgroup kim_options_reference KIM Options Reference Documentation - * @{ - */ - -/*! - * \param out_options on exit, a new options object. Must be freed with kim_options_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Create new options with default values. - */ -kim_error kim_options_create (kim_options *out_options); - -/*! - * \param out_options on exit, a new options object which is a copy of \a in_options. - * Must be freed with kim_options_free(). If passed KIM_OPTIONS_DEFAULT - * will set \a out_options to KIM_OPTIONS_DEFAULT. - * \param in_options a options object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Copy options. - */ -kim_error kim_options_copy (kim_options *out_options, - kim_options in_options); - -/*! - * \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 - * immediately. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the date when a credential should become valid. - * \note When using a start time in the future, once the start time has been reached the credential - * must be validated before it can be used. - * \par Default value - * 0, indicating "now". The credential will be valid immediately. - * \sa kim_options_get_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate() - */ -kim_error kim_options_set_start_time (kim_options io_options, - kim_time in_start_time); - -/*! - * \param in_options an options object. - * \param out_start_time on exit, the start date (in seconds since January 1, 1970) specified by - * \a in_options. #KIM_OPTIONS_START_IMMEDIATELY indicates the credential - * will be valid immediately. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the date when a credential should become valid. - * \note When using a start time in the future, once the start time has been reached the credential - * must be validated before it can be used. - * \par Default value - * 0, indicating "now". The credential will be valid immediately. - * \sa kim_options_set_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate() - */ -kim_error kim_options_get_start_time (kim_options in_options, - kim_time *out_start_time); - -/*! - * \param io_options an options object to modify. - * \param in_lifetime a lifetime duration (in seconds). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the duration during which a credential should be valid. - * \note KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours). - * As a result the credential will actually have a lifetime which is the minimum of - * \a in_lifetime and the KDC's maximum allowed lifetime. - * \sa kim_options_get_lifetime() - * \par Default value - * Read from the user's preferences and the Kerberos configuration. 10 hours if unspecified. - */ -kim_error kim_options_set_lifetime (kim_options io_options, - kim_lifetime in_lifetime); - -/*! - * \param in_options an options object. - * \param out_lifetime on exit, the lifetime duration (in seconds) specified in \a in_options. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the duration during which an acquired credential should be valid. - * \note KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours). - * As a result the credential will actually have a lifetime which is the minimum of - * \a in_lifetime and the KDC's maximum allowed lifetime. - * \par Default value - * Read from the user's preferences and the Kerberos configuration. 10 hours if unspecified. - * \sa kim_options_set_lifetime() - */ -kim_error kim_options_get_lifetime (kim_options in_options, - kim_lifetime *out_lifetime); - -/*! - * \param io_options an options object to modify. - * \param in_renewable a boolean value indicating whether or not to request a renewable - * credential. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set whether or not to request a renewable credential. - * \par Default value - * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. - * \sa kim_options_get_renewable() - */ -kim_error kim_options_set_renewable (kim_options io_options, - kim_boolean in_renewable); - -/*! - * \param in_options an options object. - * \param out_renewable on exit, a boolean value indicating whether or \a in_options will - * request a renewable credential. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get whether or not to request a renewable credential. - * \par Default value - * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. - * \sa kim_options_set_renewable() - */ -kim_error kim_options_get_renewable (kim_options in_options, - kim_boolean *out_renewable); - -/*! - * \param io_options an options object to modify. - * \param in_renewal_lifetime a renewal lifetime duration (in seconds). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the duration during which a valid credential should be renewable. - * \note KDCs have a maximum allowed renewal lifetime per identity (usually 10 to 21 hours). - * As a result the credential will actually have a lifetime which is the minimum of - * \a in_lifetime and the KDC's maximum allowed lifetime. - * \par Default value - * Read from the user's preferences and the Kerberos configuration. 7 days if unspecified. - * \sa kim_options_get_renewal_lifetime(), kim_identity_renew(), kim_credential_renew(), kim_ccache_renew() - */ -kim_error kim_options_set_renewal_lifetime (kim_options io_options, - kim_lifetime in_renewal_lifetime); - -/*! - * \param in_options an options object. - * \param out_renewal_lifetime on exit, the renewal lifetime duration (in seconds) specified - * in \a in_options. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the duration during which a valid credential should be renewable. - * \note KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours). - * As a result the credential will actually have a lifetime which is the minimum of - * \a in_lifetime and the KDC's maximum allowed lifetime. - * \par Default value - * Read from the user's preferences and the Kerberos configuration. 7 days if unspecified. - * \sa kim_options_set_renewal_lifetime(), kim_identity_renew(), kim_credential_renew(), kim_ccache_renew() - */ -kim_error kim_options_get_renewal_lifetime (kim_options in_options, - kim_lifetime *out_renewal_lifetime); - -/*! - * \param io_options an options object to modify. - * \param in_forwardable a boolean value indicating whether or not to request a forwardable - * credential. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set whether or not to request a forwardable credential. - * \par Default value - * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. - * \sa kim_options_get_forwardable() - */ -kim_error kim_options_set_forwardable (kim_options io_options, - kim_boolean in_forwardable); - -/*! - * \param in_options an options object. - * \param out_forwardable on exit, a boolean value indicating whether or \a in_options will - * request a forwardable credential. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get whether or not to request a forwardable credential. - * \par Default value - * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. - * \sa kim_options_set_forwardable() - */ -kim_error kim_options_get_forwardable (kim_options in_options, - kim_boolean *out_forwardable); - -/*! - * \param io_options an options object to modify. - * \param in_proxiable a boolean value indicating whether or not to request a proxiable - * credential. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set whether or not to request a proxiable credential. - * \par Default value - * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. - * \sa kim_options_get_proxiable() - */ -kim_error kim_options_set_proxiable (kim_options io_options, - kim_boolean in_proxiable); - -/*! - * \param in_options an options object. - * \param out_proxiable on exit, a boolean value indicating whether or \a in_options will - * request a proxiable credential. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get whether or not to request a proxiable credential. - * \par Default value - * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. - * \sa kim_options_set_proxiable() - */ -kim_error kim_options_get_proxiable (kim_options in_options, - kim_boolean *out_proxiable); - -/*! - * \param io_options an options object to modify. - * \param in_addressless a boolean value indicating whether or not to request an addressless - * credential. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set whether or not to request an addressless credential. - * \par Default value - * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. - * \sa kim_options_get_addressless() - */ -kim_error kim_options_set_addressless (kim_options io_options, - kim_boolean in_addressless); - -/*! - * \param in_options an options object. - * \param out_addressless on exit, a boolean value indicating whether or \a in_options will - * request an addressless credential. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get whether or not to request an addressless credential. - * \par Default value - * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. - * \sa kim_options_set_addressless() - */ -kim_error kim_options_get_addressless (kim_options in_options, - kim_boolean *out_addressless); - -/*! - * \param io_options an options object to modify. - * \param in_service_name a service name. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the service name to request a credential for. - * \par Default value - * NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service. - * \sa kim_options_get_service_name() - */ -kim_error kim_options_set_service_name (kim_options io_options, - kim_string in_service_name); - -/*! - * \param in_options an options object. - * \param out_service_name on exit, the service name specified in \a in_options. - * Must be freed with kim_string_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the service name to request a credential for. - * \par Default value - * NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service. - * \sa kim_options_set_service_name() - */ -kim_error kim_options_get_service_name (kim_options in_options, - kim_string *out_service_name); - -/*! - * \param io_options the options object to be freed. Set to NULL on exit. - * \brief Free memory associated with an options object. - */ -void kim_options_free (kim_options *io_options); - -/*!@}*/ - -#ifdef __cplusplus -} -#endif - -#endif /* KIM_OPTIONS_H */ diff --git a/src/include/kim/kim_preferences.h b/src/include/kim/kim_preferences.h deleted file mode 100644 index fd3293319..000000000 --- a/src/include/kim/kim_preferences.h +++ /dev/null @@ -1,420 +0,0 @@ -/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ -/* - * Copyright 2005-2006 Massachusetts Institute of Technology. - * All Rights Reserved. - * - * Export of this software from the United States of America may - * require a specific license from the United States Government. - * It is the responsibility of any person or organization contemplating - * export to obtain such a license before exporting. - * - * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - * distribute this software and its documentation for any purpose and - * without fee is hereby granted, provided that the above copyright - * notice appear in all copies and that both that copyright notice and - * this permission notice appear in supporting documentation, and that - * the name of M.I.T. not be used in advertising or publicity pertaining - * to distribution of the software without specific, written prior - * permission. Furthermore if you modify this software you must label - * your software as modified software and not distribute it in such a - * fashion that it might be confused with the original M.I.T. software. - * M.I.T. makes no representations about the suitability of - * this software for any purpose. It is provided "as is" without express - * or implied warranty. - */ - -#ifndef KIM_PREFERENCES_H -#define KIM_PREFERENCES_H - -#ifdef __cplusplus -extern "C" { -#endif - -#include <kim/kim_types.h> - -/*! - * \page kim_preferences_overview KIM Preferences Overview - * - * \section kim_preferences_introduction Introduction - * - * In addition to the site preferences stored in the Kerberos configuration, users may also - * want to have their own personal preferences for controlling credential acquisition. - * As a result, KIM provides user preferences for initial credential options and - * user interface behavior such as the default client identity and the favorite identities list. - * - * \section kim_preferences_edit Viewing and Editing the Preferences - * - * In order to view and edit the user's preferences, call #kim_preferences_create() to acquire a - * preferences object containing the user's preferences. You can examine preferences - * with the functions starting with "kim_preferences_get_" and change preferences with - * the functions starting with "kim_preferences_set_". Once you are done making changes, - * you can write changes back out to the user's preferences with #kim_preferences_synchronize(). - * - * \note The location of user preferences and the semantics of - * preference synchronization is platform-specific. Where possible KIM will use - * platform-specific preference mechanisms. - * - * \section kim_preferences_options Initial Credential Options Preferences - * - * KIM provides user preferences for initial credential options. These - * are the options #kim_options_create() will use when creating a new KIM - * options object. They are also the options specified by KIM_OPTIONS_DEFAULT. - * You can view and edit the initial credential options using - * #kim_preferences_get_options() and #kim_preferences_set_options(). - * - * \note Not all credential options in the kim_options_t object have corresponding - * user preferences. For example, the prompt callback function is not stored - * in the user preferences since it has no meaning outside of the current - * application. Some options which are not currently stored in the - * preferences may be stored there in the future. - * - * If you are implementing a user interface for credentials acquisition, - * you should be aware that KIM has a user preference to manage the initial - * credential options preferences. If the user successfully acquires credentials - * with non-default options and #kim_preferences_get_remember_options() is set - * to TRUE, you should store the options used to get credentials with - * #kim_preferences_set_options(). - * - * \section kim_preferences_client_identity Client Identity Preferences - * - * KIM also provides user preferences for the default client identity. - * This identity is used whenever KIM needs to display a graphical dialog for - * credential acquisition but does not know what client identity to use. - * You can view and edit the default client identity using - * #kim_preferences_get_client_identity() and - * #kim_preferences_set_client_identity(). - * - * If you are implementing a user interface for credentials acquisition, - * you should be aware that KIM has a user preference to manage - * the client identity preferences. If the user successfully acquires credentials - * with non-default options and #kim_preferences_get_remember_client_identity() is - * set to TRUE, you should store the client identity for which credentials were - * acquired using #kim_preferences_set_client_identity(). - * - * \section kim_preferences_favorite_identities Favorite Identities Preferences - * - * As Kerberos becomes more widespread, the number of possible Kerberos - * identities and realms a user might want to use will become very large. - * Sites may list hundreds of realms in their Kerberos configuration files. - * In addition, sites may wish to use DNS SRV records to avoid having to list - * all the realms they use in their Kerberos configuration. As a result, the - * list of realms in the Kerberos configuration may be exceedingly large and/or - * incomplete. Users may also use multiple identities from the same realm. - * - * On platforms which use a GUI to acquire credentials, the KIM would like - * to to display a list of identities for the user to select from. Depending on - * what is appropriate for the platform, identities may be displayed in a popup - * menu or other list. - * - * To solve this problem, the KIM maintains a list of favorite identities - * specifically for identity selection. This list is a set of unique identities - * in alphabetical order (as appropriate for the user's language localization). - * - * Each identity may optionally have its own options for ticket acquisition. - * This allows KIM UIs to remember what ticket options worked for a specific - * identity. For example if the user normally wants renewable tickets but - * they have one identity at a KDC which rejects requests for renewable tickets, - * the "not renewable" option can be associated with that identity without - * changing the user's default preference to get renewable tickets. If an - * identity should use the default options, just pass KIM_OPTIONS_DEFAULT. - * - * Most callers will not need to use the favorite identities APIs. However if you - * are implementing your own graphical prompt callback or a credential management - * application, you may to view and/or edit the user's favorite identities. - * - * \section kim_favorite_identities_edit Viewing and Editing the Favorite Identities - * - * First, you need to acquire the Favorite Identities stored in the user's - * preferences using #kim_preferences_create(). - * - * Then use #kim_preferences_get_number_of_favorite_identities() and - * #kim_preferences_get_favorite_identity_at_index() to display the identities list. - * Use #kim_preferences_add_favorite_identity() and #kim_preferences_remove_favorite_identity() - * to change which identities are in the identities list. Identities are always stored in - * alphabetical order and duplicate identities are not permitted, so when you add or remove a - * identity you should redisplay the entire list. If you wish to replace the - * identities list entirely, use #kim_preferences_remove_all_favorite_identities() - * to clear the list before adding your identities. - * - * Once you are done editing the favorite identities list, store changes in the - * user's preference file using #kim_preferences_synchronize(). - * - * See \ref kim_preferences_reference for information on specific APIs. - */ - -/*! - * \defgroup kim_preferences_reference KIM Preferences Documentation - * @{ - */ - -/*! - * \param out_preferences on exit, a new preferences object. - * Must be freed with kim_preferences_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Create a new preferences object from the current user's preferences. - */ -kim_error kim_preferences_create (kim_preferences *out_preferences); - -/*! - * \param out_preferences on exit, a new preferences object which is a copy of in_preferences. - * Must be freed with kim_preferences_free(). - * \param in_preferences a preferences object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Copy a preferences object. - */ -kim_error kim_preferences_copy (kim_preferences *out_preferences, - kim_preferences in_preferences); - -/*! - * \param io_preferences a preferences object to modify. - * \param in_options an options object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the user's preferred options. - * \sa kim_preferences_get_options() - */ -kim_error kim_preferences_set_options (kim_preferences io_preferences, - kim_options in_options); - -/*! - * \param in_preferences a preferences object. - * \param out_options on exit, the options specified in \a in_preferences. - * May be KIM_OPTIONS_DEFAULT. - * If not, must be freed with kim_options_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the user's preferred options. - * \sa kim_preferences_set_options() - */ -kim_error kim_preferences_get_options (kim_preferences in_preferences, - kim_options *out_options); - -/*! - * \param io_preferences a preferences object to modify. - * \param in_remember_options a boolean value indicating whether or not to remember the last - * options used to acquire a credential. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set whether or not to remember the last options the user used to acquire a credential. - * \sa kim_preferences_get_remember_options() - */ -kim_error kim_preferences_set_remember_options (kim_preferences io_preferences, - kim_boolean in_remember_options); - -/*! - * \param in_preferences a preferences object. - * \param out_remember_options on exit, a boolean value indicating whether or \a in_preferences will - * remember the last options used to acquire a credential. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get whether or not to remember the last options the user used to acquire a credential. - * \sa kim_preferences_set_remember_options() - */ -kim_error kim_preferences_get_remember_options (kim_preferences in_preferences, - kim_boolean *out_remember_options); - -/*! - * \param io_preferences a preferences object to modify. - * \param in_client_identity a client identity object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the user's preferred client identity. - * \sa kim_preferences_get_client_identity() - */ -kim_error kim_preferences_set_client_identity (kim_preferences io_preferences, - kim_identity in_client_identity); - -/*! - * \param in_preferences a preferences object. - * \param out_client_identity on exit, the client identity specified in \a in_preferences. - * Must be freed with kim_identity_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the user's preferred client identity. - * \sa kim_preferences_set_client_identity() - */ -kim_error kim_preferences_get_client_identity (kim_preferences in_preferences, - kim_identity *out_client_identity); - -/*! - * \param io_preferences a preferences object to modify. - * \param in_remember_client_identity a boolean value indicating whether or not to remember the last - * client identity for which a credential was acquired. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set whether or not to remember the last client identity the user acquired a credential for. - * \sa kim_preferences_get_remember_client_identity() - */ -kim_error kim_preferences_set_remember_client_identity (kim_preferences io_preferences, - kim_boolean in_remember_client_identity); - -/*! - * \param in_preferences a preferences object. - * \param out_remember_client_identity on exit, a boolean value indicating whether or \a in_preferences will - * remember the last client identity for which a credential was acquired. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get whether or not to remember the last client identity the user acquired a credential for. - * \sa kim_preferences_set_remember_client_identity() - */ -kim_error kim_preferences_get_remember_client_identity (kim_preferences in_preferences, - kim_boolean *out_remember_client_identity); - -/*! - * \param io_preferences a preferences object to modify. - * \param in_minimum_lifetime a minimum lifetime indicating how small a lifetime the - * GUI tools should allow the user to specify for credentials. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the minimum credential lifetime for GUI credential lifetime controls. - * \sa kim_preferences_get_minimum_lifetime() - */ -kim_error kim_preferences_set_minimum_lifetime (kim_preferences io_preferences, - kim_lifetime in_minimum_lifetime); - -/*! - * \param in_preferences a preferences object. - * \param out_minimum_lifetime on exit, the minimum lifetime that GUI tools will - * allow the user to specify for credentials. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the minimum credential lifetime for GUI credential lifetime controls. - * \sa kim_preferences_set_minimum_lifetime() - */ -kim_error kim_preferences_get_minimum_lifetime (kim_preferences in_preferences, - kim_lifetime *out_minimum_lifetime); - -/*! - * \param io_preferences a preferences object to modify. - * \param in_maximum_lifetime a maximum lifetime indicating how large a lifetime the - * GUI tools should allow the user to specify for credentials. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the maximum credential lifetime for GUI credential lifetime controls. - * \sa kim_preferences_get_maximum_lifetime() - */ -kim_error kim_preferences_set_maximum_lifetime (kim_preferences io_preferences, - kim_lifetime in_maximum_lifetime); - -/*! - * \param in_preferences a preferences object. - * \param out_maximum_lifetime on exit, the maximum lifetime that GUI tools will - * allow the user to specify for credentials. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the maximum credential lifetime for GUI credential lifetime controls. - * \sa kim_preferences_set_maximum_lifetime() - */ -kim_error kim_preferences_get_maximum_lifetime (kim_preferences in_preferences, - kim_lifetime *out_maximum_lifetime); - -/*! - * \param io_preferences a preferences object to modify. - * \param in_minimum_renewal_lifetime a minimum lifetime indicating how small a lifetime the - * GUI tools should allow the user to specify for - * credential renewal. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the minimum credential renewal lifetime for GUI credential lifetime controls. - * \sa kim_preferences_get_minimum_renewal_lifetime() - */ -kim_error kim_preferences_set_minimum_renewal_lifetime (kim_preferences io_preferences, - kim_lifetime in_minimum_renewal_lifetime); - -/*! - * \param in_preferences a preferences object. - * \param out_minimum_renewal_lifetime on exit, the minimum lifetime that GUI tools will - * allow the user to specify for credential renewal. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the minimum credential renewal lifetime for GUI credential lifetime controls. - * \sa kim_preferences_set_minimum_renewal_lifetime() - */ -kim_error kim_preferences_get_minimum_renewal_lifetime (kim_preferences in_preferences, - kim_lifetime *out_minimum_renewal_lifetime); - -/*! - * \param io_preferences a preferences object to modify. - * \param in_maximum_renewal_lifetime a maximum lifetime indicating how large a lifetime the - * GUI tools should allow the user to specify for - * credential renewal. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the maximum credential renewal lifetime for GUI credential lifetime controls. - * \sa kim_preferences_get_minimum_renewal_lifetime() - */ -kim_error kim_preferences_set_maximum_renewal_lifetime (kim_preferences io_preferences, - kim_lifetime in_maximum_renewal_lifetime); - -/*! - * \param in_preferences a preferences object. - * \param out_maximum_renewal_lifetime on exit, the maximum lifetime that GUI tools will - * allow the user to specify for credential renewal. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the maximum credential renewal lifetime for GUI credential lifetime controls. - * \sa kim_preferences_set_minimum_renewal_lifetime() - */ -kim_error kim_preferences_get_maximum_renewal_lifetime (kim_preferences in_preferences, - kim_lifetime *out_maximum_renewal_lifetime); - -/*! - * \param in_preferences a preferences object. - * \param out_number_of_identities on exit, the number of identities in \a in_preferences. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the number of favorite identities in a preferences object. - */ -kim_error kim_preferences_get_number_of_favorite_identities (kim_preferences in_preferences, - kim_count *out_number_of_identities); - -/*! - * \param in_preferences a preferences object. - * \param in_index a index into the identities list (starting at 0). - * \param out_identity on exit, the identity at \a in_index in \a in_preferences. - * Must be freed with kim_string_free(). - * \param out_options on exit, the options associated with identity at \a in_index - * in \a in_favorite_identities. May be KIM_OPTIONS_DEFAULT. - * Pass NULL if you do not want the options associated with the identity. - * Must be freed with kim_options_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the Nth favorite identity in a preferences object. - */ -kim_error kim_preferences_get_favorite_identity_at_index (kim_preferences in_preferences, - kim_count in_index, - kim_identity *out_identity, - kim_options *out_options); - -/*! - * \param io_preferences a preferences object. - * \param in_identity an identity to add to \a io_preferences. - * \param in_options options which will be associated with that identity. - * Use KIM_OPTIONS_DEFAULT if the identity should use - * the user's default options. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Add a favorite identity to a preferences object. - */ -kim_error kim_preferences_add_favorite_identity (kim_preferences io_preferences, - kim_identity in_identity, - kim_options in_options); - -/*! - * \param io_preferences a preferences object. - * \param in_identity an identity to remove from \a io_preferences. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Remove a favorite identity from a preferences object. - */ -kim_error kim_preferences_remove_favorite_identity (kim_preferences io_preferences, - kim_identity in_identity); - -/*! - * \param io_preferences a preferences object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Remove all favorite identities in a preferences object. - */ -kim_error kim_preferences_remove_all_favorite_identities (kim_preferences io_preferences); - -/*! - * \param in_preferences a preferences object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Synchronize a preferences object with the user's preferences, writing pending changes - * and reading any changes applied by other processes. - */ -kim_error kim_preferences_synchronize (kim_preferences in_preferences); - -/*! - * \param io_preferences the preferences object to be freed. Set to NULL on exit. - * \brief Free memory associated with a preferences object. - */ -void kim_preferences_free (kim_preferences *io_preferences); - -/*!@}*/ - -#ifdef __cplusplus -} -#endif - -#endif /* KIM_PREFERENCES_H */ diff --git a/src/include/kim/kim_selection_hints.h b/src/include/kim/kim_selection_hints.h deleted file mode 100644 index 76cd41fc7..000000000 --- a/src/include/kim/kim_selection_hints.h +++ /dev/null @@ -1,439 +0,0 @@ -/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ -/* - * Copyright 2005-2006 Massachusetts Institute of Technology. - * All Rights Reserved. - * - * Export of this software from the United States of America may - * require a specific license from the United States Government. - * It is the responsibility of any person or organization contemplating - * export to obtain such a license before exporting. - * - * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - * distribute this software and its documentation for any purpose and - * without fee is hereby granted, provided that the above copyright - * notice appear in all copies and that both that copyright notice and - * this permission notice appear in supporting documentation, and that - * the name of M.I.T. not be used in advertising or publicity pertaining - * to distribution of the software without specific, written prior - * permission. Furthermore if you modify this software you must label - * your software as modified software and not distribute it in such a - * fashion that it might be confused with the original M.I.T. software. - * M.I.T. makes no representations about the suitability of - * this software for any purpose. It is provided "as is" without express - * or implied warranty. - */ - -#ifndef KIM_SELECTION_HINTS_H -#define KIM_SELECTION_HINTS_H - -#ifdef __cplusplus -extern "C" { -#endif - -#include <kim/kim_types.h> - -/*! - * \page kim_selection_hints_overview KIM Selection Hints Overview - * - * \section kim_selection_hints_introduction Introduction - * - * Most users belong to multiple organizations and thus need - * to authenticate to multiple Kerberos realms. Traditionally Kerberos sites - * solved this problem by setting up a cross-realm relationship, which allowed - * the user to use TGT credentials for their client identity in one realm - * to obtain credentials in another realm via cross-realm authentication. As a - * result users could acquire credentials for a single client identity and use - * them everywhere. - * - * Setting up cross-realm requires that realms share a secret, so sites must - * coordinate with one another to set up a cross-realm relationship. In - * addition, sites must set up authorization policies for users from other - * realms. As Kerberos becomes increasingly wide-spread, many realms will - * not have cross-realm relationships, and users will need to - * manually obtain credentials for their client identity at each realm - * (eg: "user@BANK.COM", "user@UNIVERSITY.EDU", etc). As a result, users - * will often have multiple credentials caches, one for each client identity. - * - * Unfortunately this presents a problem for applications which need to obtain - * service credentials. Which client identity should they use? - * Rather than having each application to manually search the cache collection, - * KIM provides a selection hints API for choosing the best client identity. - * This API is intended to simplify the process of choosing credentials - * and provide consistent behavior across all applications. - * - * Searching the cache collection for credentials may be expensive if there - * are a large number of caches. If credentials for the client identity - * are expired or not present, KIM may also wish to prompt the user for - * new credentials for the appropriate client identity. As a result, - * applications might want to remember which client identity worked in - * the past and always request credentials using that identity. - * - * - * \section kim_selection_hints_creating Creating KIM Selection Hints - * - * A KIM selection hints object consists of an application identifier and one or - * more pieces of information about the service the client application will be - * contacting. The application identifier is used by user preferences - * to control how applications share cache entries. It is important to be - * consistent about what application identifier you provide. Java-style - * identifiers are recommended to avoid collisions. - * - * \section kim_selection_hints_searching Selection Hint Search Behavior - * - * When using selection hints to search for an appropriate client identity, - * KIM uses a consistent hint search order. This allows applications to specify - * potentially contradictory information without preventing KIM from locating a - * single ccache. In addition the selection hint search order may change, - * especially if more hints are added. - * - * As a result, callers are encouraged to provide all relevant search hints, - * even if only a subset of those search hints are necessary to get reasonable - * behavior in the current implementation. Doing so will provide the most - * user-friendly selection experience. - * - * Currently the search order looks like this: - * - * \li <B>Service Identity</B> The client identity which has obtained a service credential for this service identity. - * \li <B>Server</B> A client identity which has obtained a service credential for this server. - * \li <B>Service Realm</B> A client identity which has obtained a service credential for this realm. - * \li <B>Service</B> A client identity which has obtained a service credential for this service. - * \li <B>Client Realm</B> A client identity in this realm. - * \li <B>User</B> A client identity whose first component is this user string. - * - * For example, if you specify a service identity and a credential for - * that identity already exists in the ccache collection, KIM may use that - * ccache, even if your user and client realm entries in the selection hints would - * lead it to choose a different ccache. If no credentials for the service identity - * exist then KIM will fall back on the user and realm hints. - * - * \note Due to performance and information exposure concerns, currently all - * searching is done by examining the cache collection. In the future the KIM - * may also make network requests as part of its search algorithm. For example - * it might check to see if the TGT credentials in each ccache can obtain - * credentials for the service identity specified by the selection hints. - * - * \section kim_selection_hints_selecting Selecting an Identity Using Selection Hints - * - * Once you have provided search criteria for selecting an identity, use - * #kim_selection_hints_get_identity() to obtain an identity object. - * You can then use #kim_identity_get_string() to obtain a krb5 principal - * string for use with gss_import_name() and gss_acquire_cred(). Alternatively, - * you can use #kim_ccache_create_from_client_identity() to obtain a ccache - * containing credentials for the identity. - * - * \note #kim_selection_hints_get_identity() obtains an identity based on - * the current state of the selection hints object. If you change the - * selection hints object you must call #kim_selection_hints_get_identity() - * again. - * - * \section kim_selection_hints_caching Selection Hint Caching Behavior - * - * In addition to using selection hints to search for an appropriate client - * identity, KIM can also use them to remember which client identity worked. - * KIM maintains a per-user cache mapping selection hints to identities so - * that applications do not have to maintain their own caches or present - * user interface for selecting which cache to use. - * - * When #kim_selection_hints_get_identity() is called KIM looks up in the - * cache and returns the identity which the selection hints map to. If - * there is not a preexisting cache entry for the selection hints then - * #kim_selection_hints_get_identity() will search for an identity and - * prompt the user if it cannot find an appropriate one. - * - * If the client identity returned by KIM authenticates and passes - * authorization checks, you should tell KIM to cache the identity by calling - * #kim_selection_hints_remember_identity(). This will create a cache entry - * for the mapping between your selection hints and the identity so that - * subsequent calls to #kim_selection_hints_get_identity() do not need to - * prompt the user. - * - * If the client identity returned by KIM fails to authenticate or fails - * authorization checks, you must call #kim_selection_hints_forget_identity() - * to remove any mapping that already exists. After this function is called, - * future calls to #kim_selection_hints_get_identity() will search for an - * identity again. You may also wish to call this function if the user - * changes your application preferences such that the identity might be - * invalidated. - * - * \note It is very important that you call #kim_selection_hints_forget_identity() - * if your application fails to successfully establish a connection with the - * server. Otherwise the user can get "stuck" using the same non-working - * identity if they chose the wrong one accidentally or if their identity - * information changes. Because only your application understands the - * authorization checksof the protocol it uses, KIM cannot tell whether or not - * the identity worked. - * - * If you wish to search and prompt for an identity without using - * the cached mappings, you can turn off the cached mapping lookups using - * #kim_selection_hints_set_remember_identity(). This is not recommended - * for most applications since it will result in a lot of unnecessary - * searching and prompting for identities. - * - * \note Because cache entries key off of selection hints, it is important - * to always specify the same hints when contacting a particular - * service. Otherwise KIM will not always find the cache entries. - * - * \section kim_selection_hints_prompt Selection Hint Prompting Behavior - * - * If valid credentials for identity in the selection hints cache are - * unavailable or if no identity could be found using searching or caching - * when #kim_selection_hints_get_identity() is called, KIM may present a - * GUI to ask the user to select an identity or acquire credentials for - * an identity. - * - * \note Because of the caching behavior described above the user will - * only be prompted to choose an identity when setting up the application - * or when their identity stops working. - * - * In order to let the user know why Kerberos needs their assistance, KIM - * displays the name of the application which requested the identity - * selection. Unfortunately, some platforms do not provide a runtime - * mechanism for determining the name of the calling process. If your - * application runs on one of these platforms (or is cross-platform) - * you should provide a localized version of its name with - * the private function #kim_library_set_application_name(). - * - * In many cases a single application may select different identities for - * different purposes. For example an email application might use different - * identities to check mail for different accounts. If your application - * has this property you may need to provide the user with a localized - * string describing how the identity will be used. You can specify - * this string with #kim_selection_hints_get_explanation(). You can find - * out what string will be used with kim_selection_hints_set_explanation(). - * - * Since the user may choose to acquire credentials when selection an - * identity, KIM also provides #kim_selection_hints_set_options() to - * set what credential acquisition options are used. - * #kim_selection_hints_get_options() returns the options which will be used. - * - * If you need to disable user interaction, use - * #kim_selection_hints_set_allow_user_interaction(). Use - * #kim_selection_hints_get_allow_user_interaction() to find out whether or - * not user interaction is enabled. User interaction is enabled by default. - * - * See \ref kim_selection_hints_reference for information on specific APIs. - */ - -/*! - * \defgroup kim_selection_hints_reference KIM Selection Hints Reference Documentation - * @{ - */ - -/*! A client identity in this realm. - * See \ref kim_selection_hints_overview for more information */ -#define kim_hint_key_client_realm "kim_hint_key_client_realm" - -/*! A client identity whose first component is this user string. - * See \ref kim_selection_hints_overview for more information */ -#define kim_hint_key_user "kim_hint_key_user" - -/*! A client identity which has obtained a service credential for this realm. - * See \ref kim_selection_hints_overview for more information */ -#define kim_hint_key_service_realm "kim_hint_key_service_realm" - -/*! A client identity which has obtained a service credential for this service. - * See \ref kim_selection_hints_overview for more information */ -#define kim_hint_key_service "kim_hint_key_service" - -/*! A client identity which has obtained a service credential for this server. - * See \ref kim_selection_hints_overview for more information */ -#define kim_hint_key_server "kim_hint_key_server" - -/*! The client identity which has obtained a service credential for this service identity. - * See \ref kim_selection_hints_overview for more information */ -#define kim_hint_key_service_identity "kim_hint_key_service_identity" - -/*! - * \param out_selection_hints on exit, a new selection hints object. - * Must be freed with kim_selection_hints_free(). - * \param in_application_identifier an application identifier string. Java-style identifiers are recommended - * to avoid cache entry collisions (eg: "com.example.MyApplication") - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Create a new selection hints object. - */ -kim_error kim_selection_hints_create (kim_selection_hints *out_selection_hints, - kim_string in_application_identifier); - -/*! - * \param out_selection_hints on exit, a new selection hints object which is a copy of in_selection_hints. - * Must be freed with kim_selection_hints_free(). - * \param in_selection_hints a selection hints object. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Copy a selection hints object. - */ -kim_error kim_selection_hints_copy (kim_selection_hints *out_selection_hints, - kim_selection_hints in_selection_hints); - -/*! - * \param io_selection_hints a selection hints object to modify. - * \param in_hint_key A string representing the type of hint to set. - * \param in_hint_string A string representation of a hint for - * \a in_hint_key to set in \a in_selection_hints. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the string value of a hint used for identity selection. - * \sa kim_selection_hints_get_hint() - */ -kim_error kim_selection_hints_set_hint (kim_selection_hints io_selection_hints, - kim_string in_hint_key, - kim_string in_hint_string); - -/*! - * \param in_selection_hints a selection hints object. - * \param in_hint_key A string representing the type of hint to - * obtain. - * \param out_hint_string On exit, a string representation of the hint - * \a in_hint_key in \a in_selection_hints. - * If the hint is not set, sets the value pointed - * to by \a out_hint_string to NULL; - * Must be freed with kim_string_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the string value of a hint used for identity selection. - * \sa kim_selection_hints_set_hint() - */ -kim_error kim_selection_hints_get_hint (kim_selection_hints in_selection_hints, - kim_string in_hint_key, - kim_string *out_hint_string); - -/*! - * \param io_selection_hints a selection hints object to modify. - * \param in_explanation a localized string describing why the caller needs the identity. - * \note If the application only does one thing (the reason it needs an identity is obvious) - * then you may not need to call this function. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the strings used to prompt the user to select the identity. - * \sa kim_selection_hints_get_explanation() - */ -kim_error kim_selection_hints_set_explanation (kim_selection_hints io_selection_hints, - kim_string in_explanation); - -/*! - * \param in_selection_hints a selection hints object. - * \param out_explanation on exit, the localized string specified in \a in_selection_hints - * which describes why the caller needs the identity. May be NULL. - * If non-NULL, must be freed with kim_string_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the strings used to prompt the user to select the identity. - * \sa kim_selection_hints_set_explanation() - */ -kim_error kim_selection_hints_get_explanation (kim_selection_hints in_selection_hints, - kim_string *out_explanation); - - -/*! - * \param io_selection_hints a selection hints object to modify. - * \param in_options options to control credential acquisition. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Set the options which will be used if credentials need to be acquired. - * \sa kim_selection_hints_get_options() - */ -kim_error kim_selection_hints_set_options (kim_selection_hints io_selection_hints, - kim_options in_options); - -/*! - * \param in_selection_hints a selection hints object. - * \param out_options on exit, the options to control credential acquisition - * specified in \a in_selection_hints. May be KIM_OPTIONS_DEFAULT. - * If not, must be freed with kim_options_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the options which will be used if credentials need to be acquired. - * \sa kim_selection_hints_set_options() - */ -kim_error kim_selection_hints_get_options (kim_selection_hints in_selection_hints, - kim_options *out_options); - -/*! - * \param in_selection_hints a selection hints object to modify - * \param in_allow_user_interaction a boolean value specifying whether or not KIM should ask - * the user to select an identity for \a in_selection_hints. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \note This setting defaults to TRUE. - * \brief Set whether or not KIM may interact with the user to select an identity. - * \sa kim_selection_hints_get_allow_user_interaction - */ -kim_error kim_selection_hints_set_allow_user_interaction (kim_selection_hints in_selection_hints, - kim_boolean in_allow_user_interaction); - -/*! - * \param in_selection_hints a selection hints object to modify - * \param out_allow_user_interaction on exit, a boolean value specifying whether or not KIM - * should ask the user to select an identity for - * \a in_selection_hints. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \note This setting defaults to TRUE. - * \brief Get whether or not KIM may interact with the user to select an identity. - * \sa kim_selection_hints_set_allow_user_interaction - */ -kim_error kim_selection_hints_get_allow_user_interaction (kim_selection_hints in_selection_hints, - kim_boolean *out_allow_user_interaction); - -/*! - * \param in_selection_hints a selection hints object to modify - * \param in_remember_identity a boolean value specifying whether or not KIM should use a cached - * mapping between \a in_selection_hints and a Kerberos identity. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \note This setting defaults to TRUE. - * \brief Set whether or not KIM will use cached mappings for this selection hints object. - * \sa kim_selection_hints_get_remember_identity - */ -kim_error kim_selection_hints_set_remember_identity (kim_selection_hints in_selection_hints, - kim_boolean in_remember_identity); - -/*! - * \param in_selection_hints a selection hints object to modify - * \param out_remember_identity on exit, a boolean value specifying whether or not KIM will use a - * cached mapping between \a in_selection_hints and a Kerberos identity. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \note This setting defaults to TRUE. - * \brief Get whether or not KIM will use cache mappings for this selection hints object. - * \sa kim_selection_hints_set_remember_identity - */ -kim_error kim_selection_hints_get_remember_identity (kim_selection_hints in_selection_hints, - kim_boolean *out_remember_identity); - -/*! - * \param in_selection_hints the selection hints to add to the cache. - * \param out_identity the Kerberos identity \a in_selection_hints maps to. - * Must be freed with kim_identity_free(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \note \a out_identity is the identity mapped to by the current state of \a in_selection_hints. - * This function may prompt the user via a GUI to choose that identity. - * Subsequent modifications to \a in_selection_hints will not change \a out_identity. - * \brief Choose a client identity based on selection hints. - */ - -kim_error kim_selection_hints_get_identity (kim_selection_hints in_selection_hints, - kim_identity *out_identity); - -/*! - * \param in_selection_hints the selection hints to add to the cache. - * \param in_identity the Kerberos identity \a in_selection_hints maps to. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Add an entry for the selection hints to the selection hints cache, - * replacing any existing entry. - */ - -kim_error kim_selection_hints_remember_identity (kim_selection_hints in_selection_hints, - kim_identity in_identity); - -/*! - * \param in_selection_hints the selection hints to remove from the cache. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Remove an entry for the selection hints from the selection hints cache. - */ - -kim_error kim_selection_hints_forget_identity (kim_selection_hints in_selection_hints); - -/*! - * \param io_selection_hints the selection hints object to be freed. Set to NULL on exit. - * \brief Free memory associated with a selection hints object. - */ - -void kim_selection_hints_free (kim_selection_hints *io_selection_hints); - -/*!@}*/ - -#ifdef __cplusplus -} -#endif - -#endif /* KIM_SELECTION_HINTS_H */ diff --git a/src/include/kim/kim_string.h b/src/include/kim/kim_string.h deleted file mode 100644 index aaf1975a9..000000000 --- a/src/include/kim/kim_string.h +++ /dev/null @@ -1,123 +0,0 @@ -/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ -/* - * Copyright 2005-2006 Massachusetts Institute of Technology. - * All Rights Reserved. - * - * Export of this software from the United States of America may - * require a specific license from the United States Government. - * It is the responsibility of any person or organization contemplating - * export to obtain such a license before exporting. - * - * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - * distribute this software and its documentation for any purpose and - * without fee is hereby granted, provided that the above copyright - * notice appear in all copies and that both that copyright notice and - * this permission notice appear in supporting documentation, and that - * the name of M.I.T. not be used in advertising or publicity pertaining - * to distribution of the software without specific, written prior - * permission. Furthermore if you modify this software you must label - * your software as modified software and not distribute it in such a - * fashion that it might be confused with the original M.I.T. software. - * M.I.T. makes no representations about the suitability of - * this software for any purpose. It is provided "as is" without express - * or implied warranty. - */ - -#ifndef KIM_STRING_H -#define KIM_STRING_H - -#ifdef __cplusplus -extern "C" { -#endif - -#include <kim/kim_types.h> - -/*! - * \page kim_string_overview KIM String Overview - * - * A UTF8 string. - * - * Memory management routines are provided for runtime consistency on - * operating systems with shared libraries and multiple runtimes. - * - * \section kim_string_error_messages KIM Error Messages - * - * Like most C APIs, the KIM API returns numeric error codes. These error - * codes may come from KIM, krb5 or GSS APIs. In most cases the caller will - * want to handle these error programmatically. However, in some circumstances - * the caller may wish to print an error string to the user. - * - * One problem with just printing the error code to the user is that frequently - * the context behind the error has been lost. For example if KIM is trying to - * obtain credentials via referrals, it may fail partway through the process. - * In this case the error code will be KRB5KDC_ERR_C_PRINCIPAL_UNKNOWN, which - * maps to "Client not found in Kerberos database". Unfortunately this error - * isn't terribly helpful because it doesn't tell the user whether they typoed - * their principal name or if referrals failed. - * - * To avoid this problem, KIM maintains an explanatory string for the last - * error seen in each thread calling into KIM. If a caller wishes to display - * an error to the user, immediately after getting the error the caller should - * call #kim_string_create_for_last_error() to obtain a copy of the - * descriptive error message. - * - * See \ref kim_string_reference for information on specific APIs. - */ - -/*! - * \defgroup kim_string_reference KIM String Reference Documentation - * @{ - */ - -/*! - * \param out_string On success, a human-readable UTF-8 string describing the - * error representedby \a in_error. Must be freed with - * kim_string_free(). - * \param in_error an error code. Used to verify that the correct error - * string will be returned (see note below). - * \return On success, KIM_NO_ERROR. - * \note This API is implemented using thread local storage. It should be - * called immediately after a KIM API returns an error code so that the correct - * string is returned. The returned copy may then be held by the caller until - * needed. If \a in_error does not match the last saved error KIM may return - * a less descriptive string. - * \brief Get a text description of an error suitable for display to the user. - */ -kim_error kim_string_create_for_last_error (kim_string *out_string, - kim_error in_error); - -/*! - * \param out_string on exit, a new string object which is a copy of \a in_string. - Must be freed with kim_string_free(). - * \param in_string the string to copy. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Copy a string. - */ -kim_error kim_string_copy (kim_string *out_string, - const kim_string in_string); - -/*! - * \param in_string a string. - * \param in_compare_to_string a string to be compared to \a in_string. - * \param out_comparison on exit, a comparison result indicating whether \a in_string - * is greater than, less than or equal to \a in_compare_to_string. - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Compare two strings. - */ -kim_error kim_string_compare (kim_string in_string, - kim_string in_compare_to_string, - kim_comparison *out_comparison); - -/*! - * \param io_string a string to be freed. Set to NULL on exit. - * \brief Free memory associated with a string. - */ -void kim_string_free (kim_string *io_string); - -/*!@}*/ - -#ifdef __cplusplus -} -#endif - -#endif /* KIM_STRING_H */ diff --git a/src/include/kim/kim_types.h b/src/include/kim/kim_types.h deleted file mode 100644 index 4778ba527..000000000 --- a/src/include/kim/kim_types.h +++ /dev/null @@ -1,156 +0,0 @@ -/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ -/* - * Copyright 2005-2006 Massachusetts Institute of Technology. - * All Rights Reserved. - * - * Export of this software from the United States of America may - * require a specific license from the United States Government. - * It is the responsibility of any person or organization contemplating - * export to obtain such a license before exporting. - * - * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - * distribute this software and its documentation for any purpose and - * without fee is hereby granted, provided that the above copyright - * notice appear in all copies and that both that copyright notice and - * this permission notice appear in supporting documentation, and that - * the name of M.I.T. not be used in advertising or publicity pertaining - * to distribution of the software without specific, written prior - * permission. Furthermore if you modify this software you must label - * your software as modified software and not distribute it in such a - * fashion that it might be confused with the original M.I.T. software. - * M.I.T. makes no representations about the suitability of - * this software for any purpose. It is provided "as is" without express - * or implied warranty. - */ - -#ifndef KIM_TYPES_H -#define KIM_TYPES_H - -#include <stdint.h> - -#ifdef __cplusplus -extern "C" { -#endif - -/*! - * \defgroup kim_types_reference KIM Types and Constants - * @{ - */ - -/*! - * The KIM Error type. - */ -typedef int32_t kim_error; - -/*! - * No error value for the kim_error type. - */ -#define KIM_NO_ERROR ((kim_error) 0) - -/*! - * A time value represented in seconds since January 1, 1970. - */ -typedef int64_t kim_time; - -/*! - * A duration represented in seconds. - */ -typedef int64_t kim_lifetime; - -/*! - * An quantity, usually used to return the number of elements in an array. - */ -typedef uint64_t kim_count; - -/*! - * A boolean value. 0 means false, all other values mean true. - */ -typedef int kim_boolean; - -/*! - * A comparison between two sortable objects. - * \li Less than 0 means the first object is less than the second. - * \li 0 means the two objects are identical. - * \li Greater than 0 means the first object is greater than the second. - * \note Convenience macros are provided for interpreting #kim_comparison - * values to improve code readability. - * See #kim_comparison_is_less_than(), #kim_comparison_is_equal_to() and - * #kim_comparison_is_greater_than() - */ -typedef int kim_comparison; - -/*! - * Convenience macro for interpreting #kim_comparison. - */ -#define kim_comparison_is_less_than(c) (c < 0) - -/*! - * Convenience macro for interpreting #kim_comparison. - */ -#define kim_comparison_is_equal_to(c) (c == 0) - -/*! - * Convenience macro for interpreting #kim_comparison. - */ -#define kim_comparison_is_greater_than(c) (c > 0) - -/*! - * The KIM String type. See \ref kim_string_overview for more information. - */ -typedef const char *kim_string; - -struct kim_identity_opaque; -/*! - * A KIM Principal object. See \ref kim_identity_overview for more information. - */ -typedef struct kim_identity_opaque *kim_identity; - -struct kim_options_opaque; -/*! - * A KIM Options object. See \ref kim_options_overview for more information. - */ -typedef struct kim_options_opaque *kim_options; - -struct kim_selection_hints_opaque; -/*! - * A KIM Selection Hints object. See \ref kim_selection_hints_overview for more information. - */ -typedef struct kim_selection_hints_opaque *kim_selection_hints; - -struct kim_preferences_opaque; -/*! - * A KIM Preferences object. See \ref kim_preferences_overview for more information. - */ -typedef struct kim_preferences_opaque *kim_preferences; - -struct kim_ccache_iterator_opaque; -/*! - * A KIM CCache Iterator object. See \ref kim_credential_cache_collection for more information. - */ -typedef struct kim_ccache_iterator_opaque *kim_ccache_iterator; - -struct kim_ccache_opaque; -/*! - * A KIM CCache object. See \ref kim_ccache_overview for more information. - */ -typedef struct kim_ccache_opaque *kim_ccache; - -struct kim_credential_iterator_opaque; -/*! - * A KIM Credential Iterator object. See \ref kim_credential_iterator for more information. - */ -typedef struct kim_credential_iterator_opaque *kim_credential_iterator; - -struct kim_credential_opaque; -/*! - * A KIM Credential object. See \ref kim_credential_overview for more information. - */ -typedef struct kim_credential_opaque *kim_credential; - -/*!@}*/ - -#ifdef __cplusplus -} -#endif - -#endif /* KIM_TYPES_H */ diff --git a/src/include/kim/kim_ui_plugin.h b/src/include/kim/kim_ui_plugin.h deleted file mode 100644 index 579be7359..000000000 --- a/src/include/kim/kim_ui_plugin.h +++ /dev/null @@ -1,153 +0,0 @@ -/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ -/* - * Copyright 2008 Massachusetts Institute of Technology. - * All Rights Reserved. - * - * Export of this software from the United States of America may - * require a specific license from the United States Government. - * It is the responsibility of any person or organization contemplating - * export to obtain such a license before exporting. - * - * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - * distribute this software and its documentation for any purpose and - * without fee is hereby granted, provided that the above copyright - * notice appear in all copies and that both that copyright notice and - * this permission notice appear in supporting documentation, and that - * the name of M.I.T. not be used in advertising or publicity pertaining - * to distribution of the software without specific, written prior - * permission. Furthermore if you modify this software you must label - * your software as modified software and not distribute it in such a - * fashion that it might be confused with the original M.I.T. software. - * M.I.T. makes no representations about the suitability of - * this software for any purpose. It is provided "as is" without express - * or implied warranty. - */ - -#ifndef KIM_UI_PLUGIN_H -#define KIM_UI_PLUGIN_H - -#ifdef __cplusplus -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 - * in both cases we'll be able to wrap the v0 functions. - */ -/* extern kim_ui_plugin_ftable_v0 kim_ui_0; */ - - -typedef struct kim_ui_plugin_ftable_v0 { - int minor_version; /* currently 0 */ - - /* Called before other calls to allow the UI to initialize. - * Return an error if you can't display your UI in this environment. - * To allow your plugin to be called from multiple threads, pass back - * state associated with this instance of your UI in out_context. - * The same context pointer will be provided to all plugin calls for - * 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. - * If out_change_password is set to TRUE, KIM will call change_password - * on the identity and then call enter_identity again, allowing you - * to have a change password option on your UI. */ - kim_error (*enter_identity) (void *in_context, - kim_options io_options, - kim_identity *out_identity, - kim_boolean *out_change_password); - - /* 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 auth_prompt below. - * If out_change_password is set to TRUE, KIM will call change_password - * on the identity and then call select_identity again, allowing you - * to have a change password option on your UI. */ - kim_error (*select_identity) (void *in_context, - kim_selection_hints io_hints, - kim_identity *out_identity, - kim_boolean *out_change_password); - - /* Present UI to display authentication to the user */ - /* If in_allow_save_reply is FALSE do not display UI to allow the user - * to save their password. In this case the value of out_save_reply will - * be ignored. */ - kim_error (*auth_prompt) (void *in_context, - kim_identity in_identity, - kim_prompt_type in_type, - kim_boolean in_allow_save_reply, - kim_boolean in_hide_reply, - kim_string in_title, - kim_string in_message, - kim_string in_description, - char **out_reply, - kim_boolean *out_save_reply); - - /* Prompt to change the identity's password. - * 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 - * which generated the error will be used for this callback. */ - kim_error (*change_password) (void *in_context, - kim_identity in_identity, - kim_boolean in_old_password_expired, - char **out_old_password, - char **out_new_password, - char **out_verify_password); - - /* Display an error to the user; may be called after any of the prompts */ - 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. 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. */ - kim_error (*fini) (void *io_context); - -} kim_ui_plugin_ftable_v0; - - -#ifdef __cplusplus -} -#endif - -#endif /* KIM_UI_PLUGIN_H */ |