diff options
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/kim/kim.h | 7 | ||||
-rw-r--r-- | src/include/kim/kim_ccache.h | 8 | ||||
-rw-r--r-- | src/include/kim/kim_credential.h | 10 | ||||
-rw-r--r-- | src/include/kim/kim_identity.h | 4 | ||||
-rw-r--r-- | src/include/kim/kim_library.h | 37 | ||||
-rw-r--r-- | src/include/kim/kim_preferences.h | 2 | ||||
-rw-r--r-- | src/include/kim/kim_selection_hints.h | 27 | ||||
-rw-r--r-- | src/include/kim/kim_string.h | 2 | ||||
-rw-r--r-- | src/include/kim/kim_types.h | 30 |
9 files changed, 84 insertions, 43 deletions
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 * - * <B>KIM Realms List (kim_favorite_identities_t)</B> views and edits the current user's favorite realms list: - * - \subpage kim_favorite_identities_overview - * - \subpage kim_favorite_identities_reference - * * <B>KIM Preferences (kim_preferences_t)</B> 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 * - * <B>KIM Error (kim_error_t)</B> 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 <kim/kim.h> +/*! + * \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; |