<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>kim_options.h</title>
<style type="text/css">
.enscript-comment { font-style: italic; color: rgb(178,34,34); }
.enscript-function-name { font-weight: bold; color: rgb(0,0,255); }
.enscript-variable-name { font-weight: bold; color: rgb(184,134,11); }
.enscript-keyword { font-weight: bold; color: rgb(160,32,240); }
.enscript-reference { font-weight: bold; color: rgb(95,158,160); }
.enscript-string { font-weight: bold; color: rgb(188,143,143); }
.enscript-builtin { font-weight: bold; color: rgb(218,112,214); }
.enscript-type { font-weight: bold; color: rgb(34,139,34); }
.enscript-highlight { text-decoration: underline; color: 0; }
</style>
</head>
<body id="top">
<h1 style="margin:8px;" id="f1">kim_options.h&nbsp;&nbsp;&nbsp;<span style="font-weight: normal; font-size: 0.5em;">[<a href="kim_options.h">plain text</a>]</span></h1>
<hr/>
<div></div>
<pre>
<span class="enscript-comment">/*
 * 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 &quot;as is&quot; without express
 * or implied warranty.
 */</span>

#<span class="enscript-reference">ifndef</span> <span class="enscript-variable-name">KIM_OPTIONS_H</span>
#<span class="enscript-reference">define</span> <span class="enscript-variable-name">KIM_OPTIONS_H</span>

#<span class="enscript-reference">ifdef</span> <span class="enscript-variable-name">__cplusplus</span>
<span class="enscript-type">extern</span> <span class="enscript-string">&quot;C&quot;</span> {
#<span class="enscript-reference">endif</span>
    
#<span class="enscript-reference">include</span> <span class="enscript-string">&lt;Kerberos/kim_types.h&gt;</span>
    
<span class="enscript-comment">/*!
 * \addtogroup kim_types_reference
 * @{
 */</span>

<span class="enscript-comment">/*!
 * Specifies the user's default options.
 */</span>
#<span class="enscript-reference">define</span> <span class="enscript-variable-name">KIM_OPTIONS_DEFAULT</span>           ((kim_options) NULL)

<span class="enscript-comment">/*!
 * Specifies that credentials should be valid immediately.
 */</span>
#<span class="enscript-reference">define</span> <span class="enscript-variable-name">KIM_OPTIONS_START_IMMEDIATELY</span> ((kim_time_t) 0)

<span class="enscript-comment">/*! @} */</span>

<span class="enscript-comment">/*!
 * \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 &quot;expire&quot; 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 &quot;renewal
 * lifetime&quot; 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 &quot;ticket granting tickets&quot;) 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.
 */</span> 

<span class="enscript-comment">/*!
 * \defgroup kim_options_reference KIM Options Reference Documentation
 * @{
 */</span>

<span class="enscript-comment">/*!
 * \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.
 */</span>
kim_error <span class="enscript-function-name">kim_options_create</span> (kim_options *out_options);

<span class="enscript-comment">/*!
 * \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.
 */</span>
kim_error <span class="enscript-function-name">kim_options_copy</span> (kim_options *out_options,
                            kim_options  in_options);

<span class="enscript-comment">/*!
 * \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 &quot;now&quot;.  The credential will be valid immediately.
 * \sa kim_options_get_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate()
 */</span>
kim_error <span class="enscript-function-name">kim_options_set_start_time</span> (kim_options io_options,
                                      kim_time    in_start_time);

<span class="enscript-comment">/*!
 * \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 &quot;now&quot;.  The credential will be valid immediately.
 * \sa kim_options_set_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate()
 */</span>
kim_error <span class="enscript-function-name">kim_options_get_start_time</span> (kim_options  in_options,
                                      kim_time    *out_start_time);

<span class="enscript-comment">/*!
 * \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.
 */</span>
kim_error <span class="enscript-function-name">kim_options_set_lifetime</span> (kim_options  io_options,
                                    kim_lifetime in_lifetime);

<span class="enscript-comment">/*!
 * \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()
 */</span>
kim_error <span class="enscript-function-name">kim_options_get_lifetime</span> (kim_options   in_options,
                                    kim_lifetime *out_lifetime);

<span class="enscript-comment">/*!
 * \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()
 */</span>
kim_error <span class="enscript-function-name">kim_options_set_renewable</span> (kim_options io_options,
                                     kim_boolean in_renewable);

<span class="enscript-comment">/*!
 * \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()
 */</span>
kim_error <span class="enscript-function-name">kim_options_get_renewable</span> (kim_options  in_options,
                                     kim_boolean *out_renewable);

<span class="enscript-comment">/*!
 * \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()
 */</span>
kim_error <span class="enscript-function-name">kim_options_set_renewal_lifetime</span> (kim_options  io_options,
                                            kim_lifetime in_renewal_lifetime);

<span class="enscript-comment">/*!
 * \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()
 */</span>
kim_error <span class="enscript-function-name">kim_options_get_renewal_lifetime</span> (kim_options   in_options,
                                            kim_lifetime *out_renewal_lifetime);

<span class="enscript-comment">/*!
 * \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()
 */</span>
kim_error <span class="enscript-function-name">kim_options_set_forwardable</span> (kim_options io_options,
                                       kim_boolean in_forwardable);

<span class="enscript-comment">/*!
 * \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()
 */</span>
kim_error <span class="enscript-function-name">kim_options_get_forwardable</span> (kim_options  in_options,
                                       kim_boolean *out_forwardable);

<span class="enscript-comment">/*!
 * \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()
 */</span>
kim_error <span class="enscript-function-name">kim_options_set_proxiable</span> (kim_options io_options,
                                     kim_boolean in_proxiable);

<span class="enscript-comment">/*!
 * \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()
 */</span>
kim_error <span class="enscript-function-name">kim_options_get_proxiable</span> (kim_options  in_options,
                                     kim_boolean *out_proxiable);

<span class="enscript-comment">/*!
 * \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()
 */</span>
kim_error <span class="enscript-function-name">kim_options_set_addressless</span> (kim_options io_options,
                                       kim_boolean in_addressless);

<span class="enscript-comment">/*!
 * \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()
 */</span>
kim_error <span class="enscript-function-name">kim_options_get_addressless</span> (kim_options  in_options,
                                       kim_boolean *out_addressless);

<span class="enscript-comment">/*!
 * \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 &quot;krbtgt@&lt;REALM&gt;&quot;, the ticket granting ticket (TGT) service.
 * \sa kim_options_get_service_name()
 */</span>
kim_error <span class="enscript-function-name">kim_options_set_service_name</span> (kim_options io_options,
                                        kim_string  in_service_name);

<span class="enscript-comment">/*!
 * \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 &quot;krbtgt@&lt;REALM&gt;&quot;, the ticket granting ticket (TGT) service.
 * \sa kim_options_set_service_name()
 */</span>
kim_error <span class="enscript-function-name">kim_options_get_service_name</span> (kim_options  in_options,
                                        kim_string  *out_service_name);

<span class="enscript-comment">/*!
 * \param io_options the options object to be freed.  Set to NULL on exit.
 * \brief Free memory associated with an options object.
 */</span>
<span class="enscript-type">void</span> <span class="enscript-function-name">kim_options_free</span> (kim_options *io_options);

<span class="enscript-comment">/*!@}*/</span>

#<span class="enscript-reference">ifdef</span> <span class="enscript-variable-name">__cplusplus</span>
}
#<span class="enscript-reference">endif</span>

#<span class="enscript-reference">endif</span> <span class="enscript-comment">/* KIM_OPTIONS_H */</span>
</pre>
<hr />
</body></html>