KIM Options Reference Documentation

Functions

• kim_error kim_options_create (kim_options *out_options)

  Create new options with default values.
  

• kim_error kim_options_copy (kim_options *out_options, kim_options in_options)

  Copy options.
  

• kim_error kim_options_set_start_time (kim_options io_options, kim_time in_start_time)

  Set the date when a credential should become valid.
  

• kim_error kim_options_get_start_time (kim_options in_options, kim_time *out_start_time)

  Get the date when a credential should become valid.
  

• kim_error kim_options_set_lifetime (kim_options io_options, kim_lifetime in_lifetime)

  Set the duration during which a credential should be valid.
  

• kim_error kim_options_get_lifetime (kim_options in_options, kim_lifetime *out_lifetime)

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

• kim_error kim_options_set_renewable (kim_options io_options, kim_boolean in_renewable)

  Set whether or not to request a renewable credential.
  

• kim_error kim_options_get_renewable (kim_options in_options, kim_boolean *out_renewable)

  Get whether or not to request a renewable credential.
  

• kim_error kim_options_set_renewal_lifetime (kim_options io_options, kim_lifetime in_renewal_lifetime)

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

• kim_error kim_options_get_renewal_lifetime (kim_options in_options, kim_lifetime *out_renewal_lifetime)

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

• kim_error kim_options_set_forwardable (kim_options io_options, kim_boolean in_forwardable)

  Set whether or not to request a forwardable credential.
  

• kim_error kim_options_get_forwardable (kim_options in_options, kim_boolean *out_forwardable)

  Get whether or not to request a forwardable credential.
  

• kim_error kim_options_set_proxiable (kim_options io_options, kim_boolean in_proxiable)

  Set whether or not to request a proxiable credential.
  

• kim_error kim_options_get_proxiable (kim_options in_options, kim_boolean *out_proxiable)

  Get whether or not to request a proxiable credential.
  

• kim_error kim_options_set_addressless (kim_options io_options, kim_boolean in_addressless)

  Set whether or not to request an addressless credential.
  

• kim_error kim_options_get_addressless (kim_options in_options, kim_boolean *out_addressless)

  Get whether or not to request an addressless credential.
  

• kim_error kim_options_set_service_name (kim_options io_options, kim_string in_service_name)

  Set the service name to request a credential for.
  

• kim_error kim_options_get_service_name (kim_options in_options, kim_string *out_service_name)

  Get the service name to request a credential for.
  

• void kim_options_free (kim_options *io_options)

  Free memory associated with an options object.
  

---

Function Documentation

kim_error kim_options_create

(

kim_options *

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 code representing the failure.

kim_error kim_options_copy	(	kim_options *	out_options,
		kim_options	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(). If passed KIM_OPTIONS_DEFAULT will set out_options to KIM_OPTIONS_DEFAULT.
	in_options	a options object.

Returns:

On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_options_set_start_time	(	kim_options	io_options,
		kim_time	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 code 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 kim_options_get_start_time	(	kim_options	in_options,
		kim_time *	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 code 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 kim_options_set_lifetime	(	kim_options	io_options,
		kim_lifetime	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 code 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 kim_options_get_lifetime	(	kim_options	in_options,
		kim_lifetime *	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 code 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 kim_options_set_renewable	(	kim_options	io_options,
		kim_boolean	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 code 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 kim_options_get_renewable	(	kim_options	in_options,
		kim_boolean *	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 code 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 kim_options_set_renewal_lifetime	(	kim_options	io_options,
		kim_lifetime	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 code 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 kim_options_get_renewal_lifetime	(	kim_options	in_options,
		kim_lifetime *	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 code 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 kim_options_set_forwardable	(	kim_options	io_options,
		kim_boolean	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 code 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 kim_options_get_forwardable	(	kim_options	in_options,
		kim_boolean *	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 code 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 kim_options_set_proxiable	(	kim_options	io_options,
		kim_boolean	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 code 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 kim_options_get_proxiable	(	kim_options	in_options,
		kim_boolean *	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 code 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 kim_options_set_addressless	(	kim_options	io_options,
		kim_boolean	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 code 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 kim_options_get_addressless	(	kim_options	in_options,
		kim_boolean *	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 code 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 kim_options_set_service_name	(	kim_options	io_options,
		kim_string	in_service_name
	)

Set the service name to request a credential for.

Parameters:

	io_options	an options object to modify.
	in_service_name	a service name.

Returns:

On success, KIM_NO_ERROR. On failure, an error code representing the failure.

Default value

NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.

See also:

kim_options_get_service_name()

kim_error kim_options_get_service_name	(	kim_options	in_options,
		kim_string *	out_service_name
	)

Get the service name to request a credential for.

Parameters:

	in_options	an options object.
	out_service_name	on exit, the service name specified in in_options. Must be freed with kim_string_free().

Returns:

On success, KIM_NO_ERROR. On failure, an error code representing the failure.

Default value

NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.

See also:

kim_options_set_service_name()

void kim_options_free

(

kim_options *

io_options

)

Free memory associated with an options object.

Parameters:

io_options

the options object to be freed. Set to NULL on exit.

---