svn rev #24851: trunk/ doc/doxy_examples/ src/include/krb5/

tsitkova@MIT.EDU tsitkova at MIT.EDU
Wed Apr 6 15:44:07 EDT 2011


http://src.mit.edu/fisheye/changelog/krb5/?cs=24851
Commit By: tsitkova
Log Message:
Documentation updates



Changed Files:
U   trunk/doc/doxy_examples/cc_set_config.c
A   trunk/doc/doxy_examples/cc_unique.c
U   trunk/src/include/krb5/krb5.hin
Modified: trunk/doc/doxy_examples/cc_set_config.c
===================================================================
--- trunk/doc/doxy_examples/cc_set_config.c	2011-04-06 14:37:01 UTC (rev 24850)
+++ trunk/doc/doxy_examples/cc_set_config.c	2011-04-06 19:44:07 UTC (rev 24851)
@@ -1,12 +1,12 @@
 /** @example  cc_set_config.c
  *
- *  Demo for krb5_cc_set_config function
+ *  Usage examples for krb5_cc_set_config and krb5_cc_get_config functions
  */
 #include <k5-int.h>
 
 krb5_error_code
-func(krb5_context context, krb5_ccache id,
-     krb5_const_principal principal, const char *key)
+func_set(krb5_context context, krb5_ccache id,
+         krb5_const_principal principal, const char *key)
 {
    krb5_data config_data;
 
@@ -14,3 +14,20 @@
    config_data.length = strlen(config_data.data);
    return  krb5_cc_set_config(context, id, principal, key, &config_data);
 }
+
+krb5_error_code
+func_get(krb5_context context, krb5_ccache id,
+         krb5_const_principal principal, const char *key)
+{
+   krb5_data config_data;
+   krb5_error_code ret;
+
+   config_data.data = NULL;
+   ret = krb5_cc_get_config(context, id, principal, key, &config_data);
+   if (ret){
+        return ret;
+   }
+   /* do something */
+   krb5_free_data_contents(context, &config_data);
+   return ret;
+}

Added: trunk/doc/doxy_examples/cc_unique.c
===================================================================
--- trunk/doc/doxy_examples/cc_unique.c	                        (rev 0)
+++ trunk/doc/doxy_examples/cc_unique.c	2011-04-06 19:44:07 UTC (rev 24851)
@@ -0,0 +1,23 @@
+/** @example  cc_unique.c
+ *
+ *  Usage example for krb5_cc_new_unique function
+ */
+#include "k5-int.h"
+
+krb5_error_code
+func(krb5_context context)
+{
+    krb5_error_code ret;
+    krb5_ccache ccache = NULL;
+
+    ret = krb5_cc_new_unique(context, "MEMORY", NULL, &ccache);
+    if (ret){
+        ccache = NULL; 
+        return ret;
+    }
+    /* do something */
+    if (ccache)
+        (void)krb5_cc_destroy(context, ccache);
+    return 0;
+}
+

Modified: trunk/src/include/krb5/krb5.hin
===================================================================
--- trunk/src/include/krb5/krb5.hin	2011-04-06 14:37:01 UTC (rev 24850)
+++ trunk/src/include/krb5/krb5.hin	2011-04-06 19:44:07 UTC (rev 24851)
@@ -1950,16 +1950,17 @@
 #define KRB5_TC_OPENCLOSE               0x00000001
 #define KRB5_TC_NOTICKET                0x00000002
 
-/**
- * @brief Retrieve the name but not type of a credential cache.
+/** Retrieve the name but not type of a credential cache.
  *
- * @param context           Context structure [input, output]
- * @param cache            Credentials cache handle [input]
+ * @param [in] context          Context structure
+ * @param [in] cache            Credentials cache handle
  *
- * Returns the name of the credential cache as an alias that should not be
- * freed or modified by the caller.  This name does not include the type
- * portion, so cannot be used as input to krb5_cc_resolve().
- * Make sure to free the allocated memory when it is no longer needed.
+ * @warning Returns the name of the credential cache as an alias that
+ * should not be freed or modified by the caller.  This name does not
+ * include the type portion, so cannot be used as input to krb5_cc_resolve().
+ *
+ * @return
+ * On success - the name of the credential cache.
  */
 const char * KRB5_CALLCONV
 krb5_cc_get_name(krb5_context context, krb5_ccache cache);
@@ -1978,15 +1979,14 @@
 krb5_error_code KRB5_CALLCONV
 krb5_cc_gen_new(krb5_context context, krb5_ccache *cache);
 
-/**
- * @brief Destroy an existing credentials cache and create a new credentials cache by the same name.
+/** Initialize credentials cache.
  *
- * @param context                      Context structure [input, output]
- * @param cache                       Credentials cache handle [input, output]
- * @param principal                    Primary principal name for the credentials cache [output]
+ * @param [in] context       Context structure
+ * @param [in] cache         Credentials cache handle
+ * @param [in] principal     Default principal name for the credentials cache
  *
- * Destroy an existing credentials cache and create a new credentials cache by the same name,
- * as specifed by @a cache for specified principal.
+ * Destroy an existing credentials cache and create a new credentials cache
+ * by the same name, as specifed by @a cache for specified @a principal.
  *
  * @note This function also modifies the specified credentials cache.
  *
@@ -2003,37 +2003,35 @@
 krb5_cc_initialize(krb5_context context, krb5_ccache cache,
                    krb5_principal principal);
 
-/**
- * @brief Destroy a credentials cache.
+/** Destroy a credentials cache.
  *
- * @param context           Context structure [input, output]
- * @param cache            Credentials cache handle [input]
+ * @param [in] context          Context structure
+ * @param [in] cache            Credentials cache handle
  *
- * This function invalidates @a cache and releases any other resources
- * acquired during use of the credentials cache. @a cache must identify a valid credentials cache.
+ * This function closes and deletes @a cache and releases any other resources
+ * acquired during use of the credentials cache.
+ * @a cache must identify a valid credentials cache.
  *
- * @note After completion, do not use @a cache until it is reinitialized with krb5_cc_resolve() or krb5_cc_gen_new().
+ * @note After completion, @a cache may not be used. It may be reinitialized
+ * with krb5_cc_resolve() or krb5_cc_gen_new().
  *
  * @retval
- *  0  Success
+ * 0  Success
  * @return
- *  Permission errors
- *
- * @sa krb5_cc_gen_new()
+ * Permission errors
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cc_destroy(krb5_context context, krb5_ccache cache);
 
-/**
- * @brief  Close a credentials cache and invalidate its handle.
+/** Close a credentials cache and invalidate its handle.
  *
- * @param context                Context structure [input, output]
- * @param cache                  Credentials cache handle [input, output]
+ * @param [in] context                Context structure
+ * @param [in] cache                  Credentials cache handle
  *
- * @note Reinitialize @a cache with krb5_cc_resolve() or  krb5_cc_gen_new().
+ * @note Reinitialize @a cache with krb5_cc_resolve() or krb5_cc_gen_new().
  *
  * @retval
- *  0    Success
+ * 0  Success
  * @return
  * Kerberos error codes
  */
@@ -2096,19 +2094,18 @@
                       krb5_flags flags, krb5_creds *mcreds,
                       krb5_creds *creds);
 
-/**
- * @brief Get the primary principal of a credentials cache.
+/** Get the primary principal of a credentials cache.
  *
- * @param context            Context structure [input, output]
- * @param cache              Credentials cache handle  [input]
- * @param principal          Primary principal [output]
+ * @param [in]  context            Context structure
+ * @param [in]  cache              Credentials cache handle
+ * @param [out] principal          Primary principal
  *
- * @note The primary principal is set by calling  krb5_cc_initialize().
+ * @note The primary principal is set by calling krb5_cc_initialize().
  *
- * Make sure to free the allocated memory when it is no longer needed.
+ * Use krb5_free_principal() to free @a principal when it is no longer needed.
  *
  * @retval
- *  0  Success
+ * 0  Success
  * @return
  * Kerberos error codes
  */
@@ -2254,14 +2251,11 @@
 krb5_error_code KRB5_CALLCONV
 krb5_cc_get_flags(krb5_context context, krb5_ccache cache, krb5_flags *flags);
 
-/**
- * @brief Retrieve the type of a credential cache.
+/** Retrieve the type of a credential cache.
  *
- * @param context           Context structure [input, output]
- * @param cache             Credentials cache handle [input]
+ * @param [in] context           Context structure
+ * @param [in] cache             Credentials cache handle
  *
- * Make sure to free the allocated memory when it is no longer needed.
- *
  * @return The type of a credential cache as an alias that should not be
  * modified or freed by the caller.
  */
@@ -2354,13 +2348,12 @@
 krb5_error_code KRB5_CALLCONV
 krb5_cccol_unlock(krb5_context context);
 
-/**
- * @brief Create a new unique credentials cache of the specified type.
+/** Create a new unique credentials cache of the specified type.
  *
- * @param context           Context structure [input, output]
- * @param type              Credentials cache type [input, output]
- * @param hint              Unused
- * @param id                Credentials cache handle [output]
+ * @param [in]  context           Context structure
+ * @param [in]  type              Credentials cache type name
+ * @param [in]  hint              Unused
+ * @param [out] id                Credentials cache handle
  *
  * @retval
  * 0 Success
@@ -2408,7 +2401,7 @@
 struct _krb5_kt;
 typedef struct _krb5_kt *krb5_keytab;
 
-/** Return the type of a key table.
+/** Return a type of a key table.
  *
  * @param [in] context           Context structure
  * @param [in] keytab            Type of key table handle
@@ -2423,14 +2416,15 @@
 const char * KRB5_CALLCONV
 krb5_kt_get_type(krb5_context context, krb5_keytab keytab);
 
-/** Get key table name
+/** Get a key table name
  *
  * @param [in]  context           Context structure
  * @param [in]  keytab            Key table handle
  * @param [out] name              Key table name
  * @param [in]  namelen           Maximum length to fill in name
  *
- * Zeroes @a name and then copies the key table name including its prefix and trailing delimeter.
+ * Zeroes @a name and then copies the key table name including
+ * its prefix and trailing delimeter.
  *
  * @sa MAX_KEYTAB_NAME_LEN
  *
@@ -2455,8 +2449,7 @@
  * acquired during use of the key table.
  * Undo anything done by krb5_kt_resolve().
  *
- * @retval
- * 0
+ * @retval 0
  */
 krb5_error_code KRB5_CALLCONV
 krb5_kt_close(krb5_context context, krb5_keytab keytab);
@@ -2470,18 +2463,17 @@
  * @param [in]  enctype       Encryption type. Use zero for any enctype.
  * @param [out] entry         Returned entry from key tablele
  *
- * Retrieve an entry from a key table that matches the @a keytab, @a principal, and @a vno.
+ * Retrieve an entry from a key table that matches the @a keytab, @a principal,
+ * and @a vno.
  * The @a entry must be freed with krb5_kt_free_entry() when it is no longer needed.
  *
- * @note If @a vno is zero, the function retrieves the highest-numbered-kvno  entry that
- * matches the specified principal.
+ * @note If @a vno is zero, the function retrieves the highest-numbered-kvno
+ * entry that matches the specified principal.
  *
  * @retval
  * 0 Success
  * @retval
  * Kerberos error codes on failure
- * @return
- * On success retrieves the entry
  */
 krb5_error_code KRB5_CALLCONV
 krb5_kt_get_entry(krb5_context context, krb5_keytab keytab,
@@ -2519,7 +2511,6 @@
  *
  * Return the next sequential entry in the specified key table and update @a cursor for
  * the next request.
- *
  * If the key table changes during the sequential get, an error is guaranteed.
  *
  * @sa krb5_kt_start_seq_get(), krb5_kt_end_seq_get()
@@ -2564,7 +2555,7 @@
  *
  * @param [out] context           Context structure
  *
- * The context must be released by calling krb5_free_context() routine when
+ * The context must be released by calling krb5_free_context() when
  * it is no longer needed.
  *
  * @warning Any program or module that needs the Kerberos code to not trust
@@ -2587,7 +2578,7 @@
  * are safe for a @c setuid program.
  * All information passed through the environment variables is ignored.
  *
- * The context must be released by calling krb5_free_context() routine when
+ * The context must be released by calling krb5_free_context() when
  * it is no longer needed.
  *
  * @retval
@@ -2617,7 +2608,7 @@
  * @param [out] nctx_out      New "cloned" context structure
  *
  * The newly created context must be released by calling krb5_free_context()
- * routine when it is no longer needed.
+ * when it is no longer needed.
  *
  * @retval
  * 0 Success
@@ -2638,10 +2629,7 @@
  * @retval
  *  0    Success
  * @retval
- *  ENOMEM Insufficient memory
- * @retval
  *  KRB5_PROG_ETYPE_NOSUPP Program lacks support for encryption type
-
  * @return
  * Kerberos error codes
  *
@@ -2661,26 +2649,19 @@
  * @retval
  *  0   Success
  * @retval
- *  ENOMEM Insufficient memory
- * @retval
  *  KRB5_PROG_ETYPE_NOSUPP Program lacks support for encryption type
  * @return
  * Kerberos error codes
  *
  * @sa enctype
- *
  */
 krb5_error_code KRB5_CALLCONV
 krb5_get_permitted_enctypes(krb5_context context, krb5_enctype **ktypes);
 
-/**
- * @brief Return a value indicating whether the client libraries support multithreading.
+/** Test whether the Kerberos library was built with multithread support.
  *
  * @retval
- *  TRUE  Client libraries are threadsafe
- * @retval
- *  FALSE Client libraries are not threadsafe
- *
+ * TRUE if the library is threadsafe; FALSE otherwise
  */
 krb5_boolean KRB5_CALLCONV
 krb5_is_thread_safe(void);
@@ -3256,9 +3237,7 @@
  * @param addrlist          Address list to be searched. Specify NULL if there is no address list [input]
  *
  * @retval
- *  TRUE    @a addr is listed in @a addrlist, or @c addrlist is NULL
- * @retval
- *  FALSE    @a addr is not listed in @a addrlist
+ * TRUE if @a addr is listed in @a addrlist, or @c addrlist is NULL; FALSE otherwise
  */
 krb5_boolean KRB5_CALLCONV_WRONG
 krb5_address_search(krb5_context context, const krb5_address *addr,
@@ -3272,9 +3251,7 @@
  * @param addr2             Second address to be compared [input]
  *
  * @retval
- *  TRUE   The addresses are the same
- * @retval
- *  FALSE  The addresses are different
+ *  TRUE if the addresses are the same, FALSE otherwise
  */
 krb5_boolean KRB5_CALLCONV
 krb5_address_compare(krb5_context context, const krb5_address *addr1,
@@ -3298,48 +3275,73 @@
 krb5_address_order(krb5_context context, const krb5_address *addr1,
                    const krb5_address *addr2);
 
-/**
- * @brief Compare the realms of two principals.
+/** Compare the realms of two principals.
  *
- * @param context           Context structure [input, output]
- * @param princ1            First principal [input]
- * @param princ2            Second principal [input]
+ * @param [in] context           Context structure
+ * @param [in] princ1            First principal
+ * @param [in] princ2            Second principal
  *
  * @retval
- *  TRUE     The realms are the same
- * @retval
- *  FALSE    The realms are the different
+ * TRUE if the realm names are the same; FALSE otherwise
  */
 krb5_boolean KRB5_CALLCONV
 krb5_realm_compare(krb5_context context, krb5_const_principal princ1,
                    krb5_const_principal princ2);
 
-/** Compare two principal names.
+/** Compare two principals.
  *
  * @param [in] context           Context structure
- * @param [in] princ1            First principal name
- * @param [in] princ2            Second principal name
+ * @param [in] princ1            First principal
+ * @param [in] princ2            Second principal
  *
  * @retval
- *  TRUE  The principal names are the same
- * @retval
- *  FALSE The principal names are not the same
+ * TRUE if the principals are the same; FALSE otherwise
  */
 krb5_boolean KRB5_CALLCONV
 krb5_principal_compare(krb5_context context,
                        krb5_const_principal princ1,
                        krb5_const_principal princ2);
 
+/** Compare two principals ignoring realm components.
+ *
+ * @param [in] context           Context structure
+ * @param [in] princ1            First principal
+ * @param [in] princ2            Second principal
+ *
+ * Similar to krb5_principal_compare() but do not compare the realm
+ * components of the principals
+ *
+ * @retval
+ * TRUE if the principals are the same; FALSE otherwise
+ */
 krb5_boolean KRB5_CALLCONV
 krb5_principal_compare_any_realm(krb5_context context,
                                  krb5_const_principal princ1,
                                  krb5_const_principal princ2);
 
-#define KRB5_PRINCIPAL_COMPARE_IGNORE_REALM  1
+#define KRB5_PRINCIPAL_COMPARE_IGNORE_REALM  1 /**< ignore realm component */
 #define KRB5_PRINCIPAL_COMPARE_ENTERPRISE    2 /**< UPNs as real principals */
 #define KRB5_PRINCIPAL_COMPARE_CASEFOLD      4 /**< case-insensitive */
 #define KRB5_PRINCIPAL_COMPARE_UTF8          8 /**< treat principals as UTF-8 */
 
+/** Compare two principals with additional flags.
+ *
+ * @param [in] context           Context structure
+ * @param [in] princ1            First principal
+ * @param [in] princ2            Second principal
+ * @param [in] flags             Flags
+ *
+ * Valid flags are:
+ * @li @c KRB5_PRINCIPAL_COMPARE_IGNORE_REALM - ignore realm component
+ * @li @c KRB5_PRINCIPAL_COMPARE_ENTERPRISE - UPNs as real principals
+ * @li @c KRB5_PRINCIPAL_COMPARE_CASEFOLD case-insensitive
+ * @li @c KRB5_PRINCIPAL_COMPARE_UTF8 - treat principals as UTF-8
+ *
+ * @sa krb5_principal_compare()
+ *
+ * @retval
+ * TRUE if the principal names are the same; FALSE otherwise
+ */
 krb5_boolean KRB5_CALLCONV
 krb5_principal_compare_flags(krb5_context context,
                              krb5_const_principal princ1,
@@ -3616,7 +3618,7 @@
  * @param [in]  realm             Realm name
  * @param [in]  ...               List of len1, sl1, len2, sl2...
  *
- * Call krb5_free_principal() to free allocated memory for principal when it is no longer needed.
+ * Call krb5_free_principal() to free @a princ when it is no longer needed.
  *
  * @note krb5_build_principal() and krb5_build_principal_va() perform the same task.
  * krb5_build_principal() takes variadic arguments.
@@ -3655,7 +3657,7 @@
  * krb5_build_principal() takes variadic arguments.
  * krb5_build_principal_va() takes a pre-computed @a varargs pointer.
  *
- * Call krb5_free_principal() to free allocated memory for principal when it is no longer needed.
+ * Use krb5_free_principal() to free @a princ when it is no longer needed.
  *
  * @retval
  * 0  Success
@@ -3681,8 +3683,7 @@
  * Similar to krb5_build_principal() this function builds a principal name,
  * but its name components are specified as va_list.
  *
- * Make sure to call krb5_free_principal() to deallocate the principal
- * when it is no longer needed.
+ * Use krb5_free_principal() to deallocate the @a princ when it is no longer needed.
  *
  * @code
  * Function usage example:
@@ -4033,21 +4034,13 @@
 
 /** Get some configuration for the credential cache in the cache.
  *
- * @param context        a Keberos context [input]
- * @param id             the credential cache to store the data for [input]
- * @param principal      configuration for a specific principal, if NULL, global for the whole cache.[input]
- * @param key            name under which the configuraion is stored [input]
- * @param data           data to be fetched; free with krb5_free_data_contents() [input,output]
+ * @param [in]     context     Context structure
+ * @param [in]     id          The credential cache to store the data for
+ * @param [in]     principal   Configuration for this principal;
+ *                             if NULL, global for the whole cache.
+ * @param [in]     key         Name under which the configuraion is stored
+ * @param [in,out] data        Data to be fetched; free with krb5_free_data_contents()
  *
- * @code
- * Example:
- *   krb5_data config_data;
- *   config_data.data = NULL;
- *   krb5_cc_get_config(context, ccache, target_principal, key, &config_data);
- *   ...
- *   krb5_free_data_contents(context, &config_data);
- * @endcode
- *
  * @retval
  * 0  Success
  * @return
@@ -4062,7 +4055,8 @@
  *
  * @param [in,out] context         a Keberos context
  * @param [in]     id              the credential cache to store the data for.
- * @param [in]     principal       configuration for a specific principal; if NULL, global for the whole cache.
+ * @param [in]     principal       configuration for a specific principal;
+ *                                 if NULL, global for the whole cache.
  * @param [in]     key             name under which the configuraion is stored.
  * @param [in]     data            data to store. If NULL, old configuration is removed.
  *
@@ -4080,12 +4074,12 @@
 
 /** Test whether a principal is a configuration principal.
  *
- * @param context        a Keberos context [input]
- * @param principal      principal to check if it a configuration principal [input]
+ * @param [in] context        a Keberos context
+ * @param [in] principal      principal to check if it a configuration principal
  *
- * @return Return TRUE (non zero) if the principal is a configuration
- *        principal (generated part of krb5_cc_set_config()). Returns
- *        FALSE (zero) if not a configuration principal.
+ * @return
+ *  TRUE (non zero) if the principal is a configuration principal
+ * (generated part of krb5_cc_set_config()); FALSE (zero) otherwise.
  */
 krb5_boolean KRB5_CALLCONV
 krb5_is_config_principal(krb5_context context, krb5_const_principal principal);
@@ -4102,8 +4096,8 @@
 
 /** Free an authenticator structure, including its pointer.
  *
- * @param context           Context structure [input, output]
- * @param val               Pointer to data structure to be freed [input, output]
+ * @param [in] context           Context structure
+ * @param [in] val               Pointer to data structure to be freed
  *
  * @return
  * None
@@ -4113,8 +4107,8 @@
 
 /** Free an array of addresses and its pointer.
  *
- * @param context           Context structure [input, output]
- * @param val               Pointer to data structure to be freed [input,output]
+ * @param [in] context           Context structure
+ * @param [in] val               Pointer to data structure to be freed
  *
  * @return
  * None
@@ -4124,8 +4118,8 @@
 
 /** Free an @c _krb5_auth_data structure.
  *
- * @param context           Context structure [input, output]
- * @param val               Pointer to data structure to be freed [input, output]
+ * @param [in] context           Context structure
+ * @param [in] val               Pointer to data structure to be freed
  *
  * @return
  * None
@@ -4135,8 +4129,8 @@
 
 /** Free a ticket.
  *
- * @param context           Context structure [input, output]
- * @param val               Pointer to the data structure to be freed [input, output]
+ * @param [in] context           Context structure
+ * @param [in] val               Pointer to the data structure to be freed
  *
  * @return
  * None
@@ -4251,8 +4245,8 @@
 
 /** Free the contents of a @c _krb5_data structure and zero the data field.
  *
- * @param context           Context structure [input, output]
- * @param val               Pointer to data structure to be freed [input, output]
+ * @param [in] context           Context structure
+ * @param [in] val               Pointer to data structure to be freed
  *
  * @note The pointer is not freed.
  *
@@ -4386,25 +4380,19 @@
 void KRB5_CALLCONV
 krb5_free_default_realm(krb5_context context, char *lrealm);
 
-/**
- * @brief Generate a full principal name from a service name.
+/** Generate a full principal name from a service name.
  *
- * @param context           Context structure [input, output]
- * @param hostname          Host name, or NULL to use local host [input]
- * @param sname             Service name [input]
- * @param type              Principal type: either @c KRB5_NT_SRV_HST or @c KRB5_NT_UNKNOWN [input]
- * @param ret_princ         Full principal name [output]
+ * @param [in]  context   Context structure
+ * @param [in]  hostname  Host name, or NULL to use local host
+ * @param [in]  sname     Service name, or NULL to use string @c host
+ * @param [in]  type      Principal type: @c KRB5_NT_SRV_HST or @c KRB5_NT_UNKNOWN
+ * @param [out] ret_princ Generated principal
  *
- * The full (multi-part) principal name tis used to authenticate the principal with the specified service on the
- * host, given a hostname @a hostname and a generic service name @a sname.
+ * This function converts a given @a hostname and @a sname into @a krb5_principal
+ * structure @a ret_princ.
  *
- * @a ret_princ holds the generated full principal name. The realm of the principal
- *  is determined internally by calling krb5_get_host_realm().
+ * The @a type can be one of the following:
  *
- * Make sure to free the allocated memory when it is no longer needed.
- *
- * The principal type, @a type, controls how krb5_sname_to_principal() generates a principal name for a service.
- *
  * @li @c KRB5_NT_SRV_HOST canonicalizes the host name (a fully
  * qualified lowercase @a hostname using the primary name and the
  * domain name), \b before @a ret_princ is generated in the form
@@ -4414,6 +4402,8 @@
  * the form @a sname\/hostname\@LOCAL.REALM, but the @a hostname \b will \b not be
  * canonicalized first. It will appear exactly as it was passed in @a hostname.
  *
+ * Use krb5_free_principal to free @a ret_princ when it is no longer needed.
+ *
  * @retval
  * 0  Success
  * @return
@@ -4423,17 +4413,24 @@
 krb5_sname_to_principal(krb5_context context, const char *hostname, const char *sname,
                         krb5_int32 type, krb5_principal *ret_princ);
 
-/** Return true if @a princ matches @a matching, false otherwise.
+/** Test whether a principal matches a matching principal.
  *
- * A matching principal is a host-based principal with an empty realm and/or
+ * @param [in]  context        Context structure
+ * @param [in]  matching       Matching principal
+ * @param [in]  princ          Principal to test
+ *
+ * @note A matching principal is a host-based principal with an empty realm and/or
  * second data component (hostname).  Profile configuration may cause the
- * hostname to be ignored even if it is present.  A principal matches a
- * matching principal if the principal has the same non-empty (and non-ignored)
- * components of the matching principal.
+ * hostname to be ignored even if it is present. A principal matches a
+ * matching principal if the former has the same non-empty (and non-ignored)
+ * components of the latter.
  *
- * If @a matching is NULL, return true.  If @a matching is not a matching
+ * If @a matching is NULL, return TRUE.  If @a matching is not a matching
  * principal, return the value of krb5_principal_compare(context, matching,
  * princ).
+ *
+ * @return
+ * TRUE if @a princ matches @a matching, FALSE otherwise.
  */
 krb5_boolean KRB5_CALLCONV
 krb5_sname_match(krb5_context context, krb5_const_principal matching,
@@ -4470,45 +4467,63 @@
                      int *result_code, krb5_data *result_code_string,
                      krb5_data *result_string);
 
-/**
- * @brief Implement set password according to RFC 3244, so that it is interoperable with MS Windows implementations.
+/** Set a password for a principal using specified credentials.
  *
- * @param context                Context structure [input, output]
- * @param creds                  Credentials [input
- * @param newpw                 New password [input]
- * @param change_password_for   Specific principal for password change  [input]
- * @param result_code           Pointer to result code returned by the remote system [output]
- * @param result_code_string    Pointer to result code translated into a readable message [output]
- * @param result_string         Pointer to result data returned from the remote system [output]
+ * @param [in,out] context            Context structure
+ * @param [in]  creds                 Credentials
+ * @param [in]  newpw                 New password
+ * @param [in]  change_password_for   Change the password for this principal
+ * @param [out] result_code           Numeric error code returned by the remote system
+ * @param [out] result_code_string    Error code translated into a readable message
+ * @param [out] result_string         Data returned from the remote system
  *
- * @note If @a change_password_for is NULL, the change is performed on the current
- * principal. If @a change_password_for is non-null, the change is performed on the
- * principal name passed in @a change_password_for.
+ * This function uses the credentials @a creds to set the password
+ * @a newpw for the principal @a change_password_for.
+ * It implements the set password operation of RFC 3244, for
+ * interoperability with Microsoft Windows implementations.
  *
+ * @note If @a change_password_for is NULL, the change is performed on the
+ * current principal. If @a change_password_for is non-null, the change is
+ * performed on the principal name passed in @a change_password_for.
+ *
+ * The error code and strings are returned in @a result_code,
+ * @a result_code_string and @a result_string.
+ *
+ * @sa krb5_set_password_using_ccache()
+ *
  * @retval
- * 0  Success
+ * 0  Success and result_code is set to KRB5_KPASSWD_SUCCESS.
  * @return
- * Kerberos error codes
+ * Kerberos error codes.
  */
 krb5_error_code KRB5_CALLCONV
 krb5_set_password(krb5_context context, krb5_creds *creds, char *newpw,
                   krb5_principal change_password_for, int *result_code,
                   krb5_data *result_code_string, krb5_data *result_string);
 
-/**
- * @brief Implement RFC 3244 set password (interoperable with MS Windows implementations) using the credentials cache instead of explicitly passed credentials.
+/** Set a password for a principal using cached credentials.
  *
- * @param context           Context structure [input, output]
- * @param ccache            Credentials cache [input]
- * @param newpw             New password [input]
- * @param change_password_for   Principal for which password is changed [input]
- * @param result_code           Pointer to result code returned from remote system [output]
- * @param result_code_string    Pointer to result code returned from remote system translated into a readable message [output]
- * @param result_string         Pointer to the result data returned from remote system [output]
+ * @param [in,out] context            Context structure
+ * @param [in]  ccache                Credentials cache
+ * @param [in]  newpw                 New password
+ * @param [in]  change_password_for   Change the password for this principal
+ * @param [out] result_code           Numeric error code returned by the remote system
+ * @param [out] result_code_string    Error code translated into a readable message
+ * @param [out] result_string         Data returned from the remote system
  *
+ * This function uses the cached credentials from @a ccache to set the password
+ * @a newpw for the principal @a change_password_for.
+ * It implements RFC 3244 set password operation (interoperable with MS Windows
+ * implementations) using the credentials cache.
+ *
+ * The error code and strings are returned in @a result_code,
+ * @a result_code_string and @a result_string.
+ *
+ * @sa krb5_set_password()
+ *
  * @note If @a change_password_for is set to NULL, the change is performed
- * on the current principal. If @a change_password_for is non null, the change is performed
- * on the specified principal.
+ * on the default principal in @a ccache. If @a change_password_for is non null,
+ * the change is performed on the specified principal.
  *
  * @retval
  * 0  Success
@@ -4538,7 +4553,7 @@
  * Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
-krb5_get_profile(krb5_context context, struct _profile_t ** profile_t);
+krb5_get_profile(krb5_context context, struct _profile_t ** profile);
 
 #if KRB5_DEPRECATED
 /**   @deprecated Replaced by krb5_get_init_creds_password() */
@@ -5588,9 +5603,7 @@
  * .k5login, the @a luser is not authorized to log into an account.
  *
  * @retval
- *  TRUE User is authorized to log in
- * @retval
- *  FALSE User is not authorized to log in
+ * TRUE User is authorized to log in; FALSE otherwise
  */
 krb5_boolean KRB5_CALLCONV
 krb5_kuserok(krb5_context context, krb5_principal principal, const char *luser);
@@ -6722,7 +6735,7 @@
 const char * KRB5_CALLCONV
 krb5_get_error_message(krb5_context ctx, krb5_error_code code);
 
-/** Free an error message state generated by krb5_get_error_message().
+/** Free an error message state generated by krb5_get_error_message.
  *
  * @param [in] ctx           Context structure
  * @param [in] msg           Pointer to error message
@@ -6845,7 +6858,12 @@
                                      const struct krb5_trace_info *info,
                                      void *cb_data);
 
-/**
+/** Specify a callback function for trace events.
+ *
+ * @param [in,out] context      Context structure
+ * @param [in]     fn           Callback function name
+ * @param [in]     cb_data      Callback data
+ *
  * Specify a callback for trace events occurring in krb5 operations performed
  * within @a context.  @a fn will be invoked with @a context as the first
  * argument, @a cb_data as the last argument, and a pointer to a struct
@@ -6854,17 +6872,22 @@
  * second argument to allow cleanup of @a cb_data.  Supply a NULL value for @a
  * fn to disable trace callbacks within @a context.
  *
- * @return Returns KRB5_TRACE_NOSUPP if tracing is not supported in the library (unless
- * @a fn is NULL).
+ * @return Returns KRB5_TRACE_NOSUPP if tracing is not supported in the library
+ * (unless @a fn is NULL).
  */
 krb5_error_code KRB5_CALLCONV
 krb5_set_trace_callback(krb5_context context, krb5_trace_callback fn,
                         void *cb_data);
 
-/**
+/** Specify a file name for directing trace events.
+ *
+ * @param [in,out] context      Context structure
+ * @param [in]     filename     File name
+ *
  * Open @a filename for appending (creating it, if necessary) and set up a
- * callback to write trace events to it.  Returns KRB5_TRACE_NOSUPP if tracing
- * is not supported in the library.
+ * callback to write trace events to it.
+ *
+ * @return  KRB5_TRACE_NOSUPP if tracing is not supported in the library.
  */
 krb5_error_code KRB5_CALLCONV
 krb5_set_trace_filename(krb5_context context, const char *filename);




More information about the cvs-krb5 mailing list