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:
KIM also provides three other callbacks: kim_prompt_callback_gui only presents a dialog and returns an error if there is no graphical access. kim_prompt_callback_cli only presents a command line interface and returns an error if there is no controlling terminal available. kim_prompt_callback_none always returns an error.
Using kim_options_set_prompt_callback(), you can change the prompt callback to one of the above callbacks or a callback you have defined yourself. Callbacks are called in a loop, one for each prompt. Because network traffic may occur between calls to the prompt callback, your prompt interface should support time passing between calls to the prompter. If you are defining a callback yourself, you should also set your own options data with kim_options_set_data() for storing state between calls. Options data is a caller defined pointer value -- the Kerberos libaries make no use of it.
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 kim_prompt_callback_none 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.
Note that setting these properties in the KIM options only changes what the Kerberos libraries 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.
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().
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.
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.
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.
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.
See KIM Options Reference Documentation for information on specific APIs.