kim_options_overview.html [plain text]
<!-- #bbinclude "header.txt"
#PAGETITLE#="Kerberos Identity Management: KIM Options Overview"
#ADDITIONALSTYLE#="@import url(doxygen.css);"
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<BASE HREF="http://web.mit.edu/macdev/KfM/KerberosFramework/KerberosIdentityManagement/Documentation/html/kim_options_overview.html">
<META NAME="keywords" CONTENT="#KEYWORDS#">
<META NAME="description" CONTENT="#DESCRIPTION#">
<TITLE>Kerberos Identity Management: KIM Options Overview</TITLE>
<STYLE TYPE="text/css">
@import url(../../../../Common/Documentation/templates/site.css);
</STYLE>
</HEAD>
<BODY>
<DIV ID="menu">
<IMG SRC="../../../../Common/Documentation/graphics/Kerberos.jpg" ALT="Kerberos for Macintosh Logo">
<HR>
<P><A HREF="../../../../Common/Documentation/index.html">Home</A></P>
<P><A HREF="http://web.mit.edu/kerberos/">MIT Kerberos</A></P>
<P><A HREF="http://web.mit.edu/ist/">MIT IS&T</A></P>
<HR>
<P><A HREF="../../../../Common/Documentation/news.html">News</A></P>
<P><A HREF="../../../../Common/Documentation/documentation.html">Documentation</A></P>
<P><A HREF="../../../../Common/Documentation/developer.html">Developer Resources</A></P>
<P><A HREF="../../../../Common/Documentation/license.html">License</A></P>
<HR>
<P><A HREF="../../../../Common/Documentation/download.html">Download</A></P>
<P><A HREF="../../../../Common/Documentation/support.html">Support</A></P>
<P><A HREF="../../../../Common/Documentation/contact.html">Contact Us</A></P>
</DIV>
<DIV ID="body">
<!-- end bbinclude -->
<!-- Generated by Doxygen 1.4.6 -->
<h1><a class="anchor" name="kim_options_overview">KIM Options Overview</a></h1><h2><a class="anchor" name="kim_options_introduction">
Introduction</a></h2>
Kerberos Identity Management Options (kim_options_t) allows you to control how the Kerberos library obtains credentials. When the options structure is initialized with <a class="el" href="group__kim__options__reference.html#g4d00f4d070409ea90aa69a8ac5cb47cf">kim_options_create()</a>, 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 <a class="el" href="group__kim__types__reference.html#ge0384d3f6d9108e3ec84e322c61235a7">KIM_OPTIONS_DEFAULT</a> into any KIM function that takes a kim_options_t.<p>
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:<h2><a class="anchor" name="kim_options_credential_acquisition">
Options for Controlling Credential Acquisition</a></h2>
In order to acquire credentials, Kerberos needs to obtain one or more secrets from the user. These secrets may be a certificate, password, SecurID pin, or information from a smart card. If obtaining the secret requires interaction with the user, the Kerberos libraries call a "prompter callback" to display a dialog or command line prompt to request information from the user. If you want to provide your own custom dialogs or command line prompts, the KIM APIs provide a mechanism for replacing the default prompt callbacks with your own.<h3><a class="anchor" name="kim_options_custom_prompt_callback">
Providing a Custom Prompt Callback</a></h3>
All secrets are obtained from the user through a <a class="el" href="group__kim__types__reference.html#g3dc87ed0aa0847e5af0e4f410ba6d7dd">kim_prompt_callback_t</a>. By default, options use <a class="el" href="group__kim__types__reference.html#gf30874b411a7c7308cd496f8531dd6ca">kim_prompt_callback_default</a>, which presents an expanding dialog to request information from the user, or if no graphical access is available, a command line prompt.<p>
KIM also provides three other callbacks: <a class="el" href="group__kim__types__reference.html#g1e0ff27a769553530b4607995f7ad61d">kim_prompt_callback_gui</a> only presents a dialog and returns an error if there is no graphical access. <a class="el" href="group__kim__types__reference.html#g10188dc8e44e579856ff3e2c5768489f">kim_prompt_callback_cli</a> only presents a command line interface and returns an error if there is no controlling terminal available. <a class="el" href="group__kim__types__reference.html#g682328322dedc851b192118e23dced71">kim_prompt_callback_none</a> always returns an error.<p>
Using <a class="el" href="group__kim__options__reference.html#gb3342e60ebb03f901307fd605af5a684">kim_options_set_prompt_callback()</a>, you can change the prompt callback to one of the above callbacks or a callback you have defined yourself. Callbacks are called in a loop, one for each prompt. Because network traffic may occur between calls to the prompt callback, your prompt interface should support time passing between calls to the prompter. If you are defining a callback yourself, you should also set your own options data with <a class="el" href="group__kim__options__reference.html#g2668448064e5ff737c7576813aad1996">kim_options_set_data()</a> for storing state between calls. Options data is a caller defined pointer value -- the Kerberos libaries make no use of it.<h3><a class="anchor" name="kim_options_preset_prompts">
Prefetching Prompt Responses</a></h3>
Sometimes you may have already collected some of the information needed to acquire Kerberos credentials. Rather than creating a prompt callback, you may also prefetch responses to the options directly with <a class="el" href="group__kim__options__reference.html#g55acd6378c0bdf5c534b9535a534c9bd">kim_options_set_prompt_response()</a>. Once you have associated your response with a given prompt type, the Kerberos libraries will use this response for the first prompt of that type rather than calling the prompt callback to obtain it.<p>
Note that even if you prefetch responses, the prompt callback may still be called if you did not provide all the information required for the identity. You may specify the <a class="el" href="group__kim__types__reference.html#g682328322dedc851b192118e23dced71">kim_prompt_callback_none</a> prompt callback to prevent prompting from occuring entirely, however, doing so will tie your application to a particular Kerberos configuration. For example, if your application assumes that all identities only require a password, it will not be able to acquire credentials at sites using SecurID pins.<h2><a class="anchor" name="kim_options_credential_properties">
Options for Controlling Credential Properties</a></h2>
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.<p>
Note that setting these properties in the KIM options only changes what the Kerberos libraries <em>request</em> 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.<h3><a class="anchor" name="kim_options_lifetimes">
Credential Lifetime</a></h3>
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.<p>
The requested credential start time can be set with <a class="el" href="group__kim__options__reference.html#g2193de68adcec22df88069d86e2a145c">kim_options_set_start_time()</a> and examined with <a class="el" href="group__kim__options__reference.html#g587539ca61a06b5730ed688f914e9fa6">kim_options_get_start_time()</a>. The requested credential lifetime can be set with <a class="el" href="group__kim__options__reference.html#ga6058acd016b6387be19e0127606fcb1">kim_options_set_lifetime()</a> and examined with <a class="el" href="group__kim__options__reference.html#gc179cfff2a29eb0bbe4ac0b6dab8afad">kim_options_get_lifetime()</a>.<h3><a class="anchor" name="kim_options_renewable">
Renewable Credentials</a></h3>
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.<p>
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.<p>
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.<p>
Use <a class="el" href="group__kim__options__reference.html#g47a49dca419a7d7f1d79c5acd1f16b7a">kim_options_set_renewable()</a> to change whether or not the Kerberos libraries request renewable credentials and <a class="el" href="group__kim__options__reference.html#gefc2785f119f04379b20d381a79a45af">kim_options_get_renewable()</a> to find out the current setting. Use <a class="el" href="group__kim__options__reference.html#g035bd3841ff3581922cba91b043cd945">kim_options_set_renewal_lifetime()</a> to change the requested renewal lifetime and <a class="el" href="group__kim__options__reference.html#g2a49d92912b6270357788436d2c6fd8f">kim_options_get_renewal_lifetime()</a> to find out the current value.<h3><a class="anchor" name="kim_options_addressless">
Addressless Credentials</a></h3>
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.<p>
Use <a class="el" href="group__kim__options__reference.html#g673640ffd337c815cbc71cbef32b4156">kim_options_set_addressless()</a> to change whether or not the Kerberos libraries request addressless credentials. Use <a class="el" href="group__kim__options__reference.html#g8308f996ae22cad938ec4a4782a01322">kim_options_get_addressless()</a> to find out the current setting.<h3><a class="anchor" name="kim_options_forwardable">
Forwardable Credentials</a></h3>
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.<p>
The forwardable flag only applies to TGT credentials.<p>
Use <a class="el" href="group__kim__options__reference.html#gc055fb95bb39e93b276dc2380632cd6d">kim_options_set_forwardable()</a> to change whether or not the Kerberos libraries request forwardable credentials. Use <a class="el" href="group__kim__options__reference.html#g6dc2e2ec0448d28ce847fc8880ce8561">kim_options_get_forwardable()</a> to find out the current setting.<h3><a class="anchor" name="kim_options_proxiable">
Proxiable Credentials</a></h3>
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.<p>
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.<p>
Use <a class="el" href="group__kim__options__reference.html#g4ab6093bff1c28196e2886e146d5e0d0">kim_options_set_proxiable()</a> to change whether or not the Kerberos libraries request proxiable credentials. Use <a class="el" href="group__kim__options__reference.html#ga36c948940f89e1cca4477b3d1869c84">kim_options_get_proxiable()</a> to find out the current setting.<h3><a class="anchor" name="kim_options_service_identity">
Service Identity</a></h3>
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 identity with <a class="el" href="group__kim__options__reference.html#g48df00d0dfd94dc37c0b3ec21aed46ac">kim_options_set_service_identity()</a> and query it with <a class="el" href="group__kim__options__reference.html#g1a57d4f84f0e4cfe79d01182bf98f501">kim_options_get_service_identity()</a>.<p>
See <a class="el" href="group__kim__options__reference.html">KIM Options Reference Documentation</a> for information on specific APIs.
<!-- #bbinclude "footer.txt" -->
</DIV>
<DIV ID="footer">
<P>
Copyright 2006 Massachusetts Institute of Technology.<BR>
Last updated on $Date: 2006-01-06 20:23:52 -0500 (Fri, 06 Jan 2006) $ <BR>
Last modified by $Author: lxs $
</P>
</DIV>
<!-- Begin MIT-use only web reporting counter -->
<IMG SRC="http://counter.mit.edu/tally" WIDTH=1 HEIGHT=1 ALT="">
<!-- End MIT-use only web reporting counter -->
</BODY></HTML>
<!-- end bbinclude -->