/*
* 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.
*/
#ifndefKIM_OPTIONS_H
#defineKIM_OPTIONS_H
#ifdef__cplusplusextern"C" {
#endif
#include<Kerberos/kim_types.h>/*!
* \addtogroup kim_types_reference
* @{
*//*!
* Specifies the user's default options.
*/
#defineKIM_OPTIONS_DEFAULT ((kim_options) NULL)
/*!
* Specifies that credentials should be valid immediately.
*/
#defineKIM_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.
*/voidkim_options_free (kim_options *io_options);
/*!@}*/
#ifdef__cplusplus
}
#endif
#endif/* KIM_OPTIONS_H */