From 3616d31222f94d3f8f3ee23a094dce20ddab719d Mon Sep 17 00:00:00 2001 From: Alexandra Ellwood Date: Wed, 1 Oct 2008 22:43:19 +0000 Subject: [PATCH] Updated documentation to reflect new APIs and re-ran Doxygen ticket: 6055 git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@20806 dc483132-0cff-0310-8789-dd5450dbe970 --- ...oup__kim__ccache__iterator__reference.html | 2 +- .../html/group__kim__ccache__reference.html | 133 ++++++++++- ..._kim__credential__iterator__reference.html | 2 +- .../group__kim__credential__reference.html | 164 ++++--------- .../html/group__kim__identity__reference.html | 43 +++- .../html/group__kim__library__reference.html | 225 ++++++++++++++++++ .../html/group__kim__options__reference.html | 2 +- .../group__kim__preferences__reference.html | 4 +- ...oup__kim__selection__hints__reference.html | 198 +++++++-------- .../html/group__kim__string__reference.html | 20 +- .../html/group__kim__types__reference.html | 56 ++--- doc/kim/html/index.html | 8 +- doc/kim/html/kim_ccache_overview.html | 5 +- doc/kim/html/kim_credential_overview.html | 9 +- doc/kim/html/kim_identity_overview.html | 4 +- doc/kim/html/kim_options_overview.html | 2 +- doc/kim/html/kim_preferences_overview.html | 2 +- .../html/kim_selection_hints_overview.html | 6 +- doc/kim/html/kim_string_overview.html | 8 +- doc/kim/html/modules.html | 4 +- src/include/kim/kim.h | 7 - src/include/kim/kim_ccache.h | 8 +- src/include/kim/kim_credential.h | 10 +- src/include/kim/kim_identity.h | 4 +- src/include/kim/kim_library.h | 37 ++- src/include/kim/kim_preferences.h | 2 +- src/include/kim/kim_selection_hints.h | 27 ++- src/include/kim/kim_string.h | 2 +- src/include/kim/kim_types.h | 30 +-- 29 files changed, 685 insertions(+), 339 deletions(-) create mode 100644 doc/kim/html/group__kim__library__reference.html diff --git a/doc/kim/html/group__kim__ccache__iterator__reference.html b/doc/kim/html/group__kim__ccache__iterator__reference.html index 1c5700d76..21e20b04a 100644 --- a/doc/kim/html/group__kim__ccache__iterator__reference.html +++ b/doc/kim/html/group__kim__ccache__iterator__reference.html @@ -107,7 +107,7 @@ Free memory associated with a ccache iterator.

Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +

Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by

1.5.3

diff --git a/doc/kim/html/group__kim__ccache__reference.html b/doc/kim/html/group__kim__ccache__reference.html index 025b166a8..ac7d22be4 100644 --- a/doc/kim/html/group__kim__ccache__reference.html +++ b/doc/kim/html/group__kim__ccache__reference.html @@ -14,10 +14,12 @@

Find a ccache containing a valid initial credential in the cache collection, or if unavailable, acquire and store a new initial credential.

kim_error kim_ccache_create_from_client_identity (kim_ccache *out_ccache, kim_identity in_client_identity)

Find a ccache for a client identity in the cache collection.

kim_error kim_ccache_create_from_keytab (kim_ccache *out_ccache, kim_identity in_identity, kim_options in_options, kim_string in_keytab)

Acquire a new initial credential from a keytab and store it in a ccache.

kim_error kim_ccache_create_from_default (kim_ccache *out_ccache) -

Get the default ccache.

kim_error kim_ccache_create_from_type_and_name (kim_ccache *out_ccache, kim_string in_type, kim_string in_name) +

Get the default ccache.

kim_error kim_ccache_create_from_display_name (kim_ccache *out_ccache, kim_string in_display_name) +

Get a ccache for a ccache display name.

kim_error kim_ccache_create_from_type_and_name (kim_ccache *out_ccache, kim_string in_type, kim_string in_name)

Get a ccache for a ccache type and name.

kim_error kim_ccache_create_from_krb5_ccache (kim_ccache *out_ccache, krb5_context in_krb5_context, krb5_ccache in_krb5_ccache)

Get a ccache for a krb5 ccache.

kim_error kim_ccache_copy (kim_ccache *out_ccache, kim_ccache in_ccache) -

Copy a ccache.

kim_error kim_ccache_get_krb5_ccache (kim_ccache in_ccache, krb5_context in_krb5_context, krb5_ccache *out_krb5_ccache) +

Copy a ccache.

kim_error kim_ccache_compare (kim_ccache in_ccache, kim_ccache in_compare_to_ccache, kim_comparison *out_comparison) +

Compare ccache objects.

kim_error kim_ccache_get_krb5_ccache (kim_ccache in_ccache, krb5_context in_krb5_context, krb5_ccache *out_krb5_ccache)

Get a krb5 ccache for a ccache.

kim_error kim_ccache_get_name (kim_ccache in_ccache, kim_string *out_name)

Get the name of a ccache.

kim_error kim_ccache_get_type (kim_ccache in_ccache, kim_string *out_type)

Get the type of a ccache.

kim_error kim_ccache_get_display_name (kim_ccache in_ccache, kim_string *out_display_name) @@ -27,7 +29,8 @@

Check the state of the credentials in a ccache (valid, expired, postdated, etc).

kim_error kim_ccache_get_start_time (kim_ccache in_ccache, kim_time *out_start_time)

Get the time when the credentials in the ccache become valid.

kim_error kim_ccache_get_expiration_time (kim_ccache in_ccache, kim_time *out_expiration_time)

Get the time when the credentials in the ccache will expire.

kim_error kim_ccache_get_renewal_expiration_time (kim_ccache in_ccache, kim_time *out_renewal_expiration_time) -

Get the time when the credentials in the ccache will no longer be renewable.

kim_error kim_ccache_set_default (kim_ccache io_ccache) +

Get the time when the credentials in the ccache will no longer be renewable.

kim_error kim_ccache_get_options (kim_ccache in_ccache, kim_options *out_options) +

Get a kim_options object based on a ccache's credential attributes.

kim_error kim_ccache_set_default (kim_ccache io_ccache)

Set a ccache to the default ccache.

kim_error kim_ccache_verify (kim_ccache in_ccache, kim_identity in_service_identity, kim_string in_keytab, kim_boolean in_fail_if_no_service_key)

Verify the TGT in a ccache.

kim_error kim_ccache_renew (kim_ccache in_ccache, kim_options in_options)

Renew the TGT in a ccache.

kim_error kim_ccache_validate (kim_ccache in_ccache, kim_options in_options) @@ -243,6 +246,45 @@ Get the default ccache.

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

+ +

+ + + + + + + + + + + + + + + + + + +

kim_error kim_ccache_create_from_display_name	(	kim_ccache *	out_ccache,
		kim_string	in_display_name
	)

+ +

+Get a ccache for a ccache display name. +

Parameters:

+ + + +

	out_ccache	on exit, a ccache object for the ccache identified by in_display_name. Must be freed with kim_ccache_free().
	in_display_name	a ccache display name string (ie: "TYPE:NAME").

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

Note:: This API is used to obtain a kim_ccache for a ccache name entered by the user.

@@ -372,6 +414,51 @@ Copy a ccache.

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

+ +

+ + + + + + + + + + + + + + + + + + + + + + + + +

kim_error kim_ccache_compare	(	kim_ccache	in_ccache,
		kim_ccache	in_compare_to_ccache,
		kim_comparison *	out_comparison
	)

+ +

+Compare ccache objects. +

Parameters:

+ + + + +

	in_ccache	a ccache object.
	in_compare_to_ccache	a ccache object.
	out_comparison	on exit, a comparison of in_ccache and in_compare_to_ccache which determines whether or not the two ccache objects refer to the same ccache.

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

@@ -761,6 +848,44 @@ Get the time when the credentials in the ccache will no longer be renewable.

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

+ +

+ + + + + + + + + + + + + + + + + + +

kim_error kim_ccache_get_options	(	kim_ccache	in_ccache,
		kim_options *	out_options
	)

+ +

+Get a kim_options object based on a ccache's credential attributes. +

Parameters:

+ + + +

	in_ccache	a ccache object.
	out_options	on exit, an options object reflecting the ticket options of the credentials in in_ccache.

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

@@ -977,7 +1102,7 @@ Free memory associated with a ccache.

Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +

Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by

1.5.3

diff --git a/doc/kim/html/group__kim__credential__iterator__reference.html b/doc/kim/html/group__kim__credential__iterator__reference.html index 1bcae59b0..f7905d77d 100644 --- a/doc/kim/html/group__kim__credential__iterator__reference.html +++ b/doc/kim/html/group__kim__credential__iterator__reference.html @@ -117,7 +117,7 @@ Free memory associated with a credential iterator.

Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +

Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by

1.5.3

diff --git a/doc/kim/html/group__kim__credential__reference.html b/doc/kim/html/group__kim__credential__reference.html index 460b065ae..5bb99fad2 100644 --- a/doc/kim/html/group__kim__credential__reference.html +++ b/doc/kim/html/group__kim__credential__reference.html @@ -12,8 +12,7 @@

kim_error kim_credential_create_new (kim_credential *out_credential, kim_identity in_client_identity, kim_options in_options)

Acquire a new initial credential.

kim_error kim_credential_create_from_keytab (kim_credential *out_credential, kim_identity in_identity, kim_options in_options, kim_string in_keytab)

Acquire a new initial credential from a keytab.

kim_error kim_credential_create_from_krb5_creds (kim_credential *out_credential, krb5_context in_krb5_context, krb5_creds *in_krb5_creds) -

Copy a credential from a krb5 credential object.

kim_error kim_credential_create_for_change_password (kim_credential *out_credential, kim_identity in_identity, kim_string in_old_password) -

Obtain a credential for changing an identity's password.

kim_error kim_credential_copy (kim_credential *out_credential, kim_credential in_credential) +

Copy a credential from a krb5 credential object.

kim_error kim_credential_copy (kim_credential *out_credential, kim_credential in_credential)

Copy a credential object.

kim_error kim_credential_get_krb5_creds (kim_credential in_credential, krb5_context in_krb5_context, krb5_creds **out_krb5_creds)

Get a krb5 credentials object for a credential object.

kim_error kim_credential_get_client_identity (kim_credential in_credential, kim_identity *out_client_identity)

Get the client identity of a credential object.

kim_error kim_credential_get_service_identity (kim_credential in_credential, kim_identity *out_service_identity) @@ -22,12 +21,12 @@

Check the state of a credential (valid, expired, postdated, etc).

kim_error kim_credential_get_start_time (kim_credential in_credential, kim_time *out_start_time)

Get the time when the credentials become valid.

kim_error kim_credential_get_expiration_time (kim_credential in_credential, kim_time *out_expiration_time)

Get the time when the credentials will expire.

kim_error kim_credential_get_renewal_expiration_time (kim_credential in_credential, kim_time *out_renewal_expiration_time) -

Get the time when the credentials will no longer be renewable.

kim_error kim_credential_store (kim_credential in_credential, kim_identity in_client_identity, kim_ccache *out_ccache) +

Get the time when the credentials will no longer be renewable.

kim_error kim_credential_get_options (kim_credential in_credential, kim_options *out_options) +

Get a kim_options object based on a credential's attributes.

kim_error kim_credential_store (kim_credential in_credential, kim_identity in_client_identity, kim_ccache *out_ccache)

Store a credential in a ccache in the cache collection.

kim_error kim_credential_verify (kim_credential in_credential, kim_identity in_service_identity, kim_string in_keytab, kim_boolean in_fail_if_no_service_key)

Verify a TGT credential.

kim_error kim_credential_renew (kim_credential *io_credential, kim_options in_options)

Renew a TGT credential.

kim_error kim_credential_validate (kim_credential *io_credential, kim_options in_options) -

Validate a TGT credential.

kim_error kim_credential_change_password (kim_credential in_credential, kim_identity in_identity, kim_string in_new_password, kim_error *out_rejected_err, kim_string *out_rejected_message, kim_string *out_rejected_description) -

Change an identity's password.

void kim_credential_free (kim_credential *io_credential) +

Validate a TGT credential.

void kim_credential_free (kim_credential *io_credential)

Free memory associated with a credential object.

Function Documentation

@@ -173,52 +172,6 @@ Copy a credential from a krb5 credential object.

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

- -

- - - - - - - - - - - - - - - - - - - - - - - - -

kim_error kim_credential_create_for_change_password	(	kim_credential *	out_credential,
		kim_identity	in_identity,
		kim_string	in_old_password
	)

- -

-Obtain a credential for changing an identity's password. -

Parameters:

- - - - -

	out_credential	on exit, a new credential object containing a change password credential for in_identity. Must be freed with kim_credential_free().
	in_identity	a client identity to obtain a change password credential for.
	in_old_password	the current password for in_identity. May be an expired password.

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

See also:: kim_credential_change_password

@@ -565,12 +518,50 @@ Get the time when the credentials will no longer be renewable.

Parameters:

- +

	in_credential	a credential object.
	out_renewal_expiration_time	on exit, the time when in_credential will no longer be renewable. May be in the past or future.
	out_renewal_expiration_time	on exit, the time when in_credential will no longer be renewable. May be in the past or future. If credentials are not renewable at all, returns 0.

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

See also:: kim_ccache_get_renewal_expiration_time

+ +

+ + + + + + + + + + + + + + + + + + +

kim_error kim_credential_get_options	(	kim_credential	in_credential,
		kim_options *	out_options
	)

+ +

+Get a kim_options object based on a credential's attributes. +

Parameters:

+ + + +

	in_credential	a credential object.
	out_options	on exit, an options object reflecting the ticket options of in_credential.

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

@@ -748,73 +739,6 @@ Validate a TGT credential.

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

See also:: kim_ccache_validate

- -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

kim_error kim_credential_change_password	(	kim_credential	in_credential,
		kim_identity	in_identity,
		kim_string	in_new_password,
		kim_error *	out_rejected_err,
		kim_string *	out_rejected_message,
		kim_string *	out_rejected_description
	)

- -

-Change an identity's password. -

Parameters:

- - - - - - - -

	in_credential	a credential object containing a change password credential. Use kim_credential_change_password to obtain a change password credential.
	in_identity	an identity to change the password for. May be different than the identity the credential is for.
	in_new_password	the password to change the identity to.
	out_rejected_err	on exit, 0 if the password change was successful or an error describing why the new password was rejected.
	out_rejected_message	on exit, if out_rejected_err is non-zero this argument will contain an error message for out_rejected_err. Pass NULL if you do not want this error string. Must be freed with kim_string_free();
	out_rejected_description	on exit, if out_rejected_err is non-zero this argument will contain an string describing why in_new_password was rejected. Pass NULL if you do not want this error string. Must be freed with kim_string_free();

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

See also:: kim_credential_create_for_change_password

@@ -844,7 +768,7 @@ Free memory associated with a credential object.

Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +

Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by

1.5.3

diff --git a/doc/kim/html/group__kim__identity__reference.html b/doc/kim/html/group__kim__identity__reference.html index 9895406a2..9a0bf521c 100644 --- a/doc/kim/html/group__kim__identity__reference.html +++ b/doc/kim/html/group__kim__identity__reference.html @@ -19,7 +19,8 @@

Get a human-readable string representation of an identity.

kim_error kim_identity_get_realm (kim_identity in_identity, kim_string *out_realm_string)

Get the realm string of an identity.

kim_error kim_identity_get_number_of_components (kim_identity in_identity, kim_count *out_number_of_components)

Get the number of components of an identity.

kim_error kim_identity_get_component_at_index (kim_identity in_identity, kim_count in_index, kim_string *out_component_string) -

Get the Nth component of an identity.

kim_error kim_identity_get_krb5_principal (kim_identity in_identity, krb5_context in_krb5_context, krb5_principal *out_krb5_principal) +

Get the Nth component of an identity.

kim_error kim_identity_get_components_string (kim_identity in_identity, kim_string *out_components) +

Get a display string of the non-realm components of an identity.

kim_error kim_identity_get_krb5_principal (kim_identity in_identity, krb5_context in_krb5_context, krb5_principal *out_krb5_principal)

Get the krb5_principal representation of an identity.

kim_error kim_identity_change_password (kim_identity in_identity)

Change the password for an identity.

void kim_identity_free (kim_identity *io_identity)

Free memory associated with an identity.

@@ -440,6 +441,44 @@ Get the Nth component of an identity.

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

+ +

+ + + + + + + + + + + + + + + + + + +

kim_error kim_identity_get_components_string	(	kim_identity	in_identity,
		kim_string *	out_components
	)

+ +

+Get a display string of the non-realm components of an identity. +

Parameters:

+ + + +

	in_identity	an identity object.
	out_components	on exit, a string of the non-realm components of in_identity separated by '/' characters. Must be freed with kim_string_free().

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

@@ -543,7 +582,7 @@ Free memory associated with an identity.

Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +

Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by

1.5.3

diff --git a/doc/kim/html/group__kim__library__reference.html b/doc/kim/html/group__kim__library__reference.html new file mode 100644 index 000000000..63b430d16 --- /dev/null +++ b/doc/kim/html/group__kim__library__reference.html @@ -0,0 +1,225 @@ + + +Kerberos Identity Management: KIM Library Documentation + + + + +

KIM Library Documentation

Defines

#define KIM_UI_ENVIRONMENT_NONE 0 +
#define KIM_UI_ENVIRONMENT_AUTO 1 +
#define KIM_UI_ENVIRONMENT_GUI 2 +
#define KIM_UI_ENVIRONMENT_CLI 3 +

Typedefs

typedef int kim_ui_environment +

Functions

kim_error kim_library_set_ui_environment (kim_ui_environment in_ui_environment) +
Tell KIM how to present UI from your application.
kim_error kim_library_set_allow_home_directory_access (kim_boolean in_allow_access) +
Tells KIM whether or not it is allowed to touch the user's home directory.
kim_error kim_library_set_allow_automatic_prompting (kim_boolean in_allow_automatic_prompting) +
Tells KIM whether or not it is allowed to automatically present user interface.
kim_error kim_library_set_application_name (kim_string in_application_name) +
Set the name of your application for KIM to use for user interface.

Define Documentation

+ +

+ + + + +

#define KIM_UI_ENVIRONMENT_NONE 0

+ +

+Do not present user interface +

+ +

+ + + + +

#define KIM_UI_ENVIRONMENT_AUTO 1

+ +

+Automatically determine what user interface is appropriate (default). +

+ +

+ + + + +

#define KIM_UI_ENVIRONMENT_GUI 2

+ +

+Present a graphical user interface +

+ +

+ + + + +

#define KIM_UI_ENVIRONMENT_CLI 3

+ +

+Present a command line user interface +

Typedef Documentation

+ +

+ + + + +

typedef int kim_ui_environment

+ +

+An integer describing the type of user interface to use. +

Function Documentation

+ +

+ + + + + + + + + +

kim_error kim_library_set_ui_environment ( kim_ui_environment in_ui_environment )

+ +

+Tell KIM how to present UI from your application. +

Parameters:

+ + +

in_ui_environment

an integer value describing the type of user interface to use.

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

Note:: Set to KIM_UI_ENVIRONMENT_AUTO by default.

+ +

+ + + + + + + + + +

kim_error kim_library_set_allow_home_directory_access ( kim_boolean in_allow_access )

+ +

+Tells KIM whether or not it is allowed to touch the user's home directory. +

Parameters:

+ + +

in_allow_access

a boolean containing whether or not to touch the user's home directory.

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

Note:: This API is usually used for Kerberos authenticated home directories to prevent a deadlock.

+ +

+ + + + + + + + + +

kim_error kim_library_set_allow_automatic_prompting ( kim_boolean in_allow_automatic_prompting )

+ +

+Tells KIM whether or not it is allowed to automatically present user interface. +

Parameters:

+ + +

in_allow_automatic_prompting

a boolean containing whether or not to prompt automatically.

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

+ +

+ + + + + + + + + +

kim_error kim_library_set_application_name ( kim_string in_application_name )

+ +

+Set the name of your application for KIM to use for user interface. +

Parameters:

+ + +

in_application_name

a string containing the localized name of your application.

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

Note:: On many operating systems KIM can determine the caller's application name automatically. This call exists for applications to use when those mechanisms fail or do not exist.

+ +

Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by + +

1.5.3

+ + diff --git a/doc/kim/html/group__kim__options__reference.html b/doc/kim/html/group__kim__options__reference.html index 6a170668d..3c4f5ae62 100644 --- a/doc/kim/html/group__kim__options__reference.html +++ b/doc/kim/html/group__kim__options__reference.html @@ -769,7 +769,7 @@ Free memory associated with an options object.

Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +

Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by

1.5.3

diff --git a/doc/kim/html/group__kim__preferences__reference.html b/doc/kim/html/group__kim__preferences__reference.html index 918a46465..90412e71f 100644 --- a/doc/kim/html/group__kim__preferences__reference.html +++ b/doc/kim/html/group__kim__preferences__reference.html @@ -806,7 +806,7 @@ Get the Nth favorite identity in a preferences object.

Parameters:

- + @@ -982,7 +982,7 @@ Free memory associated with a preferences object.

Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +

Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by

1.5.3

diff --git a/doc/kim/html/group__kim__selection__hints__reference.html b/doc/kim/html/group__kim__selection__hints__reference.html index 06c414464..b1f72bc84 100644 --- a/doc/kim/html/group__kim__selection__hints__reference.html +++ b/doc/kim/html/group__kim__selection__hints__reference.html @@ -9,18 +9,12 @@

Defines

-#define kim_hint_key_client_realm "kim_hint_key_client_realm" -
-#define kim_hint_key_user "kim_hint_key_user" -
-#define kim_hint_key_service_realm "kim_hint_key_service_realm" -
-#define kim_hint_key_service "kim_hint_key_service" -
-#define kim_hint_key_server "kim_hint_key_server" -
-#define kim_hint_key_service_identity "kim_hint_key_service_identity" +
#define kim_hint_key_client_realm "kim_hint_key_client_realm" +
#define kim_hint_key_user "kim_hint_key_user" +
#define kim_hint_key_service_realm "kim_hint_key_service_realm" +
#define kim_hint_key_service "kim_hint_key_service" +
#define kim_hint_key_server "kim_hint_key_server" +
#define kim_hint_key_service_identity "kim_hint_key_service_identity"

Functions

Create a new selection hints object.

kim_error kim_selection_hints_copy (kim_selection_hints *out_selection_hints, kim_selection_hints in_selection_hints)
Copy a selection hints object.
kim_error kim_selection_hints_set_hint (kim_selection_hints io_selection_hints, kim_string in_hint_key, kim_string in_hint_string)
Set the string value of a hint used for identity selection.
kim_error kim_selection_hints_get_hint (kim_selection_hints in_selection_hints, kim_string in_hint_key, kim_string *out_hint_string) -
Get the string value of a hint used for identity selection.
kim_error kim_selection_hints_set_application_name (kim_selection_hints io_selection_hints, kim_string in_application_name) -
Set the application name for use in user interaction.
kim_error kim_selection_hints_get_application_name (kim_selection_hints in_selection_hints, kim_string *out_application_name) -
Get the application name for use in user interaction.
kim_error kim_selection_hints_set_explanation (kim_selection_hints io_selection_hints, kim_string in_explanation) +
Get the string value of a hint used for identity selection.
kim_error kim_selection_hints_set_explanation (kim_selection_hints io_selection_hints, kim_string in_explanation)
Set the strings used to prompt the user to select the identity.
kim_error kim_selection_hints_get_explanation (kim_selection_hints in_selection_hints, kim_string *out_explanation)
Get the strings used to prompt the user to select the identity.
kim_error kim_selection_hints_set_options (kim_selection_hints io_selection_hints, kim_options in_options)
Set the options which will be used if credentials need to be acquired.
kim_error kim_selection_hints_get_options (kim_selection_hints in_selection_hints, kim_options *out_options) @@ -43,6 +35,97 @@
Add an entry for the selection hints to the selection hints cache, replacing any existing entry.
kim_error kim_selection_hints_forget_identity (kim_selection_hints in_selection_hints)
Remove an entry for the selection hints from the selection hints cache.
void kim_selection_hints_free (kim_selection_hints *io_selection_hints)
Free memory associated with a selection hints object.

Define Documentation

+ +

	kim_preferences	a preferences object.
	in_preferences	a preferences object.
	in_index	a index into the identities list (starting at 0).
	out_identity	on exit, the identity at in_index in in_preferences. Must be freed with kim_string_free().
	out_options	on exit, the options associated with identity at in_index in in_favorite_identities. May be KIM_OPTIONS_DEFAULT. Pass NULL if you do not want the options associated with the identity. Must be freed with kim_options_free().

+ + + +

#define kim_hint_key_client_realm "kim_hint_key_client_realm"

+ +

+A client identity in this realm. See KIM Selection Hints Overview for more information +

+ +

+ + + + +

#define kim_hint_key_user "kim_hint_key_user"

+ +

+A client identity whose first component is this user string. See KIM Selection Hints Overview for more information +

+ +

+ + + + +

#define kim_hint_key_service_realm "kim_hint_key_service_realm"

+ +

+A client identity which has obtained a service credential for this realm. See KIM Selection Hints Overview for more information +

+ +

+ + + + +

#define kim_hint_key_service "kim_hint_key_service"

+ +

+A client identity which has obtained a service credential for this service. See KIM Selection Hints Overview for more information +

+ +

+ + + + +

#define kim_hint_key_server "kim_hint_key_server"

+ +

+A client identity which has obtained a service credential for this server. See KIM Selection Hints Overview for more information +

+ +

+ + + + +

#define kim_hint_key_service_identity "kim_hint_key_service_identity"

+ +

+The client identity which has obtained a service credential for this service identity. See KIM Selection Hints Overview for more information +

Function Documentation

@@ -204,91 +287,12 @@ Get the string value of a hint used for identity selection. - +

	in_selection_hints	a selection hints object.
	in_hint_key	A string representing the type of hint to obtain.
	out_hint_string	A string representation of the hint in_hint_key in in_selection_hints. Must be freed with kim_string_free().
	out_hint_string	On exit, a string representation of the hint in_hint_key in in_selection_hints. If the hint is not set, sets the value pointed to by out_hint_string to NULL; Must be freed with kim_string_free().

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

See also:: kim_selection_hints_set_hint()

- -

- - - - - - - - - - - - - - - - - - -

kim_error kim_selection_hints_set_application_name	(	kim_selection_hints	io_selection_hints,
		kim_string	in_application_name
	)

- -

-Set the application name for use in user interaction. -

Parameters:

- - - -

	io_selection_hints	a selection hints object to modify.
	in_application_name	a localized string containing the full name of the application.

Note:: If you do not call this function KIM will attempt to determine the application name at runtime. If that fails (the functionality is only available on some platforms) then KIM will use the application identity string.

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

See also:: kim_selection_hints_get_application_name()

- -

- - - - - - - - - - - - - - - - - - -

kim_error kim_selection_hints_get_application_name	(	kim_selection_hints	in_selection_hints,
		kim_string *	out_application_name
	)

- -

-Get the application name for use in user interaction. -

Parameters:

- - - -

	in_selection_hints	a selection hints object.
	out_application_name	on exit, the localized full name of the application specified in in_selection_hints. Must be freed with kim_string_free().

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

See also:: kim_selection_hints_set_application_name()

@@ -325,7 +329,7 @@ Set the strings used to prompt the user to select the identity. in_explanation a localized string describing why the caller needs the identity. -

Note:: If the application only does one thing (the reason it needs an identity is obvious) then you may not need to call this function. You may still need to call kim_selection_hints_set_application_name()

Note:: If the application only does one thing (the reason it needs an identity is obvious) then you may not need to call this function.

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

See also:: kim_selection_hints_get_explanation()

@@ -740,7 +744,7 @@ Free memory associated with a selection hints object.

Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +

Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by

1.5.3

diff --git a/doc/kim/html/group__kim__string__reference.html b/doc/kim/html/group__kim__string__reference.html index a7ae6aa66..e79bd2229 100644 --- a/doc/kim/html/group__kim__string__reference.html +++ b/doc/kim/html/group__kim__string__reference.html @@ -9,18 +9,18 @@

Functions

kim_error kim_string_create_for_error (kim_string *out_string, kim_error in_error) -
Get a text description of an error.
kim_error kim_string_copy (kim_string *out_string, const kim_string in_string) +
kim_error kim_string_create_for_last_error (kim_string *out_string, kim_error in_error) +
Get a text description of an error suitable for display to the user.
kim_error kim_string_copy (kim_string *out_string, const kim_string in_string)
Copy a string.
kim_error kim_string_compare (kim_string in_string, kim_string in_compare_to_string, kim_comparison *out_comparison)
Compare two strings.
void kim_string_free (kim_string *io_string)
Free memory associated with a string.

Function Documentation

- +

- + @@ -41,16 +41,16 @@

-Get a text description of an error. +Get a text description of an error suitable for display to the user.

Parameters:

kim_error kim_string_create_for_error kim_error kim_string_create_for_last_error ( kim_string * out_string,

- - + +

	out_string	on exit, a human-readable UTF-8 string describing the error represented by in_error. Must be freed with kim_string_free().
	in_error	an error code.
	out_string	On success, a human-readable UTF-8 string describing the error representedby in_error. Must be freed with kim_string_free().
	in_error	an error code. Used to verify that the correct error string will be returned (see note below).

Returns:: On success, KIM_NO_ERROR. On failure,

Note:: If the caller needs an error string, this API should be called immediately after a KIM API returns an error.

Returns:: On success, KIM_NO_ERROR.

Note:: This API is implemented using thread local storage. It should be called immediately after a KIM API returns an error code so that the correct string is returned. The returned copy may then be held by the caller until needed. If in_error does not match the last saved error KIM may return a less descriptive string.

@@ -164,7 +164,7 @@ Free memory associated with a string.

Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +

Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by

1.5.3

diff --git a/doc/kim/html/group__kim__types__reference.html b/doc/kim/html/group__kim__types__reference.html index 473292d25..09a5da6a9 100644 --- a/doc/kim/html/group__kim__types__reference.html +++ b/doc/kim/html/group__kim__types__reference.html @@ -9,10 +9,10 @@

Defines

#define KIM_NO_ERROR ((kim_error) 0)
#define KIM_IDENTITY_ANY ((kim_identity) NULL)
#define KIM_OPTIONS_DEFAULT ((kim_options) NULL)
#define KIM_OPTIONS_START_IMMEDIATELY ((kim_time_t) 0) +
#define KIM_NO_ERROR ((kim_error) 0)
#define kim_comparison_is_less_than(c) (c < 0)
#define kim_comparison_is_equal_to(c) (c == 0)
#define kim_comparison_is_greater_than(c) (c > 0) @@ -26,7 +26,6 @@
typedef uint64_t kim_count
typedef int kim_boolean
typedef int kim_comparison -
typedef const char * kim_context
typedef const char * kim_string
typedef struct
kim_identity_opaque * kim_identity @@ -58,64 +57,64 @@ kim_credential_opaque * +

- +

#define KIM_NO_ERROR   ((kim_error) 0) #define KIM_IDENTITY_ANY   ((kim_identity) NULL)

-The kim_error_t returned when no error occurred. +Constant to specify any Kerberos identity is acceptable.

- +

- +

#define KIM_IDENTITY_ANY   ((kim_identity) NULL) #define KIM_OPTIONS_DEFAULT   ((kim_options) NULL)

-Constant to specify any Kerberos identity is acceptable. +Specifies the user's default options.

- +

- +

#define KIM_OPTIONS_DEFAULT   ((kim_options) NULL) #define KIM_OPTIONS_START_IMMEDIATELY   ((kim_time_t) 0)

-Specifies the user's default options. +Specifies that credentials should be valid immediately.

- +

- +

#define KIM_OPTIONS_START_IMMEDIATELY   ((kim_time_t) 0) #define KIM_NO_ERROR   ((kim_error) 0)

-Specifies that credentials should be valid immediately. +No error value for the kim_error type.

@@ -135,7 +134,7 @@ Specifies that credentials should be valid immediately.

-Convenience macro for interpreting kim_comparison_t. +Convenience macro for interpreting kim_comparison.

@@ -155,7 +154,7 @@ Convenience macro for interpreting kim_comparison_t.

-Convenience macro for interpreting kim_comparison_t. +Convenience macro for interpreting kim_comparison.

@@ -175,7 +174,7 @@ Convenience macro for interpreting kim_comparison_t.

-Convenience macro for interpreting kim_comparison_t. +Convenience macro for interpreting kim_comparison.

Typedef Documentation
@@ -206,7 +205,7 @@ The state of a credential. See
-The KIM Error type. See KIM Error Overview for more information. +The KIM Error type.
@@ -284,25 +283,10 @@ A boolean value. 0 means false, all other values mean true. A comparison between two sortable objects.
- Less than 0 means the first object is less than the second.
- 0 means the two objects are identical.
- Greater than 0 means the first object is greater than the second.
  Note:
  Convenience macros are provided for interpreting kim_comparison_ts to improve code readability. See kim_comparison_is_less_than(), kim_comparison_is_equal() and kim_comparison_is_greater_than()
  +
- Greater than 0 means the first object is greater than the second.
  Note:
  Convenience macros are provided for interpreting kim_comparison values to improve code readability. See kim_comparison_is_less_than(), kim_comparison_is_equal_to() and kim_comparison_is_greater_than()
- -
- -
-
- - - - -
typedef const char* kim_context
-
-
- -
-The KIM Context type. See kim_context_overview for more information.

@@ -422,7 +406,7 @@ A KIM CCache object. See KIM CCach

-A KIM Credential Iterator object. See kim_credential_iterator_t for more information. +A KIM Credential Iterator object. See Iterating over the Credentials in a CCache for more information.

@@ -463,7 +447,7 @@ Possible credential states. Credentials may be:
- kim_credential_is_valid() returns whether the credential is valid and if not why the credential is not valid.
- kim_credential_get_state() returns a kim_credential_state containing the state of the credential. Possible values are: * kim_credentials_state_valid * kim_credentials_state_expired * kim_credentials_state_not_yet_valid * kim_credentials_state_needs_validation * kim_credentials_state_address_mismatch
- kim_credential_get_start_time() returns when the credential will become valid. Credentials may be "post-dated" which means that their lifetime starts sometime in the future. Note that when a post-dated credential's start time is reached, the credential must be validated. See Validating Credentials for more information.
- kim_credential_get_expiration_time() returns when the credential will expire. Credentials are time limited by the lifetime of the credential. While you can request a credential of any lifetime, the KDC limits the credential lifetime to a administrator-defined maximum. Typically credential lifetime range from 10 to 21 hours.
- kim_credential_get_renewal_expiration_time() returns when the credential will no longer be renewable. Valid credentials may be renewed up until their renewal expiration time. Renewing credentials acquires a fresh set of credentials with a full lifetime without resending secrets to the KDC (such as a password). If credentials are not renewable, this function will return an error.
- kim_credential_get_renewal_expiration_time() returns when the credential will no longer be renewable. Valid credentials may be renewed up until their renewal expiration time. Renewing credentials acquires a fresh set of credentials with a full lifetime without resending secrets to the KDC (such as a password). If credentials are not renewable, this function will return a renewal expiration time of 0.
-See KIM Credential Reference Documentation and KIM Credential Iterator Reference Documentation for information on specific APIs.
Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +
+
kim_credential_get_options() returns a kim_options object with the credential options of the credential. This function is intended to be used when adding an identity with existing credentials to the favorite identities list. By passing in the options returned by this call, future requests for the favorite identity will use the same credential options.
+
+See KIM Credential Reference Documentation and KIM Credential Iterator Reference Documentation for information on specific APIs.
Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by 1.5.3
diff --git a/doc/kim/html/kim_identity_overview.html b/doc/kim/html/kim_identity_overview.html index 86717be66..a7c4f76b6 100644 --- a/doc/kim/html/kim_identity_overview.html +++ b/doc/kim/html/kim_identity_overview.html @@ -34,9 +34,9 @@ Unfortunately most of the time applications don't know what client identity to u To solve this problem, kim_selection_hints_get_identity() takes information from the application in the form of a selection hints object and returns the best matching client identity, if one is available. See KIM Selection Hints Overview for more information.
Changing a Identity's Password
Many Kerberos sites use passwords for user accounts. Because passwords may be stolen or compromised, they must be frequently changed. KIM provides APIs to change the identity's password directly, and also handles changing the identity's password when it has expired.
-kim_identity_change_password() presents a user interface to obtain the old and new passwords from the user. kim_identity_change_password_with_passwords() takes the old and new passwords as input, but may still present a user interface if it needs to obtain additional information to authenticate.
+kim_identity_change_password() presents a user interface to obtain the old and new passwords from the user.

Note:
Not all identities have a password. Some sites use certificates (pkinit) and in the future there may be other authentication mechanisms (eg: smart cards).
-See KIM Identity Reference Documentation for information on specific APIs.
Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +See KIM Identity Reference Documentation for information on specific APIs.
Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by 1.5.3
diff --git a/doc/kim/html/kim_options_overview.html b/doc/kim/html/kim_options_overview.html index 2273edebc..4b297df02 100644 --- a/doc/kim/html/kim_options_overview.html +++ b/doc/kim/html/kim_options_overview.html @@ -33,7 +33,7 @@ Like forwardability, the proxiable flag only applies to TGT credentials. Unlike 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.
Service Name
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 name with kim_options_set_service_name() and query it with kim_options_get_service_name().
-See KIM Options Reference Documentation for information on specific APIs.
Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +See KIM Options Reference Documentation for information on specific APIs.
Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by 1.5.3
diff --git a/doc/kim/html/kim_preferences_overview.html b/doc/kim/html/kim_preferences_overview.html index cb12608ca..30c518cda 100644 --- a/doc/kim/html/kim_preferences_overview.html +++ b/doc/kim/html/kim_preferences_overview.html @@ -29,7 +29,7 @@ Viewing and Editing the Favorite Identities First, you need to acquire the Favorite Identities stored in the user's preferences using kim_preferences_create().
Then use kim_preferences_get_number_of_favorite_identities() and kim_preferences_get_favorite_identity_at_index() to display the identities list. Use kim_preferences_add_favorite_identity() and kim_preferences_remove_favorite_identity() to change which identities are in the identities list. Identities are always stored in alphabetical order and duplicate identities are not permitted, so when you add or remove a identity you should redisplay the entire list. If you wish to replace the identities list entirely, use kim_preferences_remove_all_favorite_identities() to clear the list before adding your identities.
Once you are done editing the favorite identities list, store changes in the user's preference file using kim_preferences_synchronize().
-See KIM Preferences Documentation for information on specific APIs.
Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +See KIM Preferences Documentation for information on specific APIs.
Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by 1.5.3
diff --git a/doc/kim/html/kim_selection_hints_overview.html b/doc/kim/html/kim_selection_hints_overview.html index f30bed3ad..5f4a382ea 100644 --- a/doc/kim/html/kim_selection_hints_overview.html +++ b/doc/kim/html/kim_selection_hints_overview.html @@ -29,7 +29,7 @@ For example, if you specify a service identity and a credential for that identit
Note:
Due to performance and information exposure concerns, currently all searching is done by examining the cache collection. In the future the KIM may also make network requests as part of its search algorithm. For example it might check to see if the TGT credentials in each ccache can obtain credentials for the service identity specified by the selection hints.

Selecting an Identity Using Selection Hints
-Once you have provided search criteria for selecting an identity, use kim_selection_hints_get_identity() to obtain an identity object. You can then use kim_identity_get_gss_name() to obtain a gss_name_t for use in gss_acquire_cred() or use kim_ccache_create_from_client_identity() to obtain a ccache containing credentials for the identity.
+Once you have provided search criteria for selecting an identity, use kim_selection_hints_get_identity() to obtain an identity object. You can then use kim_identity_get_string() to obtain a krb5 principal string for use with gss_import_name() and gss_acquire_cred(). Alternatively, you can use kim_ccache_create_from_client_identity() to obtain a ccache containing credentials for the identity.

Note:
kim_selection_hints_get_identity() obtains an identity based on the current state of the selection hints object. If you change the selection hints object you must call kim_selection_hints_get_identity() again.

Selection Hint Caching Behavior
@@ -44,11 +44,11 @@ If you wish to search and prompt for an identity without using the cached mappin Selection Hint Prompting Behavior If valid credentials for identity in the selection hints cache are unavailable or if no identity could be found using searching or caching when kim_selection_hints_get_identity() is called, KIM may present a GUI to ask the user to select an identity or acquire credentials for an identity.

Note:
Because of the caching behavior described above the user will only be prompted to choose an identity when setting up the application or when their identity stops working.
-In order to let the user know why Kerberos needs their assistance, KIM displays the name of the application which requested the identity selection. Unfortunately, some platforms do not provide a runtime mechanism for determining the name of the calling process. If your application runs on one of these platforms (or is cross-platform) you should provide a localized version of its name with kim_selection_hints_set_application_name(). You can check what name will be used with kim_selection_hints_get_application_name().
+In order to let the user know why Kerberos needs their assistance, KIM displays the name of the application which requested the identity selection. Unfortunately, some platforms do not provide a runtime mechanism for determining the name of the calling process. If your application runs on one of these platforms (or is cross-platform) you should provide a localized version of its name with the private function kim_library_set_application_name().
In many cases a single application may select different identities for different purposes. For example an email application might use different identities to check mail for different accounts. If your application has this property you may need to provide the user with a localized string describing how the identity will be used. You can specify this string with kim_selection_hints_get_explanation(). You can find out what string will be used with kim_selection_hints_set_explanation().
Since the user may choose to acquire credentials when selection an identity, KIM also provides kim_selection_hints_set_options() to set what credential acquisition options are used. kim_selection_hints_get_options() returns the options which will be used.
If you need to disable user interaction, use kim_selection_hints_set_allow_user_interaction(). Use kim_selection_hints_get_allow_user_interaction() to find out whether or not user interaction is enabled. User interaction is enabled by default.
-See KIM Selection Hints Reference Documentation for information on specific APIs.
Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +See KIM Selection Hints Reference Documentation for information on specific APIs.
Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by 1.5.3
diff --git a/doc/kim/html/kim_string_overview.html b/doc/kim/html/kim_string_overview.html index f9e9422f9..ced9da69d 100644 --- a/doc/kim/html/kim_string_overview.html +++ b/doc/kim/html/kim_string_overview.html @@ -6,8 +6,12 @@
KIM String Overview
A UTF8 string.
-Memory management routines are provided for runtime consistency on operating systems with shared libraries and multiple runtimes.
-See KIM String Reference Documentation for information on specific APIs.
Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +Memory management routines are provided for runtime consistency on operating systems with shared libraries and multiple runtimes.
+KIM Error Messages
+Like most C APIs, the KIM API returns numeric error codes. These error codes may come from KIM, krb5 or GSS APIs. In most cases the caller will want to handle these error programmatically. However, in some circumstances the caller may wish to print an error string to the user.
+One problem with just printing the error code to the user is that frequently the context behind the error has been lost. For example if KIM is trying to obtain credentials via referrals, it may fail partway through the process. In this case the error code will be KRB5KDC_ERR_C_PRINCIPAL_UNKNOWN, which maps to "Client not found in Kerberos database". Unfortunately this error isn't terribly helpful because it doesn't tell the user whether they typoed their principal name or if referrals failed.
+To avoid this problem, KIM maintains an explanatory string for the last error seen in each thread calling into KIM. If a caller wishes to display an error to the user, immediately after getting the error the caller should call kim_string_create_for_last_error() to obtain a copy of the descriptive error message.
+See KIM String Reference Documentation for information on specific APIs.
Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by 1.5.3
diff --git a/doc/kim/html/modules.html b/doc/kim/html/modules.html index d0e65fa42..ba79467e2 100644 --- a/doc/kim/html/modules.html +++ b/doc/kim/html/modules.html @@ -10,15 +10,15 @@
KIM CCache Reference Documentation
KIM Credential Iterator Reference Documentation
KIM Credential Reference Documentation -
KIM Error Reference Documentation
KIM Identity Reference Documentation +
KIM Library Documentation
KIM Options Reference Documentation
KIM Preferences Documentation
KIM Selection Hints Reference Documentation
KIM String Reference Documentation
KIM Types and Constants

Generated on Mon Sep 22 18:09:05 2008 for Kerberos Identity Management by +

Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by

1.5.3

diff --git a/src/include/kim/kim.h b/src/include/kim/kim.h index 19e82ecb6..050e01b03 100644 --- a/src/include/kim/kim.h +++ b/src/include/kim/kim.h @@ -141,10 +141,6 @@ extern "C" { * - \subpage kim_options_overview * - \subpage kim_options_reference * - * KIM Realms List (kim_favorite_identities_t) views and edits the current user's favorite realms list: - * - \subpage kim_favorite_identities_overview - * - \subpage kim_favorite_identities_reference - * * KIM Preferences (kim_preferences_t) views and edits the current user's preferences: * - \subpage kim_preferences_overview * - \subpage kim_preferences_reference @@ -159,9 +155,6 @@ extern "C" { * - \subpage kim_string_overview * - \subpage kim_string_reference * - * KIM Error (kim_error_t) provides a machine and user-readable error message: - * - \subpage kim_error_overview - * - \subpage kim_error_reference * * * \section types Types and Constants diff --git a/src/include/kim/kim_ccache.h b/src/include/kim/kim_ccache.h index efa9a6dce..d18a5aae4 100644 --- a/src/include/kim/kim_ccache.h +++ b/src/include/kim/kim_ccache.h @@ -415,9 +415,9 @@ kim_error kim_ccache_copy (kim_ccache *out_ccache, * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. * \brief Compare ccache objects. */ -kim_error kim_ccache_compare (kim_ccache in_ccache, - kim_ccache in_compare_to_ccache, - kim_boolean *out_equal); +kim_error kim_ccache_compare (kim_ccache in_ccache, + kim_ccache in_compare_to_ccache, + kim_comparison *out_comparison); /*! * \param in_ccache a ccache object. @@ -531,7 +531,7 @@ kim_error kim_ccache_get_renewal_expiration_time (kim_ccache in_ccache, kim_time *out_renewal_expiration_time); /*! - * \param kim_ccache a ccache object. + * \param in_ccache a ccache object. * \param out_options on exit, an options object reflecting the ticket * options of the credentials in \a in_ccache. * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. diff --git a/src/include/kim/kim_credential.h b/src/include/kim/kim_credential.h index 222d1e760..e1303aeca 100644 --- a/src/include/kim/kim_credential.h +++ b/src/include/kim/kim_credential.h @@ -235,8 +235,14 @@ typedef int kim_credential_state; * additional service credentials without resending shared secrets (such as a password) * to the KDC. Kerberos uses TGTs to provide single sign-on authentication. * - * \li #kim_credential_is_valid() - * returns whether the credential is valid and if not why the credential is not valid. + * \li #kim_credential_get_state() + * returns a #kim_credential_state containing the state of the credential. + * Possible values are: + * * kim_credentials_state_valid + * * kim_credentials_state_expired + * * kim_credentials_state_not_yet_valid + * * kim_credentials_state_needs_validation + * * kim_credentials_state_address_mismatch * * \li #kim_credential_get_start_time() * returns when the credential will become valid. diff --git a/src/include/kim/kim_identity.h b/src/include/kim/kim_identity.h index 8f10168f9..cd50a4080 100644 --- a/src/include/kim/kim_identity.h +++ b/src/include/kim/kim_identity.h @@ -106,9 +106,7 @@ extern "C" { * password when it has expired. * * #kim_identity_change_password() presents a user interface to obtain the old and - * new passwords from the user. #kim_identity_change_password_with_passwords() takes - * the old and new passwords as input, but may still present a user interface if it - * needs to obtain additional information to authenticate. + * new passwords from the user. * * \note Not all identities have a password. Some sites use certificates (pkinit) * and in the future there may be other authentication mechanisms (eg: smart cards). diff --git a/src/include/kim/kim_library.h b/src/include/kim/kim_library.h index bd0e73bb5..681f58e79 100644 --- a/src/include/kim/kim_library.h +++ b/src/include/kim/kim_library.h @@ -28,21 +28,56 @@ #include +/*! + * \defgroup kim_library_reference KIM Library Documentation + * @{ + */ + +/*! Do not present user interface */ #define KIM_UI_ENVIRONMENT_NONE 0 +/*! Automatically determine what user interface is appropriate (default). */ #define KIM_UI_ENVIRONMENT_AUTO 1 +/*! Present a graphical user interface */ #define KIM_UI_ENVIRONMENT_GUI 2 +/*! Present a command line user interface */ #define KIM_UI_ENVIRONMENT_CLI 3 +/*! An integer describing the type of user interface to use. */ typedef int kim_ui_environment; - +/*! + * \param in_ui_environment an integer value describing the type of user interface to use. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \note Set to KIM_UI_ENVIRONMENT_AUTO by default. + * \brief Tell KIM how to present UI from your application. + */ kim_error kim_library_set_ui_environment (kim_ui_environment in_ui_environment); +/*! + * \param in_allow_access a boolean containing whether or not to touch the user's home directory. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \note This API is usually used for Kerberos authenticated home directories to prevent a deadlock. + * \brief Tells KIM whether or not it is allowed to touch the user's home directory. + */ kim_error kim_library_set_allow_home_directory_access (kim_boolean in_allow_access); +/*! + * \param in_allow_automatic_prompting a boolean containing whether or not to prompt automatically. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Tells KIM whether or not it is allowed to automatically present user interface. + */ kim_error kim_library_set_allow_automatic_prompting (kim_boolean in_allow_automatic_prompting); +/*! + * \param in_application_name a string containing the localized name of your application. + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \note On many operating systems KIM can determine the caller's application + * name automatically. This call exists for applications to use when those + * mechanisms fail or do not exist. + * \brief Set the name of your application for KIM to use for user interface. + */ kim_error kim_library_set_application_name (kim_string in_application_name); +/*!@}*/ #endif /* KIM_LIBRARY_H */ diff --git a/src/include/kim/kim_preferences.h b/src/include/kim/kim_preferences.h index fd9797523..bce010cdd 100644 --- a/src/include/kim/kim_preferences.h +++ b/src/include/kim/kim_preferences.h @@ -350,7 +350,7 @@ kim_error kim_preferences_get_number_of_favorite_identities (kim_preferences in kim_count *out_number_of_identities); /*! - * \param kim_preferences a preferences object. + * \param in_preferences a preferences object. * \param in_index a index into the identities list (starting at 0). * \param out_identity on exit, the identity at \a in_index in \a in_preferences. * Must be freed with kim_string_free(). diff --git a/src/include/kim/kim_selection_hints.h b/src/include/kim/kim_selection_hints.h index afeae635e..1abbd0211 100644 --- a/src/include/kim/kim_selection_hints.h +++ b/src/include/kim/kim_selection_hints.h @@ -115,10 +115,10 @@ extern "C" { * * Once you have provided search criteria for selecting an identity, use * #kim_selection_hints_get_identity() to obtain an identity object. - * You can then use #kim_identity_get_gss_name() to obtain a gss_name_t - * for use in gss_acquire_cred() or use - * #kim_ccache_create_from_client_identity() to obtain a ccache containing - * credentials for the identity. + * You can then use #kim_identity_get_string() to obtain a krb5 principal + * string for use with gss_import_name() and gss_acquire_cred(). Alternatively, + * you can use #kim_ccache_create_from_client_identity() to obtain a ccache + * containing credentials for the identity. * * \note #kim_selection_hints_get_identity() obtains an identity based on * the current state of the selection hints object. If you change the @@ -190,7 +190,7 @@ extern "C" { * mechanism for determining the name of the calling process. If your * application runs on one of these platforms (or is cross-platform) * you should provide a localized version of its name with - * #kim_library_set_application_name(). + * the private function #kim_library_set_application_name(). * * In many cases a single application may select different identities for * different purposes. For example an email application might use different @@ -218,11 +218,28 @@ extern "C" { * @{ */ +/*! A client identity in this realm. + * See \ref kim_selection_hints_overview for more information */ #define kim_hint_key_client_realm "kim_hint_key_client_realm" + +/*! A client identity whose first component is this user string. + * See \ref kim_selection_hints_overview for more information */ #define kim_hint_key_user "kim_hint_key_user" + +/*! A client identity which has obtained a service credential for this realm. + * See \ref kim_selection_hints_overview for more information */ #define kim_hint_key_service_realm "kim_hint_key_service_realm" + +/*! A client identity which has obtained a service credential for this service. + * See \ref kim_selection_hints_overview for more information */ #define kim_hint_key_service "kim_hint_key_service" + +/*! A client identity which has obtained a service credential for this server. + * See \ref kim_selection_hints_overview for more information */ #define kim_hint_key_server "kim_hint_key_server" + +/*! The client identity which has obtained a service credential for this service identity. + * See \ref kim_selection_hints_overview for more information */ #define kim_hint_key_service_identity "kim_hint_key_service_identity" /*! diff --git a/src/include/kim/kim_string.h b/src/include/kim/kim_string.h index dfd220ffe..f68f4a409 100644 --- a/src/include/kim/kim_string.h +++ b/src/include/kim/kim_string.h @@ -57,7 +57,7 @@ extern "C" { * To avoid this problem, KIM maintains an explanatory string for the last * error seen in each thread calling into KIM. If a caller wishes to display * an error to the user, immediately after getting the error the caller should - * call #kim_string_create_for_error() to obtain a copy of the + * call #kim_string_create_for_last_error() to obtain a copy of the * descriptive error message. * * See \ref kim_string_reference for information on specific APIs. diff --git a/src/include/kim/kim_types.h b/src/include/kim/kim_types.h index 8cf97246e..a871410bb 100644 --- a/src/include/kim/kim_types.h +++ b/src/include/kim/kim_types.h @@ -37,10 +37,13 @@ extern "C" { */ /*! - * The KIM Error type. See \ref kim_error_overview for more information. + * The KIM Error type. */ typedef int32_t kim_error; +/*! + * No error value for the kim_error type. + */ #define KIM_NO_ERROR ((kim_error) 0) /*! @@ -68,44 +71,33 @@ typedef int kim_boolean; * \li Less than 0 means the first object is less than the second. * \li 0 means the two objects are identical. * \li Greater than 0 means the first object is greater than the second. - * \note Convenience macros are provided for interpreting kim_comparison_ts - * to improve code readability. - * See #kim_comparison_is_less_than(), #kim_comparison_is_equal() and + * \note Convenience macros are provided for interpreting #kim_comparison + * values to improve code readability. + * See #kim_comparison_is_less_than(), #kim_comparison_is_equal_to() and * #kim_comparison_is_greater_than() */ typedef int kim_comparison; /*! - * Convenience macro for interpreting #kim_comparison_t. + * Convenience macro for interpreting #kim_comparison. */ #define kim_comparison_is_less_than(c) (c < 0) /*! - * Convenience macro for interpreting #kim_comparison_t. + * Convenience macro for interpreting #kim_comparison. */ #define kim_comparison_is_equal_to(c) (c == 0) /*! - * Convenience macro for interpreting #kim_comparison_t. + * Convenience macro for interpreting #kim_comparison. */ #define kim_comparison_is_greater_than(c) (c > 0) -/*! - * The KIM Context type. See \ref kim_context_overview for more information. - */ -typedef const char *kim_context; - /*! * The KIM String type. See \ref kim_string_overview for more information. */ typedef const char *kim_string; -//struct kim_error_opaque; -/*! - * A KIM Error object. See \ref kim_error_overview for more information. - */ -//typedef struct kim_error_opaque *kim_error; - struct kim_identity_opaque; /*! * A KIM Principal object. See \ref kim_identity_overview for more information. @@ -144,7 +136,7 @@ typedef struct kim_ccache_opaque *kim_ccache; struct kim_credential_iterator_opaque; /*! - * A KIM Credential Iterator object. See \ref kim_credential_iterator_t for more information. + * A KIM Credential Iterator object. See \ref kim_credential_iterator for more information. */ typedef struct kim_credential_iterator_opaque *kim_credential_iterator; -- 2.26.2