svn rev #24913: trunk/ doc/doxy_examples/ src/include/krb5/
tsitkova@MIT.EDU
tsitkova at MIT.EDU
Thu May 5 14:43:49 EDT 2011
http://src.mit.edu/fisheye/changelog/krb5/?cs=24913
Commit By: tsitkova
Log Message:
Updated documentation: added usage example for krb5_tkt_creds family, removed "(unused)" string from the comments and other cleanup.
Changed Files:
A trunk/doc/doxy_examples/tkt_creds.c
U trunk/src/include/krb5/krb5.hin
Added: trunk/doc/doxy_examples/tkt_creds.c
===================================================================
--- trunk/doc/doxy_examples/tkt_creds.c (rev 0)
+++ trunk/doc/doxy_examples/tkt_creds.c 2011-05-05 18:43:49 UTC (rev 24913)
@@ -0,0 +1,55 @@
+/** @example tkt_creds.c
+ *
+ * Usage example for krb5_tkt_creds function family
+ */
+#include "krb5.h"
+
+krb5_error_code
+func(krb5_context context, krb5_flags options,
+ krb5_ccache ccache, krb5_creds *in_creds,
+ krb5_creds **out_creds)
+{
+ krb5_error_code code = KRB5_OK;
+ krb5_creds *ncreds = NULL;
+ krb5_tkt_creds_context ctx = NULL;
+
+ *out_creds = NULL;
+
+ /* Allocate a container. */
+ ncreds = k5alloc(sizeof(*ncreds), &code);
+ if (ncreds == NULL)
+ goto cleanup;
+
+ /* Make and execute a krb5_tkt_creds context to get the credential. */
+ code = krb5_tkt_creds_init(context, ccache, in_creds, options, &ctx);
+ if (code != KRB5_OK)
+ goto cleanup;
+ code = krb5_tkt_creds_get(context, ctx);
+ if (code != KRB5_OK)
+ goto cleanup;
+ code = krb5_tkt_creds_get_creds(context, ctx, ncreds);
+ if (code != KRB5_OK)
+ goto cleanup;
+
+ *out_creds = ncreds;
+ ncreds = NULL;
+
+cleanup:
+ krb5_free_creds(context, ncreds);
+ krb5_tkt_creds_free(context, ctx);
+ return code;
+}
+
+/* Allocate zeroed memory; set *code to 0 on success or ENOMEM on failure. */
+static inline void *
+k5alloc(size_t len, krb5_error_code *code)
+{
+ void *ptr;
+
+ /* Allocate at least one byte since zero-byte allocs may return NULL. */
+ ptr = calloc((len > 0) ? len : 1, 1);
+ *code = (ptr == NULL) ? ENOMEM : 0;
+ return ptr;
+}
+
+
Modified: trunk/src/include/krb5/krb5.hin
===================================================================
--- trunk/src/include/krb5/krb5.hin 2011-05-03 14:25:11 UTC (rev 24912)
+++ trunk/src/include/krb5/krb5.hin 2011-05-05 18:43:49 UTC (rev 24913)
@@ -282,16 +282,22 @@
? (princ)->data + (i) \
: NULL)
-/*
- * Constants for realm referrals.
- */
+/** Constant for realm referrals. */
#define KRB5_REFERRAL_REALM ""
/*
* Referral-specific functions.
*/
-krb5_boolean KRB5_CALLCONV krb5_is_referral_realm(const krb5_data *r);
+/** Check for a match with KRB5_REFERRAL_REALM.
+ *
+ * @param [in] r Realm to check
+ *
+ * @retval TRUE if @a r is zero-length; Otherwise - FALSE
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_is_referral_realm(const krb5_data *r);
+
/** Return an anonymous realm data.
*
* This function returns constant storage that must not be freed.
@@ -1541,9 +1547,7 @@
*/
/* Time set */
-/**
- * Ticket start time, end time, and renewal duration.
- */
+/** Ticket start time, end time, and renewal duration. */
typedef struct _krb5_ticket_times {
krb5_timestamp authtime; /**< Time at which KDC issued the initial ticket that corresponds to this ticket */
/* XXX ? should ktime in KDC_REP == authtime
@@ -1553,7 +1557,7 @@
krb5_timestamp renew_till; /**< Latest time at which renewal of ticket can be valid */
} krb5_ticket_times;
-/** Structure for auth data */
+/** Structure for auth data */
typedef struct _krb5_authdata {
krb5_magic magic;
krb5_authdatatype ad_type; /**< ADTYPE */
@@ -1612,7 +1616,7 @@
krb5_authdata **authorization_data; /**< New add by Ari, auth data */
} krb5_authenticator;
-/**
+/*
* Ticket authentication data.
*/
typedef struct _krb5_tkt_authent {
@@ -1622,9 +1626,7 @@
krb5_flags ap_options;
} krb5_tkt_authent;
-/**
- * Credentials structure including ticket, session key, and lifetime info.
- */
+/** Credentials structure including ticket, session key, and lifetime info. */
typedef struct _krb5_creds {
krb5_magic magic;
krb5_principal client; /**< client's principal identifier */
@@ -1771,7 +1773,7 @@
krb5_ui_4 seq_number; /**< sequence #, optional */
} krb5_ap_rep_enc_part;
-/** Unused. */
+/* Unused */
typedef struct _krb5_response {
krb5_magic magic;
krb5_octet message_type;
@@ -1810,14 +1812,20 @@
krb5_cred_enc_part *enc_part2; /**< unencrypted version, if available*/
} krb5_cred;
-/** Sandia password generation structure */
+/*
+ * Sandia password generation structure
+ * Used by internal functions only
+ */
typedef struct _passwd_phrase_element {
krb5_magic magic;
krb5_data *passwd;
krb5_data *phrase;
} passwd_phrase_element;
-/** @brief Password data.*/
+/*
+ * Password data.
+ * Used by internal functions only
+ */
typedef struct _krb5_pwd_data {
krb5_magic magic;
int sequence_count;
@@ -2588,12 +2596,14 @@
krb5_error_code KRB5_CALLCONV
krb5_copy_context(krb5_context ctx, krb5_context *nctx_out);
-/**
- * @brief Set the default TGS (ticket granting service) encryption types for the context.
+/** Set default TGS encryption types in a krb5_context structure.
*
- * @param context Context structure [input, output]
- * @param etypes Encryption type [input]
+ * @param [in,out] context Context structure
+ * @param [in] etypes Encryption type(s) to set
*
+ * This function sets the default enctype list for TGS requests
+ * made using @a context to @a etypes.
+ *
* @note This overrides the default list (from config file or built-in).
*
* @retval
@@ -2602,8 +2612,6 @@
* KRB5_PROG_ETYPE_NOSUPP Program lacks support for encryption type
* @return
* Kerberos error codes
- *
- * @sa enctype
*/
krb5_error_code KRB5_CALLCONV
krb5_set_default_tgs_enctypes(krb5_context context, const krb5_enctype *etypes);
@@ -2637,18 +2645,16 @@
/* libkrb.spec */
-/**
- * @brief Decrypt a ticket using the specified key table.
+/** Decrypt a ticket using the specified key table.
*
- * @param context Context structure [input, output]
- * @param kt Key table [input]
- * @param ticket Ticket [input, output]
+ * @param [in] context Context structure
+ * @param [in] kt Key table
+ * @param [in,out] ticket Ticket to be decrypted
*
- * @retval
- * 0 Success
- * @return
- * Kerberos error codes
+ * This function takes a @a ticket as input and decrypts it using the
+ * provided key data from @a kt. The result is placed into @a ticket->enc_part2.
*
+ * @retval 0 Success; Otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
krb5_server_decrypt_ticket_keytab(krb5_context context, const krb5_keytab kt,
@@ -3198,7 +3204,7 @@
/** Search a list of addresses for a specified address.
*
- * @param context (unused)
+ * @param context Context structure
* @param [in] addr Address to search for
* @param [in] addrlist Address list to be searched.
* Specify NULL if there is no address list
@@ -3215,7 +3221,7 @@
/** Compare two Kerberos addresses.
*
- * @param context (unused)
+ * @param context Context structure
* @param [in] addr1 First address to be compared
* @param [in] addr2 Second address to be compared
*
@@ -3228,7 +3234,7 @@
/** Return an ordering of the specified addresses.
*
- * @param context (unused)
+ * @param context Context structure
* @param [in] addr1 First address
* @param [in] addr2 Second address
*
@@ -3802,8 +3808,11 @@
/** Free the contents of a key table entry.
*
- * @warning Use krb5_free_keytab_entry_contents instead; this does the same thing but is
- * misnamed and retained for backward compatability.
+ * @param [in] context Context structure
+ * @param [in] entry Key table entry to be freed
+ *
+ * @warning Use krb5_free_keytab_entry_contents instead; this does the same
+ * thing but is misnamed and retained for backward compatability.
*/
krb5_error_code KRB5_CALLCONV
krb5_kt_free_entry(krb5_context context, krb5_keytab_entry *entry);
@@ -3846,17 +3855,13 @@
krb5_error_code KRB5_CALLCONV
krb5_kt_add_entry(krb5_context context, krb5_keytab id, krb5_keytab_entry *entry);
-/**
- * @brief Convert a principal name into the default salt for that principal.
+/** Convert a principal name into the default salt for that principal.
*
- * @param context Context structure [input, output]
- * @param pr Principal name [input]
- * @param ret Pointer to the default salt for given principal [output]
+ * @param [in] context Context structure
+ * @param [in] pr Principal name
+ * @param [out] ret Default salt for @a pr to be filled in
*
- * @retval
- * 0 Success
- * @return
- * Kerberos error codes
+ * @retval 0 Success; Otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV_WRONG
krb5_principal2salt(krb5_context context,
@@ -4024,7 +4029,7 @@
/** Free a krb5_authenticator structure.
*
- * @param context (unused) Context structure
+ * @param context Context structure
* @param [in] val Pointer to authenticator structure to be freed
*
* This function frees the storage assigned to @a krb5_authenticator
@@ -4035,7 +4040,7 @@
/** Free the data stored in array of addresses.
*
- * @param context (unused) Context structure
+ * @param context Context structure
* @param [in] val Array of addresses to be freed
*
* This function frees the storage assigned to array of @a krb5_address
@@ -4048,7 +4053,7 @@
/** Free the storage assigned to array of authentication data.
*
- * @param context (unused) Context structure
+ * @param context Context structure
* @param [in] val Array of authentication data to be freed
*
* This function frees the storage assigned to array of @a krb5_authdata
@@ -4104,7 +4109,7 @@
/** Free a krb5_checksum structure.
*
- * @param context (unused) Context structure
+ * @param context Context structure
* @param [in] val Pointer to data structure to be freed
*
* This function frees the contents of a @a val and then releases @a val itself.
@@ -4114,7 +4119,7 @@
/** Free the contents of a krb5_checksum structure.
*
- * @param context (unused) Context structure
+ * @param context Context structure
* @param [in] val Checksum structure to be released
*
* @note The pointer to @a val itself is not freed.
@@ -4156,7 +4161,7 @@
/** Free the storage assigned to a krb5_data object
*
- * @param context (unused) Context structure
+ * @param context Context structure
* @param [in] val Pointer to data structure to be freed
*
* This function zeros out and frees the contents field of @a val and then
@@ -4167,7 +4172,7 @@
/** Zero out and free the contents of a krb5_data object
*
- * @param context (unused) Context structure
+ * @param context Context structure
* @param [in] val Pointer to data structure to be freed
*
* @note The pointer to @a val itself is not freed.
@@ -4177,7 +4182,7 @@
/** Free a simple character name string returned by krb5_unparse_name().
*
- * @param context (unused) Context structure
+ * @param context Context structure
* @param [in] val Pointer to name string to be freed
*
* @note The pointer to @a val itself is not freed.
@@ -4187,7 +4192,7 @@
/** Free an array of checksum types.
*
- * @param context (unused) Context structure
+ * @param context Context structure
* @param [in] val Array of checksum types to be freed
*
* @note Make sure the checksum contents have already been freed.
@@ -4282,7 +4287,7 @@
/** Free the default realm string returned by krb5_get_default_realm().
*
- * @param context (unused)
+ * @param context Context structure
* @param [in] lrealm Realm to be freed
*/
void KRB5_CALLCONV
@@ -4986,7 +4991,7 @@
/** Set a flags field in a krb5_auth_context structure.
*
- * @param context (unused)
+ * @param context Context structure
* @param [in,out] auth_context Authentication context
* @param [in] flags Flags bit mask
*
@@ -5003,7 +5008,7 @@
/** Retrieve a flags field from a krb5_auth_context structure.
*
- * @param context (unused)
+ * @param context Context structure
* @param [in] auth_context Authentication context
* @param [out] flags Flags bit mask
*
@@ -5021,7 +5026,7 @@
/** Set checksum_function related fields in krb5_auth_contex structure.
*
- * @param context (unused)
+ * @param context Context structure
* @param [in,out] auth_context Authentication context
* @param [in] func Function to perform the checksum
* @param [in] data Pointer to arbitrary to be received by @a func
@@ -5038,7 +5043,7 @@
/** Get checksum_function related fields from krb5_auth_contex structure.
*
- * @param context (unused)
+ * @param context Context structure
* @param [in] auth_context Authentication context
* @param [out] func Pointer to krb5 function that performs the checksum
* @param [out] data Pointer to data
@@ -5140,7 +5145,7 @@
/** Get a copy of an encryption key from a krb5_auth_context structure.
*
- * @param ctx (unused)
+ * @param context Context structure
* @param [in] auth_context Authentication context
* @param [in,out] key Output key structure to be filled in
*
@@ -5170,7 +5175,7 @@
/** Get a copy of a send_subkey key from a krb5_auth_context structure.
*
- * @param ctx (unused)
+ * @param ctx Context structure
* @param [in] ac Authentication context
* @param [in,out] key Key structure to be filled in
*
@@ -5185,7 +5190,7 @@
/** Retrieve a recv_subkey keyblock from a krb5_auth_context structure.
*
- * @param ctx (unused)
+ * @param ctx Context structure
* @param [in] ac Authentication context
* @param [out] keyblock Key block structure
*
@@ -5200,7 +5205,7 @@
/** Get a copy of a recv_subkey key from a krb5_auth_context structure.
*
- * @param ctx (unused)
+ * @param ctx Context structure
* @param [in] ac Authentication context
* @param [in,out] key Key block structure to be filled in
*
@@ -5283,7 +5288,7 @@
/** Retrieve a local sequence number from a krb5_auth_context structure.
*
- * @param context (unused)
+ * @param context Context structure
* @param [in] auth_context Authentication context
* @param [in,out] seqnumber Local sequence number to be filled in
*
@@ -5300,7 +5305,7 @@
/** Retrieve a remote sequence number from a krb5_auth_context structure.
*
- * @param context (unused)
+ * @param context Context structure
* @param [in] auth_context Authentication context
* @param [in,out] seqnumber Remote sequence number to be filled in
*
@@ -5327,7 +5332,7 @@
/** Set the replay cache field in a krb5_auth_context structure.
*
- * @param context (unused)
+ * @param context Context structure
* @param [in,out] auth_context Authentication context
* @param [in] rcache Replay cache haddle
*
@@ -5339,7 +5344,7 @@
/** Retrieve rcache field from a krb5_auth_context structure.
*
- * @param context (unused)
+ * @param context Context structure
* @param [in] auth_context Authentication context
* @param [out] rcache Replay cache handle
*
@@ -5369,7 +5374,7 @@
/** Set a checksum types field in a krb5_auth_context structure.
*
- * @param context (unused)
+ * @param context Context structure
* @param [in,out] auth_context Authentication context
* @param [in] cksumtype Checksun type
*
@@ -5497,7 +5502,7 @@
/** Free the memory allocated by krb5_get_host_realm().
*
- * @param context Context structure (unused)
+ * @param context Context structure
* @param [in] realmlist List of the realm names to be released
*
* @retval
@@ -5548,26 +5553,25 @@
krb5_auth_con_genaddrs(krb5_context context, krb5_auth_context auth_context,
int infd, int flags);
-/**
- * @brief Set time offset field in a @c _krb5_context structure.
+/** Set time offset field in a krb5_context structure.
*
- * @param context Context structure [input, output]
- * @param seconds Number of seconds to set in @c time_offset field in @a context [input]
- * @param microseconds Number of microseconds to set in @c usec_offset field in context [input]
+ * @param [in] context Context structure
+ * @param [in] seconds Number of seconds to set in @c time_offset
+ * field in @a context
+ * @param [in] microseconds Number of microseconds to set in @c usec_offset
+ * field in @a context
*
* Take the @a real @a time as input, and set the time offset fields in the
- * context structure so the @c krb5_time routines return the correct time, as corrected by the difference
- * between the system time and the @a real @a time as passed to this routine.
+ * context structure so the @c krb5_time routines return the correct time,
+ * as corrected by the difference between the system time and the @a real @a time as passed to this routine.
*
* Make sure to free the allocated memory when it is no longer needed.
*
- * @retval
- * 0 Success
- * @return
- * Kerberos error codes
+ * @retval 0 Success; Otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
-krb5_set_real_time(krb5_context context, krb5_timestamp seconds, krb5_int32 microseconds);
+krb5_set_real_time(krb5_context context, krb5_timestamp seconds,
+ krb5_int32 microseconds);
/** Return the time offsets from the os context.
*
@@ -5822,7 +5826,7 @@
/** Free an extended krb5_get_init_creds_opt structure.
*
- * @param context Context structure (unused)
+ * @param context Context structure
* @param [in] opt Pointer to @c _krb5_get_init_creds_opt structure to be freed
*
* @sa krb5_get_init_creds_opt_alloc()
@@ -6257,20 +6261,24 @@
typedef struct _krb5_tkt_creds_context *krb5_tkt_creds_context;
/**
- * @brief Create a context to get credentials from a KDC's Ticket Granting Service.
+ * Create a context to get credentials from a KDC's Ticket Granting Service.
*
* @param[in] context A krb5 library context (see krb5_init_context())
* @param[in] ccache A credentials cache containing the desired credentials
* or a Ticket Granting Ticket (TGT) for the client realm.
* TGT and service credentials may be stored into this
* cache as they are acquired.
- * @param creds
+ * @param[in] creds Input credentials
* @param[in] options KRB5_GC_* options for this request.
* @param[out] ctx The TGS acquisition context.
*
* The resulting TGS acquisition context can be used asynchronously with
* krb5_tkt_creds_step() or synchronously with krb5_tkt_creds_get(). See also
* krb5_get_credentials() for synchrous use.
+ *
+ * Use krb5_tkt_creds_free() to free @a ctx when it is no longer needed.
+ *
+ * @retval 0 Success; Otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache,
@@ -6278,7 +6286,7 @@
krb5_tkt_creds_context *ctx);
/**
- * @brief Synchronously obtain credentials within an acquisition context.
+ * Synchronously obtain credentials within an acquisition context.
*
* @param[in] context A krb5 library context (see krb5_init_context())
* @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init())
@@ -6286,12 +6294,14 @@
* This function repeatedly generates requests, sends them to the appropriate
* realms' KDCs, and processes the replies until credentials are available for
* retrieval with krb5_tkt_creds_get_creds().
+ *
+ * @retval 0 Success; Otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
krb5_tkt_creds_get(krb5_context context, krb5_tkt_creds_context ctx);
/**
- * @brief Retrieve credentials from an acquisition context, filling in @a creds.
+ * Retrieve credentials from an acquisition context, filling in @a creds.
*
* @param[in] context A krb5 library context (see krb5_init_context())
* @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init())
@@ -6299,13 +6309,15 @@
*
* The acquisition context must have completed obtaining credentials via either
* krb5_tkt_creds_get() or krb5_tkt_creds_step().
+ *
+ * @retval 0 Success; Otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
krb5_tkt_creds_get_creds(krb5_context context, krb5_tkt_creds_context ctx,
krb5_creds *creds);
/**
- * @brief Release the resources used by an acquisition context.
+ * Release the resources used by an acquisition context.
*
* @param[in] context A krb5 library context (see krb5_init_context())
* @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init())
@@ -6316,7 +6328,7 @@
#define KRB5_TKT_CREDS_STEP_FLAG_CONTINUE 0x1 /* More responses needed. */
/**
- * @brief Process a response and generate the next request to acquire credentials.
+ * Process a response and generate the next request to acquire credentials.
*
* @param[in] context A krb5 library context (see krb5_init_context())
* @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init())
@@ -6330,6 +6342,8 @@
* KRB5_TKT_CREDS_STEP_FLAG_CONTINUE. In that case, the caller must transport
* @a out to a KDC for @a realm and receive a response, which should be
* provided as @a in to the next call.
+ *
+ * @retval 0 Success; Otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
krb5_tkt_creds_step(krb5_context context, krb5_tkt_creds_context ctx,
@@ -6337,7 +6351,7 @@
unsigned int *flags);
/**
- * @brief Retrieve ticket times for obtained credentials, filling in @a times.
+ * Retrieve ticket times for obtained credentials, filling in @a times.
*
* @param[in] context A krb5 library context (see krb5_init_context())
* @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init())
@@ -6345,6 +6359,8 @@
*
* The acquisition context must have completed obtaining credentials via either
* krb5_tkt_creds_get() or krb5_tkt_creds_step().
+ *
+ * @retval 0 Success; Otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
krb5_tkt_creds_get_times(krb5_context context, krb5_tkt_creds_context ctx,
@@ -6648,11 +6664,9 @@
/** Clear the error message state.
*
- * @param [in,out] cxt Context structure
+ * @param [in,out] ctx Context structure
*
* Similar to krb5_free_error_message() but @a ctx->msg is set to NULL.
- *
- * @todo link to extended message state
*/
void KRB5_CALLCONV
krb5_clear_error_message(krb5_context ctx);
More information about the cvs-krb5
mailing list