From 7c2ed62a0a22160ea954f4f2606aee281f76ad2f Mon Sep 17 00:00:00 2001 From: Alexandra Ellwood Date: Mon, 3 Nov 2008 22:50:08 +0000 Subject: [PATCH] Add _with_password credential acquisition functions to KIM API Needed for kinit password option. ticket: new git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@20963 dc483132-0cff-0310-8789-dd5450dbe970 --- ...oup__kim__ccache__iterator__reference.html | 2 +- .../html/group__kim__ccache__reference.html | 120 +++++++++++++++++- ..._kim__credential__iterator__reference.html | 2 +- .../group__kim__credential__reference.html | 61 ++++++++- .../html/group__kim__identity__reference.html | 2 +- .../html/group__kim__library__reference.html | 2 +- .../html/group__kim__options__reference.html | 4 +- .../group__kim__preferences__reference.html | 4 +- ...oup__kim__selection__hints__reference.html | 2 +- .../html/group__kim__string__reference.html | 2 +- .../html/group__kim__types__reference.html | 2 +- doc/kim/html/index.html | 2 +- doc/kim/html/kim_ccache_overview.html | 3 +- doc/kim/html/kim_credential_overview.html | 3 +- doc/kim/html/kim_identity_overview.html | 2 +- doc/kim/html/kim_options_overview.html | 2 +- doc/kim/html/kim_preferences_overview.html | 2 +- .../html/kim_selection_hints_overview.html | 2 +- doc/kim/html/kim_string_overview.html | 2 +- doc/kim/html/modules.html | 2 +- src/include/kim/kim_ccache.h | 51 +++++++- src/include/kim/kim_credential.h | 28 +++- src/kim/lib/kim.exports | 3 + src/kim/lib/kim_ccache_private.h | 42 ------ src/kim/lib/kim_credential_private.h | 5 - src/kim/lib/kim_private.h | 1 - 26 files changed, 273 insertions(+), 80 deletions(-) delete mode 100644 src/kim/lib/kim_ccache_private.h diff --git a/doc/kim/html/group__kim__ccache__iterator__reference.html b/doc/kim/html/group__kim__ccache__iterator__reference.html index 21e20b04a..4b51443cd 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 Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by +

Generated on Mon Nov 3 17:45:44 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 ac7d22be4..57886e601 100644 --- a/doc/kim/html/group__kim__ccache__reference.html +++ b/doc/kim/html/group__kim__ccache__reference.html @@ -10,8 +10,10 @@

Functions

kim_error kim_ccache_create_new (kim_ccache *out_ccache, kim_identity in_client_identity, kim_options in_options) -
Acquire a new initial credential and store it in a ccache.
kim_error kim_ccache_create_new_if_needed (kim_ccache *out_ccache, kim_identity in_client_identity, kim_options in_options) -
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) +
Acquire a new initial credential and store it in a ccache.
kim_error kim_ccache_create_new_with_password (kim_ccache *out_ccache, kim_identity in_client_identity, kim_options in_options, kim_string in_password) +
Acquire a new initial credential and store it in a ccache using the provided password..
kim_error kim_ccache_create_new_if_needed (kim_ccache *out_ccache, kim_identity in_client_identity, kim_options in_options) +
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_new_if_needed_with_password (kim_ccache *out_ccache, kim_identity in_client_identity, kim_options in_options, kim_string in_password) +
Find a ccache containing a valid initial credential in the cache collection, or if unavailable, acquire and store a new initial credential using the provided password.
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_display_name (kim_ccache *out_ccache, kim_string in_display_name) @@ -79,7 +81,60 @@ Acquire a new initial credential and store it in a ccache. in_options options to control credential acquisition. -

Note:: Depending on the kim_options specified, kim_ccache_create_new() may present a GUI or command line prompt to obtain information from the user.

Note:: kim_ccache_create_new() may present a GUI or command line prompt to obtain information from the user.

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

+ + +

+ +

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

kim_error kim_ccache_create_new_with_password	(	kim_ccache *	out_ccache,
		kim_identity	in_client_identity,
		kim_options	in_options,
		kim_string	in_password
	)

+ +

+Acquire a new initial credential and store it in a ccache using the provided password.. +

Parameters:

+ + + + + +

	out_ccache	on exit, a new cache object for a ccache containing a newly acquired initial credential. Must be freed with kim_ccache_free().
	in_client_identity	a client identity to obtain a credential for. Specify KIM_IDENTITY_ANY to allow the user to choose.
	in_options	options to control credential acquisition.
	in_password	a password to be used while obtaining credentials.

Note:: kim_ccache_create_new_with_password() exists to support legacy password-based Kerberos environments. You should not use this function unless you know that it will only be used in environments using passwords. This function may also present a GUI or command line prompt to obtain additional information needed to obtain credentials (eg: SecurID pin).

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

@@ -125,7 +180,60 @@ Find a ccache containing a valid initial credential in the cache collection, or in_options options to control credential acquisition (if a credential is acquired). -

Note:: Depending on the kim_options specified, kim_ccache_create_new_if_needed() may present a GUI or command line prompt to obtain information from the user.

Note:: kim_ccache_create_new_if_needed() may present a GUI or command line prompt to obtain information from the user.

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

+ +

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

kim_error kim_ccache_create_new_if_needed_with_password	(	kim_ccache *	out_ccache,
		kim_identity	in_client_identity,
		kim_options	in_options,
		kim_string	in_password
	)

+ +

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

Parameters:

+ + + + + +

	out_ccache	on exit, a ccache object for a ccache containing a newly acquired initial credential. Must be freed with kim_ccache_free().
	in_client_identity	a client identity to obtain a credential for.
	in_options	options to control credential acquisition (if a credential is acquired).
	in_password	a password to be used while obtaining credentials.

Note:: kim_ccache_create_new_if_needed_with_password() exists to support legacy password-based Kerberos environments. You should not use this function unless you know that it will only be used in environments using passwords. This function may also present a GUI or command line prompt to obtain additional information needed to obtain credentials (eg: SecurID pin).

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

@@ -161,7 +269,7 @@ Find a ccache for a client identity in the cache collection.

Parameters:

- +

	out_ccache	on exit, a ccache object for a ccache containing a TGT credential. Must be freed with kim_ccache_free().
	in_client_identity	a client identity to obtain a credential for.
	in_client_identity	a client identity to find a ccache for. If in_client_identity is KIM_IDENTITY_ANY, this function returns the default ccache (ie: is equivalent to kim_ccache_create_from_default()).

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

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

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

Generated on Mon Nov 3 17:45:44 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 f7905d77d..770119554 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 Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by +

Generated on Mon Nov 3 17:45:44 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 5bb99fad2..2cd1f787c 100644 --- a/doc/kim/html/group__kim__credential__reference.html +++ b/doc/kim/html/group__kim__credential__reference.html @@ -10,7 +10,8 @@

Functions

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.
kim_error kim_credential_create_new_with_password (kim_credential *out_credential, kim_identity in_client_identity, kim_options in_options, kim_string in_password) +
Acquire a new initial credential using the provided password.
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_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) @@ -70,7 +71,61 @@ Acquire a new initial credential. in_options options to control credential acquisition. -

Note:: Depending on the kim_options specified, kim_credential_create_new() may present a GUI or command line prompt to obtain information from the user.

Note:: kim_credential_create_new() may present a GUI or command line prompt to obtain information from the user.

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

See also:: kim_ccache_create_new

+ + +

+ +

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

kim_error kim_credential_create_new_with_password	(	kim_credential *	out_credential,
		kim_identity	in_client_identity,
		kim_options	in_options,
		kim_string	in_password
	)

+ +

+Acquire a new initial credential using the provided password. +

Parameters:

+ + + + + +

	out_credential	on exit, a new credential object containing a newly acquired initial credential. Must be freed with kim_credential_free().
	in_client_identity	a client identity to obtain a credential for. Specify NULL to allow the user to choose the identity
	in_options	options to control credential acquisition.
	in_password	a password to be used while obtaining the credential.

Note:: kim_credential_create_new_with_password() exists to support legacy password-based Kerberos environments. You should not use this function unless you know that it will only be used in environments using passwords. This function may also present a GUI or command line prompt to obtain additional information needed to obtain credentials (eg: SecurID pin).

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

See also:: kim_ccache_create_new

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

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

Generated on Mon Nov 3 17:45:44 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 9a0bf521c..c975c731c 100644 --- a/doc/kim/html/group__kim__identity__reference.html +++ b/doc/kim/html/group__kim__identity__reference.html @@ -582,7 +582,7 @@ Free memory associated with an identity.

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

Generated on Mon Nov 3 17:45:44 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 index 63b430d16..c646557b7 100644 --- a/doc/kim/html/group__kim__library__reference.html +++ b/doc/kim/html/group__kim__library__reference.html @@ -218,7 +218,7 @@ Set the name of your application for KIM to use for user interface.

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

Generated on Mon Nov 3 17:45:44 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 3c4f5ae62..aea7292d7 100644 --- a/doc/kim/html/group__kim__options__reference.html +++ b/doc/kim/html/group__kim__options__reference.html @@ -88,7 +88,7 @@ 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().
	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.

@@ -769,7 +769,7 @@ Free memory associated with an options object.

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

Generated on Mon Nov 3 17:45:44 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 90412e71f..5320884dd 100644 --- a/doc/kim/html/group__kim__preferences__reference.html +++ b/doc/kim/html/group__kim__preferences__reference.html @@ -172,7 +172,7 @@ Get the user's preferred options.

Parameters:

- +

	in_preferences	a preferences object.
	out_options	on exit, the options specified in in_preferences. Must be freed with kim_options_free().
	out_options	on exit, the options specified in in_preferences. May be KIM_OPTIONS_DEFAULT. If not, must be freed with kim_options_free().

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

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

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

Generated on Mon Nov 3 17:45:44 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 b1f72bc84..a80eb7347 100644 --- a/doc/kim/html/group__kim__selection__hints__reference.html +++ b/doc/kim/html/group__kim__selection__hints__reference.html @@ -744,7 +744,7 @@ Free memory associated with a selection hints object.

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

Generated on Mon Nov 3 17:45:44 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 e79bd2229..31192c96f 100644 --- a/doc/kim/html/group__kim__string__reference.html +++ b/doc/kim/html/group__kim__string__reference.html @@ -164,7 +164,7 @@ Free memory associated with a string.

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

Generated on Mon Nov 3 17:45:44 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 09a5da6a9..a3c037609 100644 --- a/doc/kim/html/group__kim__types__reference.html +++ b/doc/kim/html/group__kim__types__reference.html @@ -447,7 +447,7 @@ Possible credential states. Credentials may be:

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

Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by

1.5.3

diff --git a/doc/kim/html/index.html b/doc/kim/html/index.html index c514f270b..a11d58f64 100644 --- a/doc/kim/html/index.html +++ b/doc/kim/html/index.html @@ -76,7 +76,7 @@ Types and Constants

KIM Types and Constants

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

Generated on Mon Nov 3 17:45:43 2008 for Kerberos Identity Management by

1.5.3

diff --git a/doc/kim/html/kim_ccache_overview.html b/doc/kim/html/kim_ccache_overview.html index 4bb914b72..e6cce0abe 100644 --- a/doc/kim/html/kim_ccache_overview.html +++ b/doc/kim/html/kim_ccache_overview.html @@ -21,6 +21,7 @@ Acquiring Credentials from the Default CCache Acquiring New Credentials in a CCache KIM provides the kim_ccache_create_new() API for acquiring new credentials and storing them in a ccache. Credentials can either be obtained for a specific client identity or by specifying KIM_IDENTITY_ANY to allow the user to choose. Typically callers of this API obtain the client identity using kim_selection_hints_get_identity(). Depending on the kim_options specified, kim_ccache_create_new() may present a GUI or command line prompt to obtain information from the user.

kim_ccache_create_new_if_needed() searches the cache collection for a ccache for the client identity and if no appropriate ccache is available, attempts to acquire new credentials and store them in a new ccache. Depending on the kim_options specified, kim_ccache_create_new_if_needed() may present a GUI or command line prompt to obtain information from the user. This function exists for convenience and to avoid code duplication. It can be trivially implemented using kim_ccache_create_from_client_identity() and kim_ccache_create_new().

+For legacy password-based Kerberos environments KIM also provides kim_ccache_create_new_with_password() and kim_ccache_create_new_if_needed_with_password(). You should not use these functions unless you know that they will only be used in environments using passwords. Otherwise users without passwords may be prompted for them.

KIM provides the kim_ccache_create_from_keytab() to create credentials using a keytab and store them in the cache collection. A keytab is an on-disk copy of a client identity's secret key. Typically sites use keytabs for client identities that identify a machine or service and protect the keytab with disk permissions. Because a keytab is sufficient to obtain credentials, keytabs will normally only be readable by root, Administrator or some other privileged account. Typically applications use credentials obtained from keytabs to obtain credentials for batch processes. These keytabs and credentials are usually for a special identity used for the batch process rather than a user identity.

Validating Credentials in a CCache

A credential with a start time in the future (ie: after the issue date) is called a post-dated credential. Because the KDC administrator may wish to disable a identity, once the start time is reached, all post-dated credentials must be validated before they can be used. Otherwise an attacker using a compromised account could acquire lots of post-dated credentials to circumvent the acccount being disabled.

@@ -62,7 +63,7 @@ Examining CCache Properties

kim_ccache_get_options() returns a kim_options object with the credential options of the credentials in the ccache. 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 CCache Reference Documentation and KIM CCache Iterator Reference Documentation for information on specific APIs.

Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by +See KIM CCache Reference Documentation and KIM CCache Iterator Reference Documentation for information on specific APIs.

Generated on Mon Nov 3 17:45:43 2008 for Kerberos Identity Management by

1.5.3

diff --git a/doc/kim/html/kim_credential_overview.html b/doc/kim/html/kim_credential_overview.html index 894a3d6f7..71f981777 100644 --- a/doc/kim/html/kim_credential_overview.html +++ b/doc/kim/html/kim_credential_overview.html @@ -14,6 +14,7 @@ KIM credential APIs are intended for applications and system tools which manage

Acquiring New Credentials

KIM provides the kim_credential_create_new() API for acquiring new credentials. Credentials can either be obtained for a specific client identity or by specifying KIM_IDENTITY_ANY to allow the user to choose. Typically callers of this API obtain the client identity using kim_selection_hints_get_identity(). Depending on the kim_options specified, kim_credential_create_new() may present a GUI or command line prompt to obtain information from the user.

+For legacy password-based Kerberos environments KIM also provides kim_credential_create_new_with_password(). You should not use this function unless you know that it will only be used in environments using passwords. Otherwise users without passwords may be prompted for them.

KIM provides the kim_credential_create_from_keytab() to create credentials using a keytab. A keytab is an on-disk copy of a client identity's secret key. Typically sites use keytabs for client identities that identify a machine or service and protect the keytab with disk permissions. Because a keytab is sufficient to obtain credentials, keytabs will normally only be readable by root, Administrator or some other privileged account. Typically applications use credentials obtained from keytabs to obtain credentials for batch processes. These keytabs and credentials are usually for a special identity used for the batch process rather than a user identity.

Validating Credentials

@@ -59,7 +60,7 @@ Examining Credential Properties

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 +See KIM Credential Reference Documentation and KIM Credential Iterator Reference Documentation for information on specific APIs.

Generated on Mon Nov 3 17:45:43 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 a7c4f76b6..a930d4321 100644 --- a/doc/kim/html/kim_identity_overview.html +++ b/doc/kim/html/kim_identity_overview.html @@ -36,7 +36,7 @@ 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.

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 Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by +See KIM Identity Reference Documentation for information on specific APIs.

Generated on Mon Nov 3 17:45:43 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 4b297df02..993239836 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 Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by +See KIM Options Reference Documentation for information on specific APIs.

Generated on Mon Nov 3 17:45:44 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 30c518cda..2759f594c 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 Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by +See KIM Preferences Documentation for information on specific APIs.

Generated on Mon Nov 3 17:45:44 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 5f4a382ea..44a1cd28d 100644 --- a/doc/kim/html/kim_selection_hints_overview.html +++ b/doc/kim/html/kim_selection_hints_overview.html @@ -48,7 +48,7 @@ In order to let the user know why Kerberos needs their assistance, KIM displays 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 Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by +See KIM Selection Hints Reference Documentation for information on specific APIs.

Generated on Mon Nov 3 17:45:44 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 ced9da69d..fbc0962ac 100644 --- a/doc/kim/html/kim_string_overview.html +++ b/doc/kim/html/kim_string_overview.html @@ -11,7 +11,7 @@ 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 +See KIM String Reference Documentation for information on specific APIs.

Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by

1.5.3

diff --git a/doc/kim/html/modules.html b/doc/kim/html/modules.html index ba79467e2..0239b81d5 100644 --- a/doc/kim/html/modules.html +++ b/doc/kim/html/modules.html @@ -18,7 +18,7 @@

KIM String Reference Documentation

KIM Types and Constants

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

Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by

1.5.3

diff --git a/src/include/kim/kim_ccache.h b/src/include/kim/kim_ccache.h index 709c69814..a1cba1710 100644 --- a/src/include/kim/kim_ccache.h +++ b/src/include/kim/kim_ccache.h @@ -114,6 +114,12 @@ extern "C" { * It can be trivially implemented using * #kim_ccache_create_from_client_identity() and #kim_ccache_create_new(). * + * For legacy password-based Kerberos environments KIM also provides + * #kim_ccache_create_new_with_password() and + * #kim_ccache_create_new_if_needed_with_password(). You should not use these + * functions unless you know that they will only be used in environments using + * passwords. Otherwise users without passwords may be prompted for them. + * * KIM provides the #kim_ccache_create_from_keytab() to create credentials * using a keytab and store them in the cache collection. A keytab is an * on-disk copy of a client identity's secret key. Typically sites use @@ -301,7 +307,7 @@ void kim_ccache_iterator_free (kim_ccache_iterator *io_ccache_iterator); * \param in_client_identity a client identity to obtain a credential for. Specify KIM_IDENTITY_ANY to * allow the user to choose. * \param in_options options to control credential acquisition. - * \note Depending on the kim_options specified, #kim_ccache_create_new() may + * \note #kim_ccache_create_new() may * present a GUI or command line prompt to obtain information from the user. * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. * \brief Acquire a new initial credential and store it in a ccache. @@ -310,12 +316,33 @@ kim_error kim_ccache_create_new (kim_ccache *out_ccache, kim_identity in_client_identity, kim_options in_options); +/*! + * \param out_ccache on exit, a new cache object for a ccache containing a newly acquired + * initial credential. Must be freed with kim_ccache_free(). + * \param in_client_identity a client identity to obtain a credential for. Specify KIM_IDENTITY_ANY to + * allow the user to choose. + * \param in_options options to control credential acquisition. + * \param in_password a password to be used while obtaining credentials. + * \note #kim_ccache_create_new_with_password() exists to support + * legacy password-based Kerberos environments. You should not use this + * function unless you know that it will only be used in environments using passwords. + * This function may also present a GUI or command line prompt to obtain + * additional information needed to obtain credentials (eg: SecurID pin). + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Acquire a new initial credential and store it in a ccache + * using the provided password.. + */ +kim_error kim_ccache_create_new_with_password (kim_ccache *out_ccache, + kim_identity in_client_identity, + kim_options in_options, + kim_string in_password); + /*! * \param out_ccache on exit, a ccache object for a ccache containing a newly acquired * initial credential. Must be freed with kim_ccache_free(). * \param in_client_identity a client identity to obtain a credential for. * \param in_options options to control credential acquisition (if a credential is acquired). - * \note Depending on the kim_options specified, #kim_ccache_create_new_if_needed() may + * \note #kim_ccache_create_new_if_needed() may * present a GUI or command line prompt to obtain information from the user. * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. * \brief Find a ccache containing a valid initial credential in the cache collection, or if @@ -325,6 +352,26 @@ kim_error kim_ccache_create_new_if_needed (kim_ccache *out_ccache, kim_identity in_client_identity, kim_options in_options); +/*! + * \param out_ccache on exit, a ccache object for a ccache containing a newly acquired + * initial credential. Must be freed with kim_ccache_free(). + * \param in_client_identity a client identity to obtain a credential for. + * \param in_options options to control credential acquisition (if a credential is acquired). + * \param in_password a password to be used while obtaining credentials. + * \note #kim_ccache_create_new_if_needed_with_password() exists to support + * legacy password-based Kerberos environments. You should not use this + * function unless you know that it will only be used in environments using passwords. + * This function may also present a GUI or command line prompt to obtain + * additional information needed to obtain credentials (eg: SecurID pin). + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Find a ccache containing a valid initial credential in the cache collection, or if + * unavailable, acquire and store a new initial credential using the provided password. + */ +kim_error kim_ccache_create_new_if_needed_with_password (kim_ccache *out_ccache, + kim_identity in_client_identity, + kim_options in_options, + kim_string in_password); + /*! * \param out_ccache on exit, a ccache object for a ccache containing a TGT * credential. Must be freed with kim_ccache_free(). diff --git a/src/include/kim/kim_credential.h b/src/include/kim/kim_credential.h index e1303aeca..c061f1199 100644 --- a/src/include/kim/kim_credential.h +++ b/src/include/kim/kim_credential.h @@ -101,6 +101,11 @@ typedef int kim_credential_state; * kim_options specified, #kim_credential_create_new() may present a * GUI or command line prompt to obtain information from the user. * + * For legacy password-based Kerberos environments KIM also provides + * #kim_credential_create_new_with_password(). You should not use this + * function unless you know that it will only be used in environments using + * passwords. Otherwise users without passwords may be prompted for them. + * * KIM provides the #kim_credential_create_from_keytab() to create credentials * using a keytab. A keytab is an on-disk copy of a client identity's secret * key. Typically sites use keytabs for client identities that identify a @@ -324,7 +329,7 @@ void kim_credential_iterator_free (kim_credential_iterator *io_credential_iterat * \param in_client_identity a client identity to obtain a credential for. Specify NULL to * allow the user to choose the identity * \param in_options options to control credential acquisition. - * \note Depending on the kim_options specified, #kim_credential_create_new() may + * \note #kim_credential_create_new() may * present a GUI or command line prompt to obtain information from the user. * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. * \brief Acquire a new initial credential. @@ -334,6 +339,27 @@ kim_error kim_credential_create_new (kim_credential *out_credential, kim_identity in_client_identity, kim_options in_options); +/*! + * \param out_credential on exit, a new credential object containing a newly acquired + * initial credential. Must be freed with kim_credential_free(). + * \param in_client_identity a client identity to obtain a credential for. Specify NULL to + * allow the user to choose the identity + * \param in_options options to control credential acquisition. + * \param in_password a password to be used while obtaining the credential. + * \note #kim_credential_create_new_with_password() exists to support + * legacy password-based Kerberos environments. You should not use this + * function unless you know that it will only be used in environments using passwords. + * This function may also present a GUI or command line prompt to obtain + * additional information needed to obtain credentials (eg: SecurID pin). + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Acquire a new initial credential using the provided password. + * \sa kim_ccache_create_new + */ +kim_error kim_credential_create_new_with_password (kim_credential *out_credential, + kim_identity in_client_identity, + kim_options in_options, + kim_string in_password); + /*! * \param out_credential on exit, a new credential object containing an initial credential * for \a in_identity obtained using \a in_keytab. diff --git a/src/kim/lib/kim.exports b/src/kim/lib/kim.exports index ca96d04a2..0216e4be3 100644 --- a/src/kim/lib/kim.exports +++ b/src/kim/lib/kim.exports @@ -93,6 +93,7 @@ kim_credential_iterator_next kim_credential_iterator_free kim_credential_create_new +kim_credential_create_new_with_password kim_credential_create_from_keytab kim_credential_create_from_krb5_creds kim_credential_copy @@ -116,7 +117,9 @@ kim_ccache_iterator_next kim_ccache_iterator_free kim_ccache_create_new +kim_ccache_create_new_with_password kim_ccache_create_new_if_needed +kim_ccache_create_new_if_needed_with_password kim_ccache_create_from_client_identity kim_ccache_create_from_keytab kim_ccache_create_from_default diff --git a/src/kim/lib/kim_ccache_private.h b/src/kim/lib/kim_ccache_private.h deleted file mode 100644 index 6e1d7a12e..000000000 --- a/src/kim/lib/kim_ccache_private.h +++ /dev/null @@ -1,42 +0,0 @@ -/* - * $Header$ - * - * Copyright 2006 Massachusetts Institute of Technology. - * All Rights Reserved. - * - * Export of this software from the United States of America may - * require a specific license from the United States Government. - * It is the responsibility of any person or organization contemplating - * export to obtain such a license before exporting. - * - * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - * distribute this software and its documentation for any purpose and - * without fee is hereby granted, provided that the above copyright - * notice appear in all copies and that both that copyright notice and - * this permission notice appear in supporting documentation, and that - * the name of M.I.T. not be used in advertising or publicity pertaining - * to distribution of the software without specific, written prior - * permission. Furthermore if you modify this software you must label - * your software as modified software and not distribute it in such a - * fashion that it might be confused with the original M.I.T. software. - * M.I.T. makes no representations about the suitability of - * this software for any purpose. It is provided "as is" without express - * or implied warranty. - */ - -#ifndef KIM_CCACHE_PRIVATE_H -#define KIM_CCACHE_PRIVATE_H - -#include - -kim_error kim_ccache_create_new_if_needed_with_password (kim_ccache *out_ccache, - kim_identity in_client_identity, - kim_options in_options, - kim_string in_password); - -kim_error kim_ccache_create_new_with_password (kim_ccache *out_ccache, - kim_identity in_client_identity, - kim_options in_options, - kim_string in_password); - -#endif /* KIM_CCACHE_PRIVATE_H */ diff --git a/src/kim/lib/kim_credential_private.h b/src/kim/lib/kim_credential_private.h index c9a975d59..3f30d6c73 100644 --- a/src/kim/lib/kim_credential_private.h +++ b/src/kim/lib/kim_credential_private.h @@ -36,9 +36,4 @@ kim_error kim_credential_create_for_change_password (kim_credential *out_creden kim_ui_context *in_ui_context, kim_boolean *out_user_was_prompted); -kim_error kim_credential_create_new_with_password (kim_credential *out_credential, - kim_identity in_identity, - kim_options in_options, - kim_string in_password); - #endif /* KIM_CREDENTIAL_PRIVATE_H */ diff --git a/src/kim/lib/kim_private.h b/src/kim/lib/kim_private.h index 7a86d7e0a..939279f77 100644 --- a/src/kim/lib/kim_private.h +++ b/src/kim/lib/kim_private.h @@ -39,7 +39,6 @@ #include "kim_debug_private.h" #include "kim_error_private.h" #include "kim_identity_private.h" -#include "kim_ccache_private.h" #include "kim_credential_private.h" #include "kim_options_private.h" #include "kim_preferences_private.h" -- 2.26.2