svn rev #24875: trunk/src/ include/krb5/ lib/krb5/krb/
tsitkova@MIT.EDU
tsitkova at MIT.EDU
Tue Apr 12 09:36:16 EDT 2011
http://src.mit.edu/fisheye/changelog/krb5/?cs=24875
Commit By: tsitkova
Log Message:
Documentation updates. Mostly GIC related.
Changed Files:
U trunk/src/include/krb5/krb5.hin
U trunk/src/lib/krb5/krb/fwd_tgt.c
Modified: trunk/src/include/krb5/krb5.hin
===================================================================
--- trunk/src/include/krb5/krb5.hin 2011-04-11 22:23:47 UTC (rev 24874)
+++ trunk/src/include/krb5/krb5.hin 2011-04-12 13:36:15 UTC (rev 24875)
@@ -1993,11 +1993,7 @@
* @retval
* 0 Success
* @return
- * System errors
- * @return
- * Permission errors
- * @return
- * Kerberos error codes
+ * System errors; Permission errors; Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
krb5_cc_initialize(krb5_context context, krb5_ccache cache,
@@ -2028,7 +2024,7 @@
* @param [in] context Context structure
* @param [in] cache Credentials cache handle
*
- * @note Reinitialize @a cache with krb5_cc_resolve() or krb5_cc_gen_new().
+ * @a cache may be reinitialized with krb5_cc_resolve() or krb5_cc_gen_new().
*
* @retval
* 0 Success
@@ -2595,9 +2591,6 @@
*
* This function frees a context that was created by krb5_init_context()
* or krb5_init_secure_context().
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_context(krb5_context context);
@@ -2690,9 +2683,6 @@
*
* @param context Context structure [input, output]
* @param tgts Pointer to credentials to be freed [input, output]
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_tgt_creds(krb5_context context, krb5_creds **tgts);
@@ -3931,8 +3921,6 @@
* and @a type must be a type known to the library.
* If the @a name does not contain a colon, interpret it as a file name.
*
- * @li When necessary to accommodate file naming differences in @a OpenVMS, the type specifier prefix can be followed by an equal sign, not a colon.
- *
* @code
* Example: krb5_cc_resolve(context, "MEMORY:C_", &cache);
* @endcode
@@ -4098,9 +4086,6 @@
*
* @param [in] context Context structure
* @param [in] val Pointer to data structure to be freed
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_authenticator(krb5_context context, krb5_authenticator *val);
@@ -4109,9 +4094,6 @@
*
* @param [in] context Context structure
* @param [in] val Pointer to data structure to be freed
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_addresses(krb5_context context, krb5_address **val);
@@ -4120,9 +4102,6 @@
*
* @param [in] context Context structure
* @param [in] val Pointer to data structure to be freed
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_authdata(krb5_context context, krb5_authdata **val);
@@ -4131,9 +4110,6 @@
*
* @param [in] context Context structure
* @param [in] val Pointer to the data structure to be freed
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_ticket(krb5_context context, krb5_ticket *val);
@@ -4142,9 +4118,6 @@
*
* @param context Context structure [input, output]
* @param val Pointer to data structure to be freed [input, output]
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_error(krb5_context context, register krb5_error *val);
@@ -4153,9 +4126,6 @@
*
* @param [in] context Context structure
* @param [in] val Pointer to data structure to be freed
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_creds(krb5_context context, krb5_creds *val);
@@ -4166,9 +4136,6 @@
* @param [in] val Pointer to the data structure to be freed
*
* @note The pointer val is not freed.
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_cred_contents(krb5_context context, krb5_creds *val);
@@ -4177,9 +4144,6 @@
*
* @param context Context structure [input, output]
* @param val Pointer to data structure to be freed [input, output]
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_checksum(krb5_context context, register krb5_checksum *val);
@@ -4190,9 +4154,6 @@
* @param val Pointer to data structure to be freed [input, output]
*
* @note The pointer is not freed.
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_checksum_contents(krb5_context context, register krb5_checksum *val);
@@ -4201,9 +4162,6 @@
*
* @param context Context structure [input, output]
* @param val Pointer to data structure to be freed [input, output]
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_keyblock(krb5_context context, register krb5_keyblock *val);
@@ -4214,9 +4172,6 @@
* @param key Pointer to data structure to be freed [input, output]
*
* @note The pointer is not freed.
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_keyblock_contents(krb5_context context, register krb5_keyblock *key);
@@ -4225,9 +4180,6 @@
*
* @param context Context structure [input, output]
* @param val Pointer to data structure to be freed [input, output]
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_ap_rep_enc_part(krb5_context context, krb5_ap_rep_enc_part *val);
@@ -4236,9 +4188,6 @@
*
* @param context Context structure [input, output]
* @param val Pointer to data structure to be freed [input, output]
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_data(krb5_context context, krb5_data *val);
@@ -4249,9 +4198,6 @@
* @param [in] val Pointer to data structure to be freed
*
* @note The pointer is not freed.
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_data_contents(krb5_context context, krb5_data *val);
@@ -4262,8 +4208,6 @@
* @param val Pointer to name string to be freed [input, output]
*
* @note The pointer is not freed.
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_unparsed_name(krb5_context context, char *val);
@@ -4274,8 +4218,6 @@
* @param val Pointer to checksum type to be freed [input, output]
*
* @note Make sure the checksum contents have already been freed.
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_cksumtypes(krb5_context context, krb5_cksumtype *val);
@@ -4373,9 +4315,6 @@
*
* @param [in] context Context structure (unused)
* @param [in] lrealm Realm to be freed
- *
- * @return
- * None
*/
void KRB5_CALLCONV
krb5_free_default_realm(krb5_context context, char *lrealm);
@@ -4564,7 +4503,7 @@
const char *password, krb5_ccache ccache,
krb5_creds *creds, krb5_kdc_rep **ret_as_reply);
-/** * @deprecated Replaced by krb5_get_init_creds() */
+/** @deprecated Replaced by krb5_get_init_creds() */
KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
krb5_get_in_tkt_with_skey(krb5_context context, krb5_flags options,
krb5_address *const *addrs, krb5_enctype *ktypes,
@@ -5865,13 +5804,12 @@
#define KRB5_RECVAUTH_BADAUTHVERS 0x0002
/* initial ticket api functions */
-/**
- * @brief Text for prompt used in prompter callback function.
+/** Text for prompt used in prompter callback function.
*/
typedef struct _krb5_prompt {
- char *prompt;
- int hidden;
- krb5_data *reply;
+ char *prompt; /**< the prompt to show to the user */
+ int hidden; /**< boolean; informative prompt or hidden (as for PIN or OTP) */
+ krb5_data *reply; /**< must be allocated before call to any prompt routine */
} krb5_prompt;
/**
@@ -5935,218 +5873,216 @@
#define KRB5_GET_INIT_CREDS_OPT_SALT 0x0080
#define KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT 0x0100
#define KRB5_GET_INIT_CREDS_OPT_CANONICALIZE 0x0200
-#define KRB5_GET_INIT_CREDS_OPT_ANONYMOUS 0x0400
+#define KRB5_GET_INIT_CREDS_OPT_ANONYMOUS 0x0400
-/**
- * @brief Provide extended functionality to krb5_get_init_creds_opt_init() functionality
+/** Allocate a new extended krb5_get_init_creds_opt structure.
*
- * @param context Context structure [input, output]
- * @param opt Pointer to @a opts field in @c _krb5_get_init_creds_opt [input]
+ * @param [in,out] context Context structure
+ * @param [out] opt Pointer to @c _krb5_get_init_creds_opt structure to be allocated
*
- * Make sure to free the allocated memory when it is no longer needed.
+ * The caller of this function must call krb5_get_init_creds_opt_free() to free @a opt
+ * when it is no longer needed.
*
- * @sa getinitcreds
+ * @retval 0 - Success; Kerberos errors otherwise.
*/
krb5_error_code KRB5_CALLCONV
krb5_get_init_creds_opt_alloc(krb5_context context,
krb5_get_init_creds_opt **opt);
-/**
- * @brief Free the extended options allocated by krb5_get_init_creds_opt_alloc().
+/** Free an extended krb5_get_init_creds_opt structure.
*
- * @param context Context structure [input, output]
- * @param opt Pointer to extended options field in @c _krb5_get_init_creds_opt [input]
+ * @param [in] context Context structure (unused)
+ * @param [in] opt Pointer to @c _krb5_get_init_creds_opt structure to be freed
*
- * @return
- * None
+ * @sa krb5_get_init_creds_opt_alloc()
*/
void KRB5_CALLCONV
krb5_get_init_creds_opt_free(krb5_context context,
krb5_get_init_creds_opt *opt);
-/**
- * @brief Set @a opt field of @c _krb5_get_init_creds_opt to zero.
+/** Initialize a krb5_get_init_creds_opt structure.
*
- * @param opt Pointer to @c _krb5_get_init_creds_opt [input, output]
+ * @param [in,out] opt Pointer to krb5_get_init_creds_opt structure to be initialized
*
- * @note Call this function on an options structure on which krb5_init_creds_opt_alloc() has been called.
+ * @warning Callers MUST NOT call krb5_get_init_creds_opt_init() after allocating an
+ * krb5_get_init_creds_opt structure using krb5_get_init_creds_opt_alloc().
+ * To do so will introduce memory leaks.
*
- * Make sure to free the allocated memory when it is no longer needed.
- * @return
- * None
+ * Sets @a opt->flag to KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT
*/
void KRB5_CALLCONV
krb5_get_init_creds_opt_init(krb5_get_init_creds_opt *opt);
-/**
- * @brief Initialize the ticket lifetime field in @c _krb5_get_init_creds_opt.
+/** Initialize the ticket lifetime field in krb5_get_init_creds_opt structure.
*
- * @param opt Pointer to structure containing flags and options [input, output]
- * @param tkt_life Ticket lifetime [input]
+ * @param [in,out] opt Options
+ * @param [in] tkt_life Ticket lifetime
*
- * Make sure to free the allocated memory when it is no longer needed.
- * @return
- * None
+ * Sets KRB5_GET_INIT_CREDS_OPT_TKT_LIFE flag in @a opt
+ *
+ * The @a opt pointer supplied to this function must have been
+ * obtained using krb5_get_init_creds_opt_alloc()
*/
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_tkt_life(krb5_get_init_creds_opt *opt,
krb5_deltat tkt_life);
-/**
- * @brief Set the ticket renewal lifetime field in @c _krb5_get_init_creds_opt.
+/** Set the ticket renewal lifetime field in krb5_get_init_creds_opt structure.
*
- * @param opt Pointer to @a options field [output]
- * @param renew_life Ticket renewal lifetime [input]
+ * @param [in,out] opt Pointer to @a options field
+ * @param [in] renew_life Ticket renewal lifetime
*
- * Make sure to free the allocated memory when it is no longer needed.
- * @return
- * None
+ * Sets KRB5_GET_INIT_CREDS_OPT_iRENEW_LIFE flag in @a opt
+ *
+ * The @a opt pointer supplied to this function must have been
+ * obtained using krb5_get_init_creds_opt_alloc()
*/
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_renew_life(krb5_get_init_creds_opt *opt,
krb5_deltat renew_life);
-/**
- * @brief Set the forwardable field in @c _krb5_get_init_creds_opt.
+/** Set the forwardable field in krb5_get_init_creds_opt structure.
*
- * @param opt Pointer to options field [output]
- * @param forwardable Flag indicating whether credentials are forwardable [input]
+ * @param [in,out] opt Options
+ * @param [in] forwardable Flag indicating whether credentials are forwardable
*
- * Make sure to free the allocated memory when it is no longer needed.
- * @return
- * None
+ * Sets KRB5_GET_INIT_CREDS_OPT_FORWARDABLE flag in @a opt
+ * The @a opt pointer supplied to this function must have been
+ * obtained using krb5_get_init_creds_opt_alloc()
*/
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_forwardable(krb5_get_init_creds_opt *opt,
int forwardable);
-/**
- * @brief Set the proxiable field in @c _krb5_get_init_creds_opt.
+/** Set the proxiable field in krb5_get_init_creds_opt structure.
*
- * @param opt Pointer to options field [output]
- * @param proxiable Flag indicating whether credentials are proxiable [input]
+ * @param [in,out] opt Options
+ * @param [in] proxiable Flag indicating whether credentials are proxiable
*
- * Make sure to free the allocated memory when it is no longer needed.
- *
- * @return
- * None
+ * Sets KRB5_GET_INIT_CREDS_OPT_PROXYABLE flag in @a opt
+ * The @a opt pointer supplied to this function must have been
+ * obtained using krb5_get_init_creds_opt_alloc()
*/
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_proxiable(krb5_get_init_creds_opt *opt,
int proxiable);
+/** Set canonicalize flag in krb5_get_init_creds_opt structure.
+ *
+ * @param [in,out] opt Options
+ * @param [in] canonicalize Boolean flag
+ *
+ * Sets KRB5_GET_INIT_CREDS_OPT_CANONICALIZE flag in @a opt
+ *
+ * The @a opt pointer supplied to this function must have been
+ * obtained using krb5_get_init_creds_opt_alloc()
+ */
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_canonicalize(krb5_get_init_creds_opt *opt,
int canonicalize);
-/**
- * Request anonymous credentials from the KDC. If the client name looks like
- * "@REALM" (an empty principal name), then fully anonymous credentials are
- * requested. If the client name looks like "name at REALM," then credentials
- * tied to a specific realm are requested.
+/** Set an anonymous flag in krb5_get_init_creds_opt structure.
*
- * Credentials tied to a specific realm are not supported in this version.
+ * @param [in,out] opt Options
+ * @param [in] anonymous Boolean flag
*
+ * This function may be used to request anonymous credentials from the KDC
+ * by setting @a anonymous to non-zero.
+ *
* Note that anonymous credentials are only a request; clients must verify that
* credentials are anonymous if that is a requirement.
+ *
+ * Sets KRB5_GET_INIT_CREDS_OPT_ANONYMOUS flag in @a opt.
+ *
+ * The @a opt pointer supplied to this function must have been
+ * obtained using krb5_get_init_creds_opt_alloc()
*/
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_anonymous(krb5_get_init_creds_opt *opt,
int anonymous);
-/**
- *@brief Set the encryption list field in the @c _krb5_get_init_creds_opt.
+/** Set an encryption list field in the krb5_get_init_creds_opt structure.
*
- * @param opt Pointer to options field [output]
- * @param etype_list Pointer to the encryption type to set [input]
- * @param etype_list_length Length of the etype_list field [input]
+ * @param [in,out] opt Options
+ * @param [in] etype_list Pointer to the encryption type to set
+ * @param [in] etype_list_length Length of the etype_list field
*
- * Make sure to free the allocated memory when it is no longer needed.
- *
- * @return
- * None
- *
- * @sa enctype
+ * The @a opt pointer supplied to this function must have been
+ * obtained using krb5_get_init_creds_opt_alloc()
*/
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_etype_list(krb5_get_init_creds_opt *opt,
krb5_enctype *etype_list,
int etype_list_length);
-/**
- * @brief Set the address list in @c _krb5_get_init_creds_opt.
+/** Set an address list field in krb5_get_init_creds_opt structure.
*
- * @param opt Pointer to options field [output]
- * @param addresses Pointer to the address to set [input]
+ * @param [in,out] opt Options
+ * @param [in] addresses Addresses to be stored in the ticket
*
- * @return
- * None
+ * Sets KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST flag in @a opt
*/
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_address_list(krb5_get_init_creds_opt *opt,
krb5_address **addresses);
-/**
- * @brief Set the @a preauth_list field in @c _krb5_get_init_creds_opt.
+/** Set the preauth_list field in krb5_get_init_creds_opt structure.
*
- * @param opt Pointer to options field [output]
- * @param preauth_list Pointer to Pre-athentication type [input]
- * @param preauth_list_length Length of @a preauth_list field [input]
+ * @param [in,out] opt Options
+ * @param [in] preauth_list Pointer to Pre-athentication type
+ * @param [in] preauth_list_length Length of @a preauth_list field
*
- * @sa padata
+ * Sets KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST flag in @a opt
+ *
+ * The @a opt pointer supplied to this function must have been
+ * obtained using krb5_get_init_creds_opt_alloc()
*/
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_preauth_list(krb5_get_init_creds_opt *opt,
krb5_preauthtype *preauth_list,
int preauth_list_length);
+/** Set prompt for a salt field in krb5_get_init_creds_opt structure.
+ *
+ * @param [in,out] opt Options
+ * @param [in] salt Salt data
+ *
+ * Sets KRB5_GET_INIT_CREDS_OPT_SALT flag in @a opt.
+ */
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_salt(krb5_get_init_creds_opt *opt,
krb5_data *salt);
-/**
- * @brief Set flag in @c _krb5_get_init_creds_opt that determines whether to prompt for a password
+/** Set prompt for a password flag in krb5_get_init_creds_opt structure.
*
- * @param opt Pointer to @c _krb5_get_init_creds_opt
- * @param prompt Prompt to change password
+ * @param [in,out] opt Options
+ * @param [in] prompt Boolean prompt to change password
*
- * change for an expired password.
- *
- * @return
- * None
- * @sa getinitcreds
+ * Sets KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT flag in @a opt.
*/
void KRB5_CALLCONV
-krb5_get_init_creds_opt_set_change_password_prompt(krb5_get_init_creds_opt
- *opt, int prompt);
+krb5_get_init_creds_opt_set_change_password_prompt(krb5_get_init_creds_opt *opt,
+ int prompt);
-/** @brief Generic preauth option attribute/value pairs */
+/** Generic preauth option attribute/value pairs */
typedef struct _krb5_gic_opt_pa_data {
char *attr;
char *value;
} krb5_gic_opt_pa_data;
-/**
- * @brief Validate options passed to @a preauth plugins by krb5_get_init_creds_opt_alloc().
+/** Feed preauth plugins with the given options.
*
- * @param context Context structure [input, output]
- * @param opt Pre options [input]
- * @param attr Pre attribute [input]
- * @param value Pre value [input]
+ * @param [in,out] context Context structure
+ * @param [in] opt Pre options
+ * @param [in] attr Pre attribute
+ * @param [in] value Pre value
*
- * @retval
- * 0 Success
- * @return
- * Kerberos error codes
- *
- * Make sure to free the allocated memory when it is no longer needed.
- *
* This function allows the caller to supply options to preauth
* plugins. Preauth plugin modules are given a chance to look
- * at each option at the time this function is called in ordre
+ * at each option at the time this function is called in order
* to check the validity of the option.
- * The 'opt' pointer supplied to this function must have been
+ * The @a opt pointer supplied to this function must have been
* obtained using krb5_get_init_creds_opt_alloc()
*/
krb5_error_code KRB5_CALLCONV
@@ -6154,48 +6090,86 @@
krb5_get_init_creds_opt *opt, const char *attr,
const char *value);
-/**
- * This API sets a ccache name that will contain some TGT on calls to
- * t_init_creds functions. If set, this ccache will be used for FAST
- * (draft-ietf-krb-wg-preauth-framework) to protect the AS-REQ from observation
- * and active attack. If the fast_ccache_name is set, then FAST may be
- * required by the client library. In this and future versions, FAST will be
- * used if available; krb5_get_init_creds_opt_set_fast_flags() may be used to
- * require that the request fail is FAST is unavailable. In MIT Kerberos 1.7
- * setting the fast ccache at all required that FAST be present or the request
- * would fail.
+/** Set a location of FAST cache containing TGT based on cache name.
+ *
+ * @param [in,out] context Context structure
+ * @param [in,out] opt Options
+ * @param [in] fast_ccache_name Credential cache name
+ *
+ * If the @a fast_ccache_name is set, then FAST may be
+ * required by the client library. Starting from MIT Kerberos version 1.8
+ * FAST is used if available; krb5_get_init_creds_opt_set_fast_flags()
+ * may be used to require that the request fail is FAST is unavailable.
+ * In version 1.7 setting the fast ccache at all required that FAST
+ * be present or the request would fail.
+ * The @a opt pointer supplied to this function must have been
+ * obtained using krb5_get_init_creds_opt_alloc()
*/
krb5_error_code KRB5_CALLCONV
krb5_get_init_creds_opt_set_fast_ccache_name(krb5_context context,
krb5_get_init_creds_opt *opt,
const char *fast_ccache_name);
-/** Set the FAST ccache name as in
- * krb5_get_init_creds_opt_set_fast_ccache_name() but using a krb5_ccache
- * rather than a name.
+/** Set a location of FAST cache containing TGT based on krb5_ccache object.
+ *
+ * @param [in,out] context Context structure
+ * @param [in,out] opt Options
+ * @param [in] fast_ccache_name Credential cache handle
+ *
+ * Set the FAST ccache name as in krb5_get_init_creds_opt_set_fast_ccache_name(),
+ * but using a krb5_ccache rather than a name.
+ * The @a opt pointer supplied to this function must have been
+ * obtained using krb5_get_init_creds_opt_alloc()
*/
krb5_error_code KRB5_CALLCONV
krb5_get_init_creds_opt_set_fast_ccache(krb5_context context,
krb5_get_init_creds_opt *opt,
krb5_ccache fast_ccache_name);
-/**
- * Set a ccache where resulting credentials will be stored. If set, then the
- * krb5_get_init_creds family of APIs will write out credentials to the given
- * ccache. Setting an output ccache is desirable both because it simplifies
- * calling code and because it permits the krb5_get_init_creds APIs to write
- * out configuration information about the realm to the ccache.
+/** Set an output credentials cache in krb5_get_init_creds_opt structure.
+ *
+ * @param [in,out] context Context structure
+ * @param [in,out] opt Options
+ * @param [in] ccache Credential cache to use
+ *
+ * If set, then the krb5_get_init_creds family of APIs will write out credentials
+ * to the given ccache. Setting an output ccache is desirable both because it
+ * simplifies calling code and because it permits the krb5_get_init_creds APIs
+ * to write out configuration information about the realm to the ccache.
*/
krb5_error_code KRB5_CALLCONV
krb5_get_init_creds_opt_set_out_ccache(krb5_context context,
krb5_get_init_creds_opt *opt,
krb5_ccache ccache);
+/** Store FAST flags in krb5_get_init_creds_opt structure.
+ *
+ * @param [in,out] context Context structure
+ * @param [in,out] opt Options
+ * @param [in] flags FAST flags (for example, KRB5_FAST_REQUIRED)
+ *
+ * This function may be used to require that the request fail if FAST is unavailable.
+ *
+ * @retval
+ * 0 - Success; Kerberos errors otherwise.
+ */
krb5_error_code KRB5_CALLCONV
krb5_get_init_creds_opt_set_fast_flags(krb5_context context,
krb5_get_init_creds_opt *opt,
krb5_flags flags);
+/** Obtain FAST flags from krb5_get_init_creds_opt structure.
+ *
+ * @param [in,out] context Context structure
+ * @param [in] opt Options
+ * @param [out] out_flags FAST flags
+ *
+ * Get FAST @a out_flags from @a opt
+ * This function may be used to verify if KDC supports FAST.
+ *
+ * @retval
+ * 0 - Success; Kerberos errors otherwise.
+ */
krb5_error_code KRB5_CALLCONV
krb5_get_init_creds_opt_get_fast_flags(krb5_context context,
krb5_get_init_creds_opt *opt,
@@ -6210,9 +6184,15 @@
krb5_timestamp account_expiration,
krb5_boolean is_last_req);
-/**
- * @brief Set a callback to receive password and account expiration times.
+/** Set an expire callback in extended krb5_get_init_creds_opt structure.
*
+ * @param [in,out] context Context structure
+ * @param [in,out] opt Options structure
+ * @param [in] cb Callback function
+ * @param [in] data Data
+ *
+ * Set a callback to receive password and account expiration times.
+ *
* This option only applies to krb5_get_init_creds_password(). @a cb will be
* invoked if and only if credentials are successfully acquired. The callback
* will receive the @a context from the krb5_get_init_creds_password() call and
@@ -6236,7 +6216,7 @@
* caller's responsibility to avoid displaying a password expiry warning in
* this case.
*
- * Setting an expire callback with this API will cause
+ * @warning Setting an expire callback with this API will cause
* krb5_get_init_creds_password() not to send password expiry warnings to the
* prompter, as it ordinarily may.
*/
@@ -6246,21 +6226,23 @@
krb5_expire_callback_func cb,
void *data);
-/**
- * @brief Get initial credentials using a password.
+/** Get initial credentials using a password.
*
- * @param context Context structure [input, output]
- * @param creds Pointer to credentials structure [output]
- * @param client Client principal [input]
- * @param password Password associated with initial credentials [input, output]
- * @param prompter Pointer to password prompt routine [input]
- * @param data Data for password prompt routine [input]
- * @param start_time Time that credentials first became valid [input]
- * @param in_tkt_service Pointer to output buffer containing the TGT [input]
- * @param k5_gic_options Pointer to structure containing flags and options [input]
+ * @param [in] context Context structure
+ * @param [in,out] creds Credentials structure to be filled in
+ * @param [in] client Client principal
+ * @param [in] password Password associated with initial credentials
+ * @param [in] prompter Pointer to password prompt routine
+ * @param [in] data Data for password prompt routine
+ * @param [in] start_time Time when a ticket should become valid; 0 means from now
+ * @param [in] in_tkt_service Service name to use while getting initial credentials
+ * @param [in] k5_gic_options Flags and options
*
- * Make sure to free the allocated memory when it is no longer needed.
+ * This function requests KDC for an initial credentials for @a client using
+ * @a password.
*
+ * @sa krb5_verify_init_creds()
+ *
* @retval
* 0 Success
* @retval
@@ -6438,26 +6420,25 @@
krb5_tkt_creds_get_times(krb5_context context, krb5_tkt_creds_context ctx,
krb5_ticket_times *times);
-/**
- * @brief Get initial credentials using a key table.
+/** Get initial credentials using a key table.
*
- * @param context Context structure [input, output]
- * @param creds Pointer to credentials structure [output]
- * @param client Client princiapl [input]
- * @param arg_keytab Key table handle [input]
- * @param start_time Time when a ticket becomes valid [input]
- * @param in_tkt_service Requesting server's principal name [input]
- * @param k5_gic_options Pointer to a structure containing flags and options [input]
+ * @param [in] context Context structure
+ * @param [in,out] creds Credentials structure to be filled in
+ * @param [in] client Client principal to get initial credentials for
+ * @param [in] arg_keytab Key table handle
+ * @param [in] start_time Time when a ticket should become valid; 0 means from now
+ * @param [in] in_tkt_service Service name to use while getting initial credentials
+ * @param [in] k5_gic_options Flags and options
*
- * Make sure to free the allocated memory when it is no longer needed.
+ * This function requests initial credentials for @a client from KDC using a key
+ * stored in @a arg_keytab, or from the default keytab if @a arg_keytab is NULL.
*
+ * @sa krb5_verify_init_creds()
+ *
* @retval
- * 0 Success
- * @retval
- * ENOMEM Insufficient memory
+ * 0 Success
* @return
* Kerberos error codes
- *
*/
krb5_error_code KRB5_CALLCONV
krb5_get_init_creds_keytab(krb5_context context, krb5_creds *creds,
Modified: trunk/src/lib/krb5/krb/fwd_tgt.c
===================================================================
--- trunk/src/lib/krb5/krb/fwd_tgt.c 2011-04-11 22:23:47 UTC (rev 24874)
+++ trunk/src/lib/krb5/krb/fwd_tgt.c 2011-04-12 13:36:15 UTC (rev 24875)
@@ -1,5 +1,5 @@
/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
-/* lib/krb5/krb/fwd_tgt.c */
+/* lib/krb5/krb/fwd_tgt.c Definition of krb5_fwd_tgt_creds() routine */
/*
* Copyright 1995 by the Massachusetts Institute of Technology.
* All Rights Reserved.
@@ -34,15 +34,10 @@
/* Get a TGT for use at the remote host */
krb5_error_code KRB5_CALLCONV
-krb5_fwd_tgt_creds(krb5_context context, krb5_auth_context auth_context, char *rhost, krb5_principal client, krb5_principal server, krb5_ccache cc, int forwardable, krb5_data *outbuf)
-
-
-
-
-
-
+krb5_fwd_tgt_creds(krb5_context context, krb5_auth_context auth_context,
+ char *rhost, krb5_principal client, krb5_principal server,
+ krb5_ccache cc, int forwardable, krb5_data *outbuf)
/* Should forwarded TGT also be forwardable? */
-
{
krb5_replay_data replaydata;
krb5_data * scratch = 0;
More information about the cvs-krb5
mailing list