KIM Options Reference Documentation

Functions

Function Documentation

kim_error_t kim_options_create (  kim_options_t *  out_options  ) 
 

Create new options with default values.

Parameters:
out_options on exit, a new options object. Must be freed with kim_options_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.

kim_error_t kim_options_copy (  kim_options_t *  out_options,
kim_options_t  in_options
) 
 

Copy options.

Parameters:
out_options on exit, a new options object which is a copy of in_options. Must be freed with kim_options_free().
in_options a options object.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.

kim_error_t kim_options_set_prompt_callback (  kim_options_t  io_options,
kim_prompt_callback_t  in_prompt_callback
) 
 

Set the prompt callback for obtaining information from the user.

Parameters:
io_options an options object to modify.
in_prompt_callback a prompt callback function.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Default value
kim_prompt_callback_default
See also:
kim_options_get_prompt_callback()

kim_error_t kim_options_get_prompt_callback (  kim_options_t  in_options,
kim_prompt_callback_t *  out_prompt_callback
) 
 

Get the prompt callback for obtaining information from the user.

Parameters:
in_options an options object.
out_prompt_callback on exit, the prompt callback specified by in_options. Does not need to be freed but may become invalid when in_options is freed.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Default value
kim_prompt_callback_default
See also:
kim_options_set_prompt_callback()

kim_error_t kim_options_set_data (  kim_options_t  io_options,
void *  in_data
) 
 

Set caller-specific data for use in library callbacks.

Parameters:
io_options an options object to modify.
in_data a pointer to caller-specific data.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Note:
This option can be used by the caller to store a pointer to data needed when handling a callback. The KIM library does not use this options data in any way.
Default value
NULL (no data is set by default)
See also:
kim_options_get_data()

kim_error_t kim_options_get_data (  kim_options_t  in_options,
void **  out_data
) 
 

Get caller-specific data for use in library callbacks.

Parameters:
in_options an options object.
out_data on exit, the pointer to caller specific data specified by in_options. Does not need to be freed but may become invalid when in_options is freed.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Note:
This option can be used by the caller to store a pointer to data needed when handling a callback. The KIM library does not use this options data in any way.
Default value
NULL (no data is set by default)
See also:
kim_options_set_data()

kim_error_t kim_options_set_prompt_response (  kim_options_t  io_options,
kim_prompt_type_t  in_prompt_type,
void *  in_response
) 
 

Set a response for a prompt for use when acquiring credentials.

Parameters:
io_options an options object to modify.
in_prompt_type a type of prompt.
in_response a response to prompts of in_prompt_type.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Note:
Each response only overrides the first prompt of a given prompt type. If multiple prompts of the same type are required, or if a prompt of a different type is requested, the prompt callback will be called to obtain user input. If you want to turn off prompting entirely, call kim_options_set_prompt_callback() with kim_prompt_callback_none.
Default value
NULL (no response is set by default)
See also:
kim_options_get_prompt_response()

kim_error_t kim_options_get_prompt_response (  kim_options_t  in_options,
kim_prompt_type_t  in_prompt_type,
void **  out_response
) 
 

Get the response for a prompt for use when acquiring credentials.

Parameters:
in_options an options object.
in_prompt_type a type of prompt.
out_response on exit, the response to prompts of type in_prompt_type specified by in_options. Does not need to be freed but may become invalid when in_options is freed.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Note:
Each response only overrides the first prompt of a given prompt type. If multiple prompts of the same type are required, or if a prompt of a different type is requested, the prompt callback will be called to obtain user input. If you want to turn off prompting entirely, call kim_options_set_prompt_callback() with kim_prompt_callback_none.
Default value
NULL (no response is set by default)
See also:
kim_options_set_prompt_response()

kim_error_t kim_options_set_start_time (  kim_options_t  io_options,
kim_time_t  in_start_time
) 
 

Set the date when a credential should become valid.

Parameters:
io_options an options object to modify.
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.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
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.
Default value
0, indicating "now". The credential will be valid immediately.
See also:
kim_options_get_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate()

kim_error_t kim_options_get_start_time (  kim_options_t  in_options,
kim_time_t *  out_start_time
) 
 

Get the date when a credential should become valid.

Parameters:
in_options an options object.
out_start_time on exit, the start date (in seconds since January 1, 1970) specified by in_options. KIM_OPTIONS_START_IMMEDIATELY indicates the credential will be valid immediately.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
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.
Default value
0, indicating "now". The credential will be valid immediately.
See also:
kim_options_set_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate()

kim_error_t kim_options_set_lifetime (  kim_options_t  io_options,
kim_lifetime_t  in_lifetime
) 
 

Set the duration during which a credential should be valid.

Parameters:
io_options an options object to modify.
in_lifetime a lifetime duration (in seconds).
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
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 in_lifetime and the KDC's maximum allowed lifetime.
See also:
kim_options_get_lifetime()
Default value
Read from the user's preferences and the Kerberos configuration. 10 hours if unspecified.

kim_error_t kim_options_get_lifetime (  kim_options_t  in_options,
kim_lifetime_t *  out_lifetime
) 
 

Get the duration during which an acquired credential should be valid.

Parameters:
in_options an options object.
out_lifetime on exit, the lifetime duration (in seconds) specified in in_options.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
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 in_lifetime and the KDC's maximum allowed lifetime.
Default value
Read from the user's preferences and the Kerberos configuration. 10 hours if unspecified.
See also:
kim_options_set_lifetime()

kim_error_t kim_options_set_renewable (  kim_options_t  io_options,
kim_boolean_t  in_renewable
) 
 

Set whether or not to request a renewable credential.

Parameters:
io_options an options object to modify.
in_renewable a boolean value indicating whether or not to request a renewable credential.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
See also:
kim_options_get_renewable()

kim_error_t kim_options_get_renewable (  kim_options_t  in_options,
kim_boolean_t *  out_renewable
) 
 

Get whether or not to request a renewable credential.

Parameters:
in_options an options object.
out_renewable on exit, a boolean value indicating whether or in_options will request a renewable credential.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
See also:
kim_options_set_renewable()

kim_error_t kim_options_set_renewal_lifetime (  kim_options_t  io_options,
kim_lifetime_t  in_renewal_lifetime
) 
 

Set the duration during which a valid credential should be renewable.

Parameters:
io_options an options object to modify.
in_renewal_lifetime a renewal lifetime duration (in seconds).
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
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 in_lifetime and the KDC's maximum allowed lifetime.
Default value
Read from the user's preferences and the Kerberos configuration. 7 days if unspecified.
See also:
kim_options_get_renewal_lifetime(), kim_identity_renew(), kim_credential_renew(), kim_ccache_renew()

kim_error_t kim_options_get_renewal_lifetime (  kim_options_t  in_options,
kim_lifetime_t *  out_renewal_lifetime
) 
 

Get the duration during which a valid credential should be renewable.

Parameters:
in_options an options object.
out_renewal_lifetime on exit, the renewal lifetime duration (in seconds) specified in in_options.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
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 in_lifetime and the KDC's maximum allowed lifetime.
Default value
Read from the user's preferences and the Kerberos configuration. 7 days if unspecified.
See also:
kim_options_set_renewal_lifetime(), kim_identity_renew(), kim_credential_renew(), kim_ccache_renew()

kim_error_t kim_options_set_forwardable (  kim_options_t  io_options,
kim_boolean_t  in_forwardable
) 
 

Set whether or not to request a forwardable credential.

Parameters:
io_options an options object to modify.
in_forwardable a boolean value indicating whether or not to request a forwardable credential.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
See also:
kim_options_get_forwardable()

kim_error_t kim_options_get_forwardable (  kim_options_t  in_options,
kim_boolean_t *  out_forwardable
) 
 

Get whether or not to request a forwardable credential.

Parameters:
in_options an options object.
out_forwardable on exit, a boolean value indicating whether or in_options will request a forwardable credential.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
See also:
kim_options_set_forwardable()

kim_error_t kim_options_set_proxiable (  kim_options_t  io_options,
kim_boolean_t  in_proxiable
) 
 

Set whether or not to request a proxiable credential.

Parameters:
io_options an options object to modify.
in_proxiable a boolean value indicating whether or not to request a proxiable credential.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
See also:
kim_options_get_proxiable()

kim_error_t kim_options_get_proxiable (  kim_options_t  in_options,
kim_boolean_t *  out_proxiable
) 
 

Get whether or not to request a proxiable credential.

Parameters:
in_options an options object.
out_proxiable on exit, a boolean value indicating whether or in_options will request a proxiable credential.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
See also:
kim_options_set_proxiable()

kim_error_t kim_options_set_addressless (  kim_options_t  io_options,
kim_boolean_t  in_addressless
) 
 

Set whether or not to request an addressless credential.

Parameters:
io_options an options object to modify.
in_addressless a boolean value indicating whether or not to request an addressless credential.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
See also:
kim_options_get_addressless()

kim_error_t kim_options_get_addressless (  kim_options_t  in_options,
kim_boolean_t *  out_addressless
) 
 

Get whether or not to request an addressless credential.

Parameters:
in_options an options object.
out_addressless on exit, a boolean value indicating whether or in_options will request an addressless credential.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
See also:
kim_options_set_addressless()

kim_error_t kim_options_set_service_identity (  kim_options_t  io_options,
kim_identity_t  in_service_identity
) 
 

Set the service identity to request a credential for.

Parameters:
io_options an options object to modify.
in_service_identity a service identity.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Default value
NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.
See also:
kim_options_get_service_identity()

kim_error_t kim_options_get_service_identity (  kim_options_t  in_options,
kim_identity_t *  out_service_identity
) 
 

Get the service identity to request a credential for.

Parameters:
in_options an options object.
out_service_identity on exit, the service identity specified in in_options. Must be freed with kim_identity_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Default value
NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.
See also:
kim_options_set_service_identity()

void kim_options_free (  kim_options_t *  io_options  ) 
 

Free memory associated with an options object.

Parameters:
io_options the options object to be freed. Set to NULL on exit.