# 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.