From: Greg Hudson Date: Wed, 22 Jun 2011 19:24:51 +0000 (+0000) Subject: Formatting and editorial pass over krb5.hin doxygen markup X-Git-Tag: krb5-1.10-alpha1~400 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=bf9671e059acd928cf578c9807850c5397539f1c;p=krb5.git Formatting and editorial pass over krb5.hin doxygen markup git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@24973 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin index 8aed7b68a..76c98cd0c 100644 --- a/src/include/krb5/krb5.hin +++ b/src/include/krb5/krb5.hin @@ -289,16 +289,18 @@ typedef const krb5_principal_data *krb5_const_principal; * Referral-specific functions. */ -/** Check for a match with KRB5_REFERRAL_REALM. +/** + * Check for a match with KRB5_REFERRAL_REALM. * - * @param [in] r Realm to check + * @param [in] r Realm to check * - * @retval TRUE if @a r is zero-length; Otherwise - FALSE + * @return @c TRUE if @a r is zero-length, @c FALSE otherwise */ krb5_boolean KRB5_CALLCONV krb5_is_referral_realm(const krb5_data *r); -/** Return an anonymous realm data. +/** + * Return an anonymous realm data. * * This function returns constant storage that must not be freed. * @@ -307,7 +309,8 @@ krb5_is_referral_realm(const krb5_data *r); const krb5_data *KRB5_CALLCONV krb5_anonymous_realm(void); -/** Build an anonymous principal. +/** + * Build an anonymous principal. * * This function returns constant storage that must not be freed. * @@ -374,13 +377,13 @@ typedef struct _krb5_keyblock { krb5_octet *contents; } krb5_keyblock; -/** Opaque identifier for a key. +/** + * Opaque identifier for a key. * - * Use with the krb5_k APIs for better - * performance for repeated operations with the same key usage. Key - * identifiers must not be used simultaneously within multiple - * threads, as they may contain mutable internal state and are not - * mutex-protected. + * Use with the krb5_k APIs for better performance for repeated operations with + * the same key and usage. Key identifiers must not be used simultaneously + * within multiple threads, as they may contain mutable internal state and are + * not mutex-protected. */ struct krb5_key_st; typedef struct krb5_key_st *krb5_key; @@ -420,7 +423,7 @@ typedef struct _krb5_crypto_iov { #define ENCTYPE_DES_CBC_MD4 0x0002 /**< DES cbc mode with RSA-MD4 */ #define ENCTYPE_DES_CBC_MD5 0x0003 /**< DES cbc mode with RSA-MD5 */ #define ENCTYPE_DES_CBC_RAW 0x0004 /**< @deprecated DES cbc mode raw */ -#define ENCTYPE_DES3_CBC_SHA 0x0005 /**< @deprecated DES-3 cbc mode with NIST-SHA */ +#define ENCTYPE_DES3_CBC_SHA 0x0005 /**< @deprecated DES-3 cbc with SHA1 */ #define ENCTYPE_DES3_CBC_RAW 0x0006 /**< @deprecated DES-3 cbc mode raw */ #define ENCTYPE_DES_HMAC_SHA1 0x0008 /**< @deprecated */ /* PKINIT */ @@ -454,19 +457,21 @@ typedef struct _krb5_crypto_iov { #define CKSUMTYPE_MD5_HMAC_ARCFOUR -137 /*Microsoft netlogon cksumtype*/ #define CKSUMTYPE_HMAC_MD5_ARCFOUR -138 /*Microsoft md5 hmac cksumtype*/ -/* The following are entropy source designations. Whenever - * krb5_C_random_add_entropy is called, one of these source ids is passed - * in. This allows the library to better estimate bits of - * entropy in the sample and to keep track of what sources of entropy have - * contributed enough entropy. Sources marked internal MUST NOT be - * used by applications outside the Kerberos library +/* + * The following are entropy source designations. Whenever + * krb5_C_random_add_entropy is called, one of these source ids is passed in. + * This allows the library to better estimate bits of entropy in the sample and + * to keep track of what sources of entropy have contributed enough entropy. + * Sources marked internal MUST NOT be used by applications outside the + * Kerberos library */ enum { KRB5_C_RANDSOURCE_OLDAPI = 0, /*calls to krb5_C_RANDOM_SEED (INTERNAL)*/ KRB5_C_RANDSOURCE_OSRAND = 1, /* /dev/random or equivalent (internal)*/ KRB5_C_RANDSOURCE_TRUSTEDPARTY = 2, /* From KDC or other trusted party*/ - /*This source should be used carefully; data in this category + /* + * This source should be used carefully; data in this category * should be from a third party trusted to give random bits * For example keys issued by the KDC in the application server. */ @@ -490,179 +495,182 @@ enum { #define krb5_xc(ptr,args) ((*(ptr)) args) #endif - /** Encrypt data using a key. +/** + * Encrypt data using a key. * - * @param context Context structure - * @param [in] key Enryption key - * @param [in] usage Key usage (see KRB5_KEYUSAGE types) - * @param [in,out] cipher_state Initial vector; specify NULL if not needed - * @param [in] input Data to be encrypted - * @param [out] output Encrypted data + * @param [in] context Library context + * @param [in] key Encryption key + * @param [in] usage Key usage (see KRB5_KEYUSAGE types) + * @param [in,out] cipher_state Cipher state; specify NULL if not needed + * @param [in] input Data to be encrypted + * @param [out] output Encrypted data * - * This function encrypts the data block @a input and stores the output - * into @a output. The actual encryption key will derive from @a key if - * key derivation is permitted for the encryption algorithm. - * @a cipher_state specifies the starting value for the encryption operation, - * and is updated with the state to be passed as input to the next operation. + * This function encrypts the data block @a input and stores the output into @a + * output. The actual encryption key will be derived from @a key and @a usage + * if key derivation is specified for the encryption type. If non-null, @a + * cipher_state specifies the beginning state for the encryption operation, and + * is updated with the state to be passed as input to the next operation. * * @note The caller must initialize @a output and allocate at least enough * space for the result (using krb5_c_encrypt_length() to determine the amount - * of space needed). @a output->length will be set to the actual length of the - * ciphertext if it was larger. + * of space needed). @a output->length will be set to the actual length of the + * ciphertext. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_encrypt(krb5_context context, const krb5_keyblock *key, krb5_keyusage usage, const krb5_data *cipher_state, const krb5_data *input, krb5_enc_data *output); -/** Decrypt data using a key. +/** + * Decrypt data using a key. * - * @param context Context structure - * @param [in] key Enryption key - * @param [in] usage Key usage (see KRB5_KEYUSAGE types) - * @param [in,out] cipher_state Initial vector; specify NULL if not needed - * @param [in] input Encrypted data - * @param [out] ouput Decrypted data + * @param [in] context Library context + * @param [in] key Encryption key + * @param [in] usage Key usage (see KRB5_KEYUSAGE types) + * @param [in,out] cipher_state Cipher state; specify NULL if not needed + * @param [in] input Encrypted data + * @param [out] output Decrypted data * - * This function decrypts the data block @a input and stores the output - * into @a output. The actual decryption key will derive from @a key if - * key derivation is permitted for the encryption algorithm. - * @a cipher_state specifies the starting value for the decryption operation, - * and is updated with the state to be passed as input to the next operation. + * This function decrypts the data block @a input and stores the output into @a + * output. The actual decryption key will be derived from @a key and @a usage + * if key derivation is specified for the encryption type. If non-null, @a + * cipher_state specifies the beginning state for the decryption operation, and + * is updated with the state to be passed as input to the next operation. * * @note The caller must initialize @a output and allocate at least enough - * space for the result. The usual practice is to allocate an output buffer - * as long as the ciphertext, and let krb5_c_decrypt() trim @a output->length. - * For some enctypes, the resulting output->length may include padding bytes - * (DES and DES3 enctypes do not have self-describing padding, so it is - * impossible to separate the plaintext from the padding based only on the - * ciphertext token). + * space for the result. The usual practice is to allocate an output buffer as + * long as the ciphertext, and let krb5_c_decrypt() trim @a output->length. + * For some enctypes, the resulting @a output->length may include padding + * bytes. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ - krb5_error_code KRB5_CALLCONV krb5_c_decrypt(krb5_context context, const krb5_keyblock *key, krb5_keyusage usage, const krb5_data *cipher_state, const krb5_enc_data *input, krb5_data *output); -/** Return encrypted data length. +/** + * Compute encrypted data length. * - * @param context Context structure - * @param [in] enctype Encryption type - * @param [in] inputlen Length of the data to be encrypted - * @param [out] length Length of the encrypted data + * @param [in] context Library context + * @param [in] enctype Encryption type + * @param [in] inputlen Length of the data to be encrypted + * @param [out] length Length of the encrypted data * * This function computes the length of the ciphertext produced by encrypting - * @a inputlen bytes and returns the length of the encrypted data including - * padding, confounder and checksum. + * @a inputlen bytes including padding, confounder, and checksum. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ - krb5_error_code KRB5_CALLCONV krb5_c_encrypt_length(krb5_context context, krb5_enctype enctype, size_t inputlen, size_t *length); -/** Return cipher block size. +/** + * Return cipher block size. * - * @param context Context structure - * @param [in] enctype Encryption algorithm + * @param [in] context Library context + * @param [in] enctype Encryption type * @param [out] blocksize Block size for @a enctype * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_block_size(krb5_context context, krb5_enctype enctype, size_t *blocksize); -/** Return length of the specified key in bytes. +/** + * Return length of the specified key in bytes. * - * @param context Context structure - * @param [in] enctype Encryption algorithm - * @param [out] keybytes Number of bytes required to make a key - * @param [out] keylength Length of final key + * @param [in] context Library context + * @param [in] enctype Encryption type + * @param [out] keybytes Number of bytes required to make a key + * @param [out] keylength Length of final key * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_keylengths(krb5_context context, krb5_enctype enctype, size_t *keybytes, size_t *keylength); -/** Initialize a new cipher state. +/** + * Initialize a new cipher state. * - * @param context Context structure - * @param [in] key Key - * @param [in] usage Key usage (see KRB5_KEYUSAGE types) - * @param [out] new_state New cipher state + * @param [in] context Library context + * @param [in] key Key + * @param [in] usage Key usage (see KRB5_KEYUSAGE types) + * @param [out] new_state New cipher state * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_init_state(krb5_context context, const krb5_keyblock *key, krb5_keyusage usage, krb5_data *new_state); -/** Free a cipher state previously allocated by krb5_c_init_state(). +/** + * Free a cipher state previously allocated by krb5_c_init_state(). * - * @param context Context structure - * @param [in] key Key - * @param [in] state Cipher state to be freed + * @param [in] context Library context + * @param [in] key Key + * @param [in] state Cipher state to be freed * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_free_state(krb5_context context, const krb5_keyblock *key, krb5_data *state); -/** Generate enctype-specific pseudo-random bytes. +/** + * Generate enctype-specific pseudo-random bytes. * - * @param context Context structure - * @param [in] keyblock Key - * @param [in] input Input data - * @param [out] output Output data + * @param [in] context Library context + * @param [in] keyblock Key + * @param [in] input Input data + * @param [out] output Output data * * This function selects a pseudo-random function based on @a keyblock and * computes its value over @a input, placing the result into @a output. * The caller must preinitialize @a output and allocate space for the * result, using krb5_c_prf_length() to determine the required length. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_prf(krb5_context context, const krb5_keyblock *keyblock, krb5_data *input, krb5_data *output); -/** Get the output length of pseudo-random functions for a given encryption type. +/** + * Get the output length of pseudo-random functions for an encryption type. * - * @param context Context structure - * @param [in] enctype Encryption type - * @param [out] len Number of bytes for @a enctype + * @param [in] context Library context + * @param [in] enctype Encryption type + * @param [out] len Length of PRF output * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_prf_length(krb5_context context, krb5_enctype enctype, size_t *len); -/** Returns KRB-FX-CF2 in a newly allocated keyblock. +/** + * Compute the KRB-FX-CF2 combination of two keys and pepper strings. * - * @param context Context structure - * @param [in] k1 KDC contribution key - * @param [in] pepper1 String "PKINIT" - * @param [in] k2 Reply key - * @param [in] pepper2 String "KeyExchange" - * @param [out] out Output key + * @param [in] context Library context + * @param [in] k1 KDC contribution key + * @param [in] pepper1 String "PKINIT" + * @param [in] k2 Reply key + * @param [in] pepper2 String "KeyExchange" + * @param [out] out Output key * - * This function is simple in that it assumes - * pepper1 and pepper2 are C strings with no - * internal nulls and that the enctype of the - * result will be the same as that of k1. Both - * of these assumptions are true of current - * specs. - * Note that @a k1 and @a k2 can be of two different enctypes. + * This function computes the KRB-FX-CF2 function over its inputs and places + * the results in a newly allocated keyblock. This function is simple in that + * it assumes that @a pepper1 and @a pepper2 are C strings with no internal + * nulls and that the enctype of the result will be the same as that of @a k1. + * @a k1 and @a k2 may be of different enctypes. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_fx_cf2_simple(krb5_context context, @@ -670,84 +678,89 @@ krb5_c_fx_cf2_simple(krb5_context context, krb5_keyblock *k2, const char *pepper2, krb5_keyblock **out); -/** Generate an enctype-specific random encryption key. +/** + * Generate an enctype-specific random encryption key. * - * @param context Context structure - * @param [in] enctype Encryption type of the generated key - * @param [out] k5_random_key An allocated and initialized keyblock + * @param [in] context Library context + * @param [in] enctype Encryption type of the generated key + * @param [out] k5_random_key An allocated and initialized keyblock * * Use krb5_free_keyblock_contents() to free @a k5_random_key when * no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_make_random_key(krb5_context context, krb5_enctype enctype, krb5_keyblock *k5_random_key); -/** Generate an enctype-specific key given random data. +/** + * Generate an enctype-specific key from random data. * - * @param context Context structure - * @param [in] enctype Encryption type - * @param [in] random_data Random input data - * @param [out] k5_random_key Random key + * @param [in] context Library context + * @param [in] enctype Encryption type + * @param [in] random_data Random input data + * @param [out] k5_random_key Resulting key * - * This function takes random input data @a random_data - * and produces a valid key @a k5_random_key for a given @a enctype. + * This function takes random input data @a random_data and produces a valid + * key @a k5_random_key for a given @a enctype. * - * @note It is assumed that @a k5_random_key has already been initialized and + * @note It is assumed that @a k5_random_key has already been initialized and * @a k5_random_key->contents has been allocated with the correct length. * - * @sa krb5_c_keylengths() + * @sa krb5_c_keylengths() * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_random_to_key(krb5_context context, krb5_enctype enctype, krb5_data *random_data, krb5_keyblock *k5_random_key); -/** Add entropy to the pseudo-random number generator. +/** + * Add entropy to the pseudo-random number generator. * - * @param context Context structure - * @param [in] randsource Entropy source - * @param [in] data Data + * @param [in] context Library context + * @param [in] randsource Entropy source (see KRB5_RANDSOURCE types) + * @param [in] data Data * - * @note This might cause the @c PRNG to be reseeded, - * although this is not guaranteed. + * Contribute entropy to the PRNG used by krb5 crypto operations. This may or + * may not affect the output of the next crypto operation requiring random + * data. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_random_add_entropy(krb5_context context, unsigned int randsource, const krb5_data *data); -/** Generate pseudo-random bytes. +/** + * Generate pseudo-random bytes. * - * @param context Context structure - * @param [out] data Random data + * @param [in] context Library context + * @param [out] data Random data * - * @a data->length specifies the number of bytes to generate and - * @a data->data points to an allocated buffer of the correct length. + * Fills in @a data with bytes from the PRNG used by krb5 crypto operations. + * The caller must preinitialize @a data and allocate the desired amount of + * space. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_random_make_octets(krb5_context context, krb5_data *data); -/** Collect entropy from the OS if possible. +/** + * Collect entropy from the OS if possible. * - * @param [in] context Context structure - * @param [in] strong Strongest available source of entropy - * @param [out] success 1 if OS provides entropy, 0 otherwise + * @param [in] context Library context + * @param [in] strong Strongest available source of entropy + * @param [out] success 1 if OS provides entropy, 0 otherwise * * If @a strong is non-zero, this function attempts to use the strongest - * available source of entropy. - * - * Setting @a strong may increase the probability of blocking and should not - * be used for normal applications. Good uses include seeding the PRNG for + * available source of entropy. Setting this flag may cause the function to + * block on some operating systems. Good uses include seeding the PRNG for * kadmind and realm setup. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_random_os_entropy(krb5_context context, int strong, int *success); @@ -756,41 +769,42 @@ krb5_c_random_os_entropy(krb5_context context, int strong, int *success); krb5_error_code KRB5_CALLCONV krb5_c_random_seed(krb5_context context, krb5_data *data); -/** Convert a given string to a key. +/** + * Convert a string (such a password) to a key. * - * @param context Context structure - * @param [in] enctype Encryption type - * @param [in] string String to be converted - * @param [in] salt Salt value - * @param [out] key Generated key + * @param [in] context Library context + * @param [in] enctype Encryption type + * @param [in] string String to be converted + * @param [in] salt Salt value + * @param [out] key Generated key * - * This function converts @a string to a @a key of encryption type - * @a enctype, using the specified @a salt. - * The newly created @a key must be released by calling - * krb5_free_keyblock_contents() when it is no longer needed. + * This function converts @a string to a @a key of encryption type @a enctype, + * using the specified @a salt. The newly created @a key must be released by + * calling krb5_free_keyblock_contents() when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_string_to_key(krb5_context context, krb5_enctype enctype, const krb5_data *string, const krb5_data *salt, krb5_keyblock *key); -/** Convert a given string to a key with additional parameters. - * - * @param context Context structure - * @param [in] enctype Encryption type - * @param [in] string String to be converted - * @param [in] salt Salt value - * @param [in] params Parameters - * @param [out] key Generated key - * - * This function is similar to krb5_c_string_to_key(), but takes - * additional parameters. - * The newly created @a key must be released by calling +/** + * Convert a string (such as a password) to a key with additional parameters. + * + * @param [in] context Library context + * @param [in] enctype Encryption type + * @param [in] string String to be converted + * @param [in] salt Salt value + * @param [in] params Parameters + * @param [out] key Generated key + * + * This function is similar to krb5_c_string_to_key(), but also takes + * parameters which may affect the algorithm in an enctype-dependent way. The + * newly created @a key must be released by calling * krb5_free_keyblock_contents() when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_string_to_key_with_params(krb5_context context, @@ -800,84 +814,98 @@ krb5_c_string_to_key_with_params(krb5_context context, const krb5_data *params, krb5_keyblock *key); -/** Compare two encryption types. +/** + * Compare two encryption types. * - * @param context Context structure - * @param [in] e1 First encryption type - * @param [in] e2 Second encryption type - * @param [out] similar @c TRUE if types are similar, @c FALSE - otherwise + * @param [in] context Library context + * @param [in] e1 First encryption type + * @param [in] e2 Second encryption type + * @param [out] similar @c TRUE if types are similar, @c FALSE if not * - * @retval 0 Success; Otherwise - Kerberos error codes + * This function determines whether two encryption types use the same kind of + * keys. + * + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_enctype_compare(krb5_context context, krb5_enctype e1, krb5_enctype e2, krb5_boolean *similar); -/** Compute a checksum. - * - * @param context Context structure - * @param [in] cksumtype Checksum type; If 0 - use the mandatory checksum. - * @param [in] key Encryption key for a keyed checksum - * @param [in] usage @a key usage - * @param [in] input Input data - * @param [out] cksum Generated checksum - * - * The newly created @a cksum must be released by calling +/** + * Compute a checksum. + * + * @param [in] context Library context + * @param [in] cksumtype Checksum type (0 for mandatory type) + * @param [in] key Encryption key for a keyed checksum + * @param [in] usage Key usage (see KRB5_KEYUSAGE types) + * @param [in] input Input data + * @param [out] cksum Generated checksum + * + * This function computes a checksum of type @a cksumtype over @a input, using + * @a key if the checksum type is a keyed checksum. If @a cksumtype is 0 and + * @a key is non-null, the checksum type will be the mandatory-to-implement + * checksum type for the key's encryption type. The actual checksum key will + * be derived from @a key and @a usage if key derivation is specified for the + * checksum type. The newly created @a cksum must be released by calling * krb5_free_checksum_contents() when it is no longer needed. * * @sa krb5_c_verify_checksum() * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_make_checksum(krb5_context context, krb5_cksumtype cksumtype, const krb5_keyblock *key, krb5_keyusage usage, const krb5_data *input, krb5_checksum *cksum); -/** Verify a checksum. +/** + * Verify a checksum. * - * @param context Context structure - * @param [in] key Encryption key for a keyed checksum - * @param [in] usage @a key usage - * @param [in] data Data to be used to compute a new checksum - * using @a key to compare @a cksum against - * @param [in] cksum Checksum to be verified - * @param [out] valid Non-zero for success, zero for failure + * @param [in] context Library context + * @param [in] key Encryption key for a keyed checksum + * @param [in] usage @a key usage + * @param [in] data Data to be used to compute a new checksum + * using @a key to compare @a cksum against + * @param [in] cksum Checksum to be verified + * @param [out] valid Non-zero for success, zero for failure * - * This function verifies that @a cksum is a valid checksum for - * @a data. If the checksum type of @a cksum is a keyed checksum, @a key - * and @a usage are used to verify the checksum. + * This function verifies that @a cksum is a valid checksum for @a data. If + * the checksum type of @a cksum is a keyed checksum, @a key is used to verify + * the checksum. The actual checksum key will be derived from @a key and @a + * usage if key derivation is specified for the checksum type. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_verify_checksum(krb5_context context, const krb5_keyblock *key, krb5_keyusage usage, const krb5_data *data, const krb5_checksum *cksum, krb5_boolean *valid); -/** Return a checksum length produced by the specified checksum type. +/** + * Return the length of checksums for a checksum type. * - * @param context Context structure - * @param [in] cksumtype Checksum type - * @param [out] length Checksum length + * @param [in] context Library context + * @param [in] cksumtype Checksum type + * @param [out] length Checksum length * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_checksum_length(krb5_context context, krb5_cksumtype cksumtype, size_t *length); -/** Get a list of checksum types that match a specified encryption type. +/** + * Return a list of keyed checksum types usable with an encryption type. * - * @param context Context structure - * @param [in] enctype Encryption type - * @param [out] count Count of checksums matching the encryption type - * @param [out] cksumtypes Array of checksum types with encryption key - * types supported by @a enctype + * @param [in] context Library context + * @param [in] enctype Encryption type + * @param [out] count Count of allowable checksum types + * @param [out] cksumtypes Array of allowable checksum types * - * Use krb5_free_cksumtypes() to free @a cksumtypes when it is no longer needed. + * Use krb5_free_cksumtypes() to free @a cksumtypes when it is no longer + * needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_c_keyed_checksum_types(krb5_context context, krb5_enctype enctype, @@ -921,7 +949,6 @@ krb5_c_keyed_checksum_types(krb5_context context, krb5_enctype enctype, /** * @note There is a conflict with the value of @c KRB5_KEYUSAGE_PA_REFERRAL: * it is used for hardware Pre-athentication @a and KDC referrals. - * */ #define KRB5_KEYUSAGE_PA_REFERRAL 26 /* XXX note conflict with above */ @@ -941,44 +968,43 @@ krb5_c_keyed_checksum_types(krb5_context context, krb5_enctype enctype, #define KRB5_KEYUSAGE_ENC_CHALLENGE_KDC 55 #define KRB5_KEYUSAGE_AS_REQ 56 -/** Verify that a specified encryption type is a valid Kerberos encryption type. +/** + * Verify that a specified encryption type is a valid Kerberos encryption type. * - * @param [in] ktype Encryption type + * @param [in] ktype Encryption type * - * @retval - * 0 - invalid; 1 - valid + * @return @c TRUE if @a ktype is valid, @c FALSE if not */ krb5_boolean KRB5_CALLCONV krb5_c_valid_enctype(krb5_enctype ktype); -/** Verify that specified checksum type is a valid Kerberos checksum type. - * - * @param ctype Checksum type [input] +/** + * Verify that specified checksum type is a valid Kerberos checksum type. * - * @retval - * 0 - invalid; 1 - valid + * @param [in] ctype Checksum type * + * @return @c TRUE if @a ctype is valid, @c FALSE if not */ krb5_boolean KRB5_CALLCONV krb5_c_valid_cksumtype(krb5_cksumtype ctype); -/** Test whether a checksum type is collision-proof. +/** + * Test whether a checksum type is collision-proof. * - * @param [in] ctype Checksum type + * @param [in] ctype Checksum type * - * @retval - * 0 Not collision-proof, or checksum type is not in the list; Otherwise - 1. + * @return @c TRUE if @a ctype is collision-proof, @c FALSE if it is not + * collision-proof or not a valid checksum type. */ krb5_boolean KRB5_CALLCONV krb5_c_is_coll_proof_cksum(krb5_cksumtype ctype); -/** Test whether a checksum type is keyed. +/** + * Test whether a checksum type is keyed. * - * @param [in] ctype Checksum type + * @param [in] ctype Checksum type * - * @retval - * 0 Checksum does not use derived keys, or checksum type is not in the list; - * Otherwise - 1. + * @return @c TRUE if @a ctype is a keyed checksum type, @c FALSE otherwise. */ krb5_boolean KRB5_CALLCONV krb5_c_is_keyed_cksum(krb5_cksumtype ctype); @@ -1030,9 +1056,7 @@ krb5_error_code KRB5_CALLCONV krb5_k_create_key(krb5_context context, const krb5_keyblock *key_data, krb5_key *out); -/** - * Keys are logically immutable and can be "copied" by reference count. - */ +/** Increment the reference count on a key. */ void KRB5_CALLCONV krb5_k_reference_key(krb5_context context, krb5_key key); @@ -1040,12 +1064,12 @@ krb5_k_reference_key(krb5_context context, krb5_key key); void KRB5_CALLCONV krb5_k_free_key(krb5_context context, krb5_key key); -/** Retrieve a copy of the keyblock from a krb5_key structure. */ +/** Retrieve a copy of the keyblock from a krb5_key structure. */ krb5_error_code KRB5_CALLCONV krb5_k_key_keyblock(krb5_context context, krb5_key key, krb5_keyblock **key_data); -/** Retrieve the enctype of a krb5_key structure. */ +/** Retrieve the enctype of a krb5_key structure. */ krb5_enctype KRB5_CALLCONV krb5_k_key_enctype(krb5_context context, krb5_key key); @@ -1236,7 +1260,8 @@ krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype, #define AP_OPTS_ETYPE_NEGOTIATION 0x00000002 #define AP_OPTS_USE_SUBKEY 0x00000001 /**< Generate a subsession key from the current session key - obtained from the credentials */ + obtained from the + credentials */ /* #define AP_OPTS_RESERVED 0x10000000 */ /* #define AP_OPTS_RESERVED 0x08000000 */ /* #define AP_OPTS_RESERVED 0x04000000 */ @@ -1332,16 +1357,16 @@ krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype, /* Message types */ -#define KRB5_AS_REQ ((krb5_msgtype)10) /**< Req for initial authentication */ -#define KRB5_AS_REP ((krb5_msgtype)11) /**< Response to KRB_AS_REQ request */ -#define KRB5_TGS_REQ ((krb5_msgtype)12) /**< TGS request to server */ -#define KRB5_TGS_REP ((krb5_msgtype)13) /**< Response to KRB_TGS_REQ req */ -#define KRB5_AP_REQ ((krb5_msgtype)14) /**< application request to server */ -#define KRB5_AP_REP ((krb5_msgtype)15) /**< Response to KRB_AP_REQ_MUTUAL */ -#define KRB5_SAFE ((krb5_msgtype)20) /**< Safe application message */ -#define KRB5_PRIV ((krb5_msgtype)21) /**< Private application message */ -#define KRB5_CRED ((krb5_msgtype)22) /**< Credential forwarding message */ -#define KRB5_ERROR ((krb5_msgtype)30) /**< Error response */ +#define KRB5_AS_REQ ((krb5_msgtype)10) /**< Initial authentication request */ +#define KRB5_AS_REP ((krb5_msgtype)11) /**< Response to AS request */ +#define KRB5_TGS_REQ ((krb5_msgtype)12) /**< Ticket granting server request */ +#define KRB5_TGS_REP ((krb5_msgtype)13) /**< Response to TGS request */ +#define KRB5_AP_REQ ((krb5_msgtype)14) /**< Auth req to application server */ +#define KRB5_AP_REP ((krb5_msgtype)15) /**< Response to mutual AP request */ +#define KRB5_SAFE ((krb5_msgtype)20) /**< Safe application message */ +#define KRB5_PRIV ((krb5_msgtype)21) /**< Private application message */ +#define KRB5_CRED ((krb5_msgtype)22) /**< Cred forwarding message */ +#define KRB5_ERROR ((krb5_msgtype)30) /**< Error response */ /* LastReq types */ #define KRB5_LRQ_NONE 0 @@ -1481,8 +1506,8 @@ typedef struct _krb5_enc_tkt_part { /** * Ticket structure. * - * Ticket structure that holds the C representation of the ticket protocol - * message and a pointer to the representation of @c _krb5_enc_tkt_part. + * The C representation of the ticket message, with a pointer to the + * C representation of the encrypted part. */ typedef struct _krb5_ticket { krb5_magic magic; @@ -1496,7 +1521,7 @@ typedef struct _krb5_ticket { /** * Ticket authenticator. * - * Ticket authenticator: the @c c representation of @c AP-REQ message with decrypted authenticator. + * The C representation of an unencrypted authenticator. */ typedef struct _krb5_authenticator { krb5_magic magic; @@ -1506,7 +1531,7 @@ typedef struct _krb5_authenticator { krb5_timestamp ctime; /**< client sec portion */ krb5_keyblock *subkey; /**< true session key, optional */ krb5_ui_4 seq_number; /**< sequence #, optional */ - krb5_authdata **authorization_data; /**< New add by Ari, auth data */ + krb5_authdata **authorization_data; /**< authoriazation data */ } krb5_authenticator; /* @@ -1540,130 +1565,131 @@ typedef struct _krb5_creds { /** Last request entry */ typedef struct _krb5_last_req_entry { krb5_magic magic; - krb5_int32 lr_type; /**< LR type */ - krb5_timestamp value; /**< Timestamp */ + krb5_int32 lr_type; /**< LR type */ + krb5_timestamp value; /**< Timestamp */ } krb5_last_req_entry; /** Pre-authentication data */ typedef struct _krb5_pa_data { krb5_magic magic; - krb5_preauthtype pa_type; /**< Preauthentication data type */ - unsigned int length; /**< Length of data */ - krb5_octet *contents; /**< Data */ + krb5_preauthtype pa_type; /**< Preauthentication data type */ + unsigned int length; /**< Length of data */ + krb5_octet *contents; /**< Data */ } krb5_pa_data; -/** Typed data. - * - * The FAST error handling logic currently assumes that this structure and - * krb5_pa_data * can be safely cast to each other if this structure changes, - * that code needs to be updated to copy. +/* + * The FAST error handling logic currently assumes that pointers to this + * structure and krb5_pa_data can be safely cast to each other. If this + * structure changes, that code needs to be updated to copy. */ +/** Typed data */ typedef struct _krb5_typed_data { krb5_magic magic; - krb5_int32 type; + krb5_int32 type; unsigned int length; krb5_octet *data; } krb5_typed_data; -/** Representation of KDC-REQ protocol message. */ +/** C representation of KDC-REQ protocol message, including KDC-REQ-BODY */ typedef struct _krb5_kdc_req { krb5_magic magic; - krb5_msgtype msg_type; /**< krb5_kdc_req AS_REQ or TGS_REQ? */ - krb5_pa_data **padata; /**< krb5_kdc_req e.g. encoded AP_REQ */ + krb5_msgtype msg_type; /**< KRB5_AS_REQ or KRB5_TGS_REQ */ + krb5_pa_data **padata; /**< Preauthentication data */ /* real body */ - krb5_flags kdc_options; /**< requested options */ - krb5_principal client; /**< includes realm; optional */ - krb5_principal server; /**< includes realm (only used if no client) */ - krb5_timestamp from; /**< requested starttime */ - krb5_timestamp till; /**< requested endtime */ - krb5_timestamp rtime; /**< (optional) requested renew_till */ - krb5_int32 nonce; /**< nonce to match request/response */ - int nktypes; /**< # of ktypes, must be positive */ - krb5_enctype *ktype; /**< requested enctype(s) */ - krb5_address **addresses; /**< requested addresses, optional */ - krb5_enc_data authorization_data; /**< encrypted auth data; OPTIONAL */ - krb5_authdata **unenc_authdata; /**< unencrypted auth data, if available */ - krb5_ticket **second_ticket;/**< second ticket array; OPTIONAL */ - /** the following field is added in March 2009; it is a hack so - * that FAST state can be carried to pre-authentication plugins. - * A new plugin interface may be a better long-term approach. It - * is believed to be safe to extend this structure because it is - * not found in any public APIs. + krb5_flags kdc_options; /**< Requested options */ + krb5_principal client; /**< Client principal and realm */ + krb5_principal server; /**< Server principal and realm */ + krb5_timestamp from; /**< Requested start time */ + krb5_timestamp till; /**< Requested end time */ + krb5_timestamp rtime; /**< Requested renewable end time */ + krb5_int32 nonce; /**< Nonce to match request andresponse */ + int nktypes; /**< Number of enctypes */ + krb5_enctype *ktype; /**< Requested enctypes */ + krb5_address **addresses; /**< Requested addresses (optional) */ + krb5_enc_data authorization_data; /**< Encrypted authz data (optional) */ + krb5_authdata **unenc_authdata; /**< Unencrypted authz data */ + krb5_ticket **second_ticket; /**< Second ticket array (optional) */ + /* + * The following field is added in March 2009; it is a hack so that FAST + * state can be carried to pre-authentication plugins. A new plugin + * interface may be a better long-term approach. It is believed to be safe + * to extend this structure because it is not found in any public APIs. */ - void * kdc_state; + void *kdc_state; } krb5_kdc_req; -/** Representation of @c EncKDCRepPart protocol message. +/** + * C representation of @c EncKDCRepPart protocol message. * * This is the cleartext message that is encrypted and inserted in @c KDC-REP. */ - typedef struct _krb5_enc_kdc_rep_part { krb5_magic magic; /* encrypted part: */ - krb5_msgtype msg_type; /**< krb5 message type */ - krb5_keyblock *session; /**< session key */ - krb5_last_req_entry **last_req; /**< array of ptrs to entries */ - krb5_int32 nonce; /**< nonce from request */ - krb5_timestamp key_exp; /**< expiration date */ - krb5_flags flags; /**< ticket flags */ - krb5_ticket_times times; /**< lifetime info */ - krb5_principal server; /**< server's principal identifier */ - krb5_address **caddrs; /**< array of ptrs to addresses, optional */ - krb5_pa_data **enc_padata; /**< Windows 2000 compat */ + krb5_msgtype msg_type; /**< krb5 message type */ + krb5_keyblock *session; /**< Session key */ + krb5_last_req_entry **last_req; /**< Array of pointers to entries */ + krb5_int32 nonce; /**< Nonce from request */ + krb5_timestamp key_exp; /**< Expiration date */ + krb5_flags flags; /**< Ticket flags */ + krb5_ticket_times times; /**< Lifetime info */ + krb5_principal server; /**< Server's principal identifier */ + krb5_address **caddrs; /**< Array of ptrs to addrs, optional */ + krb5_pa_data **enc_padata; /**< Encrypted preauthentication data */ } krb5_enc_kdc_rep_part; -/** Representation of the @c KDC-REP protocol message. */ +/** Representation of the @c KDC-REP protocol message. */ typedef struct _krb5_kdc_rep { krb5_magic magic; /* cleartext part: */ - krb5_msgtype msg_type; /**< AS_REP or KDC_REP? */ - krb5_pa_data **padata; /**< preauthentication data from KDC */ - krb5_principal client; /**< client's principal identifier */ - krb5_ticket *ticket; /**< ticket */ - krb5_enc_data enc_part; /**< encryption type, kvno, encrypted encoding */ - krb5_enc_kdc_rep_part *enc_part2; /**< unencrypted version, if available */ + krb5_msgtype msg_type; /**< KRB5_AS_REP or KRB5_KDC_REP */ + krb5_pa_data **padata; /**< Preauthentication data from KDC */ + krb5_principal client; /**< Client principal and realm */ + krb5_ticket *ticket; /**< Ticket */ + krb5_enc_data enc_part; /**< Encrypted part of reply */ + krb5_enc_kdc_rep_part *enc_part2; /**< Unencrypted version, if available */ } krb5_kdc_rep; /** Error message structure */ typedef struct _krb5_error { krb5_magic magic; /* some of these may be meaningless in certain contexts */ - krb5_timestamp ctime; /**< client sec portion; optional */ - krb5_int32 cusec; /**< client usec portion; optional */ - krb5_int32 susec; /**< server usec portion */ - krb5_timestamp stime; /**< server sec portion */ - krb5_ui_4 error; /**< error code (protocol error #'s) */ - krb5_principal client; /**< client's principal identifier; optional */ - krb5_principal server; /**< server's principal identifier */ - krb5_data text; /**< descriptive text */ - krb5_data e_data; /**< additional error-describing data */ + krb5_timestamp ctime; /**< Client sec portion; optional */ + krb5_int32 cusec; /**< Client usec portion; optional */ + krb5_int32 susec; /**< Server usec portion */ + krb5_timestamp stime; /**< Server sec portion */ + krb5_ui_4 error; /**< Error code (protocol error #'s) */ + krb5_principal client; /**< Client principal and realm */ + krb5_principal server; /**< Server principal and realm */ + krb5_data text; /**< Descriptive text */ + krb5_data e_data; /**< Additional error-describing data */ } krb5_error; /** Authentication header. */ typedef struct _krb5_ap_req { krb5_magic magic; - krb5_flags ap_options; /**< requested options */ - krb5_ticket *ticket; /**< ticket */ - krb5_enc_data authenticator; /**< authenticator (already encrypted) */ + krb5_flags ap_options; /**< Requested options */ + krb5_ticket *ticket; /**< Ticket */ + krb5_enc_data authenticator; /**< Encrypted authenticator */ } krb5_ap_req; -/** C representaton of AP-REP message. +/** + * C representaton of AP-REP message. * * The server's response to a client's request for mutual authentication. */ typedef struct _krb5_ap_rep { krb5_magic magic; - krb5_enc_data enc_part; /**< Ciphertext of ApRepEncPart */ + krb5_enc_data enc_part; /**< Ciphertext of ApRepEncPart */ } krb5_ap_rep; /** Cleartext that is encrypted and put into @c _krb5_ap_rep. */ typedef struct _krb5_ap_rep_enc_part { krb5_magic magic; - krb5_timestamp ctime; /**< client time, seconds portion */ - krb5_int32 cusec; /**< client time, microseconds portion */ - krb5_keyblock *subkey; /**< true session key, optional */ - krb5_ui_4 seq_number; /**< sequence #, optional */ + krb5_timestamp ctime; /**< Client time, seconds portion */ + krb5_int32 cusec; /**< Client time, microseconds portion */ + krb5_keyblock *subkey; /**< Subkey (optional) */ + krb5_ui_4 seq_number; /**< Sequence number */ } krb5_ap_rep_enc_part; /* Unused */ @@ -1671,38 +1697,38 @@ typedef struct _krb5_response { krb5_magic magic; krb5_octet message_type; krb5_data response; - krb5_int32 expected_nonce; /**< The expected nonce for KDC_REP messages */ - krb5_timestamp request_time; /**< When we made the request */ + krb5_int32 expected_nonce; + krb5_timestamp request_time; } krb5_response; /** Credentials information inserted into @c EncKrbCredPart. */ typedef struct _krb5_cred_info { krb5_magic magic; - krb5_keyblock *session; /**< session key used to encrypt ticket */ - krb5_principal client; /**< client name/realm, optional */ - krb5_principal server; /**< server name/realm, optional */ - krb5_flags flags; /**< ticket flags, optional */ - krb5_ticket_times times; /**< auth, start, end, renew_till, optional */ - krb5_address **caddrs; /**< array of ptrs to addresses */ + krb5_keyblock *session; /**< Session key used to encrypt ticket */ + krb5_principal client; /**< Client principal and realm */ + krb5_principal server; /**< Server principal and realm */ + krb5_flags flags; /**< Ticket flags */ + krb5_ticket_times times; /**< Auth, start, end, renew_till */ + krb5_address **caddrs; /**< Array of pointers to addrs (optional) */ } krb5_cred_info; /** Cleartext credentials information. */ typedef struct _krb5_cred_enc_part { krb5_magic magic; - krb5_int32 nonce; /**< nonce, optional */ - krb5_timestamp timestamp; /**< client time */ - krb5_int32 usec; /**< microsecond portion of time */ - krb5_address *s_address; /**< sender address, optional */ - krb5_address *r_address; /**< recipient address, optional */ + krb5_int32 nonce; /**< Nonce (optional) */ + krb5_timestamp timestamp; /**< Generation time, seconds portion */ + krb5_int32 usec; /**< Generation time, microseconds portion */ + krb5_address *s_address; /**< Sender address (optional) */ + krb5_address *r_address; /**< Recipient address (optional) */ krb5_cred_info **ticket_info; } krb5_cred_enc_part; /** Credentials data structure.*/ typedef struct _krb5_cred { krb5_magic magic; - krb5_ticket **tickets; /**< tickets */ - krb5_enc_data enc_part; /**< encrypted part */ - krb5_cred_enc_part *enc_part2; /**< unencrypted version, if available*/ + krb5_ticket **tickets; /**< Tickets */ + krb5_enc_data enc_part; /**< Encrypted part */ + krb5_cred_enc_part *enc_part2; /**< Unencrypted version, if available */ } krb5_cred; /* @@ -1759,22 +1785,28 @@ typedef struct _krb5_pa_pac_req { #define KRB5_AUTH_CONTEXT_PERMIT_ALL 0x00000010 #define KRB5_AUTH_CONTEXT_USE_SUBKEY 0x00000020 -/** Replay data. +/** + * Replay data. * - * Sequence number and timestamp information output by krb5_read_priv() and - * krb5_read_safe(). + * Sequence number and timestamp information output by krb5_rd_priv() and + * krb5_rd_safe(). */ typedef struct krb5_replay_data { - krb5_timestamp timestamp; /**< Timestamp, seconds portion */ - krb5_int32 usec; /**< Timestamp, microseconds portion */ - krb5_ui_4 seq; /**< Sequence number */ + krb5_timestamp timestamp; /**< Timestamp, seconds portion */ + krb5_int32 usec; /**< Timestamp, microseconds portion */ + krb5_ui_4 seq; /**< Sequence number */ } krb5_replay_data; -/* flags for krb5_auth_con_genaddrs() */ -#define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR 0x00000001 /**< Generate the local network address */ -#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR 0x00000002 /**< Generate the remote network address. */ -#define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR 0x00000004 /**< Generate the local network address and the local port. */ -#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR 0x00000008 /**< Generate the remote network address and the remote port */ +/* Flags for krb5_auth_con_genaddrs(). */ + +/** Generate the local network address. */ +#define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR 0x00000001 +/** Generate the remote network address. */ +#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR 0x00000002 +/** Generate the local network address and the local port. */ +#define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR 0x00000004 +/** Generate the remote network address and the remote port. */ +#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR 0x00000008 /* type of function used as a callback to generate checksum data for * mk_req */ @@ -1803,34 +1835,43 @@ typedef struct _krb5_cc_ops krb5_cc_ops; struct _krb5_cccol_cursor; typedef struct _krb5_cccol_cursor *krb5_cccol_cursor; -/* for retrieve_cred */ -#define KRB5_TC_MATCH_TIMES 0x00000001 /**< The requested lifetime must be - at least as great as that specified */ -#define KRB5_TC_MATCH_IS_SKEY 0x00000002 /**< The is_skey field must match exactly */ -#define KRB5_TC_MATCH_FLAGS 0x00000004 /**< All the flags set in the match credentials - must be set in the cache credentials */ -#define KRB5_TC_MATCH_TIMES_EXACT 0x00000008 /**< All the time fields must match exactly */ -#define KRB5_TC_MATCH_FLAGS_EXACT 0x00000010 /**< All the flags must match exactly */ -#define KRB5_TC_MATCH_AUTHDATA 0x00000020 /**< The authorization data must match */ -#define KRB5_TC_MATCH_SRV_NAMEONLY 0x00000040 /**< Only the name portion - of the principal name must match */ -#define KRB5_TC_MATCH_2ND_TKT 0x00000080 /**< The second ticket must match */ -#define KRB5_TC_MATCH_KTYPE 0x00000100 /**< The encryption key type must match */ -#define KRB5_TC_SUPPORTED_KTYPES 0x00000200 /**< The supported key types must match */ - -/* for set_flags and other functions */ -#define KRB5_TC_OPENCLOSE 0x00000001 /**< Open and close the cache each time a - credentials cache routine is called */ +/* Flags for krb5_cc_retrieve_cred. */ +/** The requested lifetime must be at least as great as the time specified. */ +#define KRB5_TC_MATCH_TIMES 0x00000001 +/** The is_skey field must match exactly. */ +#define KRB5_TC_MATCH_IS_SKEY 0x00000002 +/** All the flags set in the match credentials must be set. */ +#define KRB5_TC_MATCH_FLAGS 0x00000004 +/** All the time fields must match exactly. */ +#define KRB5_TC_MATCH_TIMES_EXACT 0x00000008 +/** All the flags must match exactly. */ +#define KRB5_TC_MATCH_FLAGS_EXACT 0x00000010 +/** The authorization data must match. */ +#define KRB5_TC_MATCH_AUTHDATA 0x00000020 +/** Only the name portion of the principal name must match. */ +#define KRB5_TC_MATCH_SRV_NAMEONLY 0x00000040 +/** The second ticket must match. */ +#define KRB5_TC_MATCH_2ND_TKT 0x00000080 +/** The encryption key type must match. */ +#define KRB5_TC_MATCH_KTYPE 0x00000100 +/** The supported key types must match. */ +#define KRB5_TC_SUPPORTED_KTYPES 0x00000200 + +/* Flags for krb5_cc_set_flags and similar. */ +/** Open and close the file for each cache operation. */ +#define KRB5_TC_OPENCLOSE 0x00000001 #define KRB5_TC_NOTICKET 0x00000002 -/** Retrieve the name but not type of a credential cache. +/** + * Retrieve the name but not type of a credential cache. * - * @param [in] context Context structure - * @param [in] cache Credentials cache handle + * @param [in] context Library context + * @param [in] cache Credential cache handle * - * @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(). + * @warning Returns the name of the credential cache. The result is an alias + * into @a cache and should not be freed or modified by the caller. This name + * does not include the cache type, so should not be used as input to + * krb5_cc_resolve(). * * @return * On success - the name of the credential cache. @@ -1839,33 +1880,19 @@ const char * KRB5_CALLCONV krb5_cc_get_name(krb5_context context, krb5_ccache cache); #if KRB5_DEPRECATED -/** Generate a new handle for a specified (unopened) credentials cache. - * - * @param [in] context Context structure - * @param [in,out] cache Credentials cache handle - * - * @deprecated Replaced by krb5_cc_new_unique() - * - * This function generate a new credential chache whose name is guaranteed to be unique. - * - * @note In the case the credential file, the cache stays unopen, but the new filename is reserved. - * - * @retval 0 Success; Otherwise - Kerberos error codes - */ krb5_error_code KRB5_CALLCONV krb5_cc_gen_new(krb5_context context, krb5_ccache *cache); #endif /* KRB5_DEPRECATED */ -/** Initialize credentials cache. - * - * @param [in] context Context structure - * @param [in] cache Credentials cache handle - * @param [in] principal Default principal name for the credentials cache +/** + * Initialize a credential cache. * - * Destroy an existing credentials cache and create a new credentials cache - * by the same name, as specifed by @a cache for specified @a principal. + * @param [in] context Library context + * @param [in] cache Credential cache handle + * @param [in] principal Default principal name * - * @note This function also modifies the specified credentials cache. + * Destroy any existing contents of @a cache and initialize it for the default + * principal @a principal. * * @retval * 0 Success @@ -1876,17 +1903,14 @@ krb5_error_code KRB5_CALLCONV krb5_cc_initialize(krb5_context context, krb5_ccache cache, krb5_principal principal); -/** Destroy a credentials cache. - * - * @param [in] context Context structure - * @param [in] cache Credentials cache handle +/** + * Destroy a credential 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. + * @param [in] context Library context + * @param [in] cache Credential cache handle * - * @note After completion, @a cache may not be used. It may be reinitialized - * with krb5_cc_resolve() or krb5_cc_gen_new(). + * This function destroys any existing contents of @a cache and closes the + * handle to it. * * @retval * 0 Success @@ -1896,14 +1920,14 @@ krb5_cc_initialize(krb5_context context, krb5_ccache cache, krb5_error_code KRB5_CALLCONV krb5_cc_destroy(krb5_context context, krb5_ccache cache); -/** Close a credentials cache and invalidate its handle. - * - * @param [in] context Context structure - * @param [in] cache Credentials cache handle +/** + * Close a credential cache handle. * - * @a cache may be reinitialized with krb5_cc_resolve() or krb5_cc_gen_new(). + * @param [in] context Library context + * @param [in] cache Credential cache handle * - * @sa KRB5_TC_OPENCLOSE flag + * This function closes a credential cache handle @a cache without affecting + * the contents of the cache. * * @retval * 0 Success @@ -1913,69 +1937,72 @@ krb5_cc_destroy(krb5_context context, krb5_ccache cache); krb5_error_code KRB5_CALLCONV krb5_cc_close(krb5_context context, krb5_ccache cache); -/** Store credentials in a specified credentials cache. +/** + * Store credentials in a credential cache. * - * @param [in] context Context structure - * @param [in,out] cache Credentials cache handle - * @param [in] creds Credentials to be stored in cache + * @param [in] context Library context + * @param [in,out] cache Credential cache handle + * @param [in] creds Credentials to be stored in cache * - * This function stores @a creds into @a cache. - * If @a creds->server and the server in the decoded ticket @a creds->ticket - * differ, both principals will be stored. + * This function stores @a creds into @a cache. If @a creds->server and the + * server in the decoded ticket @a creds->ticket differ, the credentials will + * be stored under both server principal names. * * @retval * 0 Success - * @return Permission errors; Storage failure errors; Kerberos error codes + * @return Permission errors; storage failure errors; Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cc_store_cred(krb5_context context, krb5_ccache cache, krb5_creds *creds); -/** Retrieve a specified credentials from a credentials cache. +/** + * Retrieve a specified credentials from a credential cache. * - * @param [in] context Context structure - * @param [in] cache Credentials cache handle - * @param [in] flags Flags bit mask - * @param [in] mcreds Credentials to match - * @param [out] creds Credentials that match the requested value + * @param [in] context Library context + * @param [in] cache Credential cache handle + * @param [in] flags Flags bit mask + * @param [in] mcreds Credentials to match + * @param [out] creds Credentials matching the requested value * - * This function searches a credentials cache for credentials matching @a mcreds + * This function searches a credential cache for credentials matching @a mcreds * and returns it if found. * * Valid values for @a flags are: * - * @li @c KRB5_TC_MATCH_TIMES The requested lifetime must be - * at least as great as that specified. + * @li @c KRB5_TC_MATCH_TIMES The requested lifetime must be at least as + * great as in @a mcreds . * @li @c KRB5_TC_MATCH_IS_SKEY The @a is_skey field much match exactly. - * @li @c KRB5_TC_MATCH_FLAGS The flags in @a mcreds and @a creds must match + * @li @c KRB5_TC_MATCH_FLAGS Flags set in @a mcreds must be set. * @li @c KRB5_TC_MATCH_TIMES_EXACT The requested lifetime must match exactly. - * @li @c KRB5_TC_MATCH_FLAGS_EXACT Flags in @a mcreds and @a creds must match exactly. + * @li @c KRB5_TC_MATCH_FLAGS_EXACT Flags must match exactly. * @li @c KRB5_TC_MATCH_AUTHDATA The authorization data must match. - * @li @c KRB5_TC_MATCH_SRV_NAMEONLY Only the name portion of the principal name must - * match. The realm field can be different. - * If this flag is not set, the entire principal - * name must match. + * @li @c KRB5_TC_MATCH_SRV_NAMEONLY Only the name portion of the principal + * name must match, not the realm. * @li @c KRB5_TC_MATCH_2ND_TKT The second tickets must match. * @li @c KRB5_TC_MATCH_KTYPE The encryption key types must match. - * @li @c KRB5_TC_MATCH_SUPPORTED_KTYPES Check all matching entries that have any supported - * encryption type and return the one with the encryption + * @li @c KRB5_TC_MATCH_SUPPORTED_KTYPES Check all matching entries that have + * any supported encryption type and + * return the one with the encryption * type listed earliest. * * Use krb5_free_cred_contents() to free @a creds when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cc_retrieve_cred(krb5_context context, krb5_ccache cache, krb5_flags flags, krb5_creds *mcreds, krb5_creds *creds); -/** Get the primary principal of a credentials cache. +/** + * Get the default principal of a credential cache. * - * @param [in] context Context structure - * @param [in] cache Credentials cache handle - * @param [out] principal Primary principal + * @param [in] context Library context + * @param [in] cache Credential cache handle + * @param [out] principal Primary principal * - * @note The primary principal is set by calling krb5_cc_initialize(). + * Returns the default client principal of a credential cache as set by + * krb5_cc_initialize(). * * Use krb5_free_principal() to free @a principal when it is no longer needed. * @@ -1988,52 +2015,56 @@ krb5_error_code KRB5_CALLCONV krb5_cc_get_principal(krb5_context context, krb5_ccache cache, krb5_principal *principal); -/** Prepare to sequentially read every credential in a credentials cache. +/** + * Prepare to sequentially read every credential in a credential cache. * - * @param [in] context Context structure - * @param [in] cache Credentials cache handle - * @param [out] cursor Cursor + * @param [in] context Library context + * @param [in] cache Credential cache handle + * @param [out] cursor Cursor * - * krb5_cc_end_seq_get() must be called to complete the retreive operation. + * krb5_cc_end_seq_get() must be called to complete the retrieve operation. * - * @note If @a cache was modified between the time of the call to this function + * @note If @a cache is modified between the time of the call to this function * and the time of the final krb5_cc_end_seq_get(), the results are undefined. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cc_start_seq_get(krb5_context context, krb5_ccache cache, krb5_cc_cursor *cursor); -/** Retrieve the next entry from the credentials cache. +/** + * Retrieve the next entry from the credential cache. * - * @param [in] context Context structure - * @param [in] cache Credentials cache handle - * @param [in,out] cursor Cursor - * @param [out] creds Credentials cache entry corresponding to the cursor + * @param [in] context Library context + * @param [in] cache Credential cache handle + * @param [in,out] cursor Cursor + * @param [out] creds Next credential cache entry * - * @note The cursor value is updated upon successful completion of this function. - * Subsequent calls to krb5_cc_next_cred() use the updated value. + * This function fills in @a creds with the next entry in @a cache and advances + * @a cursor. * * Use krb5_free_cred_contents() to free @a creds when it is no longer needed. * * @sa krb5_cc_start_seq_get(), krb5_end_seq_get() * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cc_next_cred(krb5_context context, krb5_ccache cache, krb5_cc_cursor *cursor, krb5_creds *creds); -/** Finish a series of sequential processing credentials cache entries. +/** + * Finish a series of sequential processing credential cache entries. * - * @param [in] context Context structure - * @param [in] cache Credentials cache handle - * @param [in,out] cursor Cursor that was created by krb5_cc_start_seq_get() + * @param [in] context Library context + * @param [in] cache Credential cache handle + * @param [in,out] cursor Cursor * - * This function finishes processing credentials cache entries and invalidates @a cursor. + * This function finishes processing credential cache entries and invalidates + * @a cursor. * - * @sa krb5_cc_next_cred() + * @sa krb5_cc_start_seq_get(), krb5_cc_next_cred() * * @retval 0 (always) */ @@ -2041,101 +2072,89 @@ krb5_error_code KRB5_CALLCONV krb5_cc_end_seq_get(krb5_context context, krb5_ccache cache, krb5_cc_cursor *cursor); -/** Remove credentials from a credentials cache. - * - * @param [in] context Context structure - * @param [in] cache Credentials cache handle - * @param [in] flags Bitwise-ORed search flags - * @param [in] creds Credentials to be matched - * - * @warning This function is not implemented on UNIX'es. Returns KRB5_CC_NOSUPP. - * - * Valid values for search flags are: - * @li @c KRB5_TC_MATCH_TIMES The requested lifetime is required to be at least - * as great as that specified. - * @li @c KRB5_TC_MATCH_IS_SKEY The @a is_skey field much match exactly. - * @li @c KRB5_TC_MATCH_FLAGS The set bits in @a mcreds must match in @a creds. - * @li @c KRB5_TC_MATCH_TIMES_EXACT The requested lifetime must match exactly. - * @li @c KRB5_TC_MATCH_FLAGS_EXACT All bits in @a mcreds must match exactly. - * @li @c KRB5_TC_MATCH_AUTHDATA The authentication data must match. - * @li @c KRB5_TC_MATCH_SRV_NAMEONLY Only the name portion of the principal name must match. - * The realm field can be different. By default, - * the entire principal name must match. - * @li @c KRB5_TC_MATCH_2ND_TKT The second tickets must match. - * @li @c KRB5_TC_MATCH_KTYPE The encryption key types must match. - * @li @c KRB5_TC_MATCH_SUPPORTED_KTYPES Check all matching entries that have - * any supported encryption type. +/** + * Remove credentials from a credential cache. * + * @param [in] context Library context + * @param [in] cache Credential cache handle + * @param [in] flags Bitwise-ORed search flags + * @param [in] creds Credentials to be matched + * + * @warning This function is not implemented for some cache types. + * + * This function accepts the same flag values as krb5_cc_retrieve_cred(). + * + * @retval KRB5_CC_NOSUPP Not implemented for this cache type * @return No matches found; Data cannot be deleted; Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cc_remove_cred(krb5_context context, krb5_ccache cache, krb5_flags flags, krb5_creds *creds); -/** Set options flags on a credentials cache. +/** + * Set options flags on a credential cache. * - * @param [in] context Context structure - * @param [in,out] cache Credentials cache handle - * @param [in] flags Flag bit mask + * @param [in] context Library context + * @param [in,out] cache Credential cache handle + * @param [in] flags Flag bit mask * * This function resets @a cache flags to @a flags. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cc_set_flags(krb5_context context, krb5_ccache cache, krb5_flags flags); -/** Retrieve flags from a credentials cache structure. +/** + * Retrieve flags from a credential cache structure. * - * @param [in] context Context structure - * @param [in] cache Credentials cache handle returned by - * krb5_cc_resolve() or krb5_cc_generate_new() - * @param [out] flags Flag bit mask + * @param [in] context Library context + * @param [in] cache Credential cache handle + * @param [out] flags Flag bit mask * - * @warning For memory credential cache always returns KRB5_OK. + * @warning For memory credential cache always returns a flag mask of 0. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cc_get_flags(krb5_context context, krb5_ccache cache, krb5_flags *flags); -/** Retrieve the type of a credential cache. +/** + * Retrieve the type of a credential cache. * - * @param [in] context Context structure - * @param [in] cache Credentials cache handle + * @param [in] context Library context + * @param [in] cache Credential cache handle * - * @return The type of a credential cache as an alias that should not be - * modified or freed by the caller. + * @return The type of a credential cache as an alias that must not be modified + * or freed by the caller. */ const char * KRB5_CALLCONV krb5_cc_get_type(krb5_context context, krb5_ccache cache); -/** Move a credential cache. - * - * @param [in] context Context structure - * @param [in] src The credential cache to move the content from - * @param [in] dst The credential cache to move the content to +/** + * Move a credential cache. * - * This function re-initializes @a dst and populates it with the credentials - * and default principal of @a src, and then, if successful, destroys @a src. + * @param [in] context Library context + * @param [in] src The credential cache to move the content from + * @param [in] dst The credential cache to move the content to * - * krb5_ccache objects are locked internally, so no data corruption - * will result if this routine is called on the same credential caches - * in multiple threads. + * This function reinitializes @a dst and populates it with the credentials and + * default principal of @a src; then, if successful, destroys @a src. * * @retval - * 0 Sucess; @a src is freed. + * 0 Success; @a src is closed. * @return - * Kerberos error codes; @a src is still allocated, while @a dst is freed. + * Kerberos error codes; @a src is still allocated, while @a dst is closed. */ krb5_error_code KRB5_CALLCONV krb5_cc_move(krb5_context context, krb5_ccache src, krb5_ccache dst); -/** Return a timestamp of the last modification of the credentials cache. +/** + * Return a timestamp of the last modification to a credential cache. * - * @param [in] context Context structure - * @param [in] ccache Credentials cache handle - * @param [out] change_time The last change time of @a ccache + * @param [in] context Library context + * @param [in] ccache Credential cache handle + * @param [out] change_time The last change time of @a ccache * * If an error occurs, @a change_time is set to 0. */ @@ -2149,28 +2168,31 @@ krb5_cc_lock(krb5_context context, krb5_ccache ccache); krb5_error_code KRB5_CALLCONV krb5_cc_unlock(krb5_context context, krb5_ccache ccache); -/** Prepare to iterate over a collection of credentials caches. +/** + * Prepare to iterate over the collection of known credential caches. * - * @param [in] context Context structure - * @param [in,out] cursor Cursor + * @param [in] context Library context + * @param [in,out] cursor Cursor * - * Get a new cache iteration @a cursor that will iterate over all - * credentials caches independent of type. + * Get a new cache iteration @a cursor that will iterate over all known + * credential caches independent of type. * - * Use krb5_cccol_cursor_free() to release @a cursor when it is no longer needed. + * Use krb5_cccol_cursor_free() to release @a cursor when it is no longer + * needed. * * @sa krb5_cccol_cursor_next() * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cccol_cursor_new(krb5_context context, krb5_cccol_cursor *cursor); -/** Get the next credentials cache in the collection. +/** + * Get the next credential cache in the collection. * - * @param [in] context Context structure - * @param [in,out] cursor Cursor - * @param [out] ccache Credentials cache handle + * @param [in] context Library context + * @param [in,out] cursor Cursor + * @param [out] ccache Credential cache handle * * @note When all caches are iterated over and the end of the list is reached, * @a ccache is set to NULL. @@ -2179,37 +2201,38 @@ krb5_cccol_cursor_new(krb5_context context, krb5_cccol_cursor *cursor); * * @sa krb5_cccol_cursor_new(), krb5_cccol_cursor_free() * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cccol_cursor_next(krb5_context context, krb5_cccol_cursor cursor, krb5_ccache *ccache); -/** Free a credentials cache collection cursor. +/** + * Free a credential cache collection cursor. * - * @param [in] context Context structure - * @param [in] cursor Cursor + * @param [in] context Library context + * @param [in] cursor Cursor * * @sa krb5_cccol_cursor_new(), krb5_cccol_cursor_next() * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cccol_cursor_free(krb5_context context, krb5_cccol_cursor *cursor); -/** Return a timestamp of the last modification for the cache collection. +/** + * Return a timestamp of the last modification of any known credential cache. * - * @param [in] context Context structure - * @param [out] change_time Last modification timestamp + * @param [in] context Library context + * @param [out] change_time Last modification timestamp * - * This function will go through the whole list of the credentials caches. - * If the last modification time is successfully retrieved for the credentials - * in the collection, it will be evaluated for being the most recent timestamp. - * Otherwise, that particular cache will be ignored. + * This function returns the most recent modification time of any known + * credential cache, ignoring any caches which cannot supply a last + * modification time. * - * If there are no credentials in the caches, @a change_time is set to 0. + * If there are no known credential caches, @a change_time is set to 0. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cccol_last_change_time(krb5_context context, krb5_timestamp *change_time); @@ -2220,12 +2243,13 @@ krb5_cccol_lock(krb5_context context); krb5_error_code KRB5_CALLCONV krb5_cccol_unlock(krb5_context context); -/** Create a new unique credentials cache of the specified type. +/** + * Create a new credential cache of the specified type with a unique name. * - * @param [in] context Context structure - * @param [in] type Credentials cache type name - * @param [in] hint Unused - * @param [out] id Credentials cache handle + * @param [in] context Library context + * @param [in] type Credential cache type name + * @param [in] hint Unused + * @param [out] id Credential cache handle * * @retval * 0 Success @@ -2264,39 +2288,36 @@ typedef krb5_pointer krb5_kt_cursor; /* XXX */ /** Key table entry. */ typedef struct krb5_keytab_entry_st { krb5_magic magic; - krb5_principal principal; /**< principal of this key */ - krb5_timestamp timestamp; /**< time entry written to keytable */ - krb5_kvno vno; /**< key version number */ - krb5_keyblock key; /**< the secret key */ + krb5_principal principal; /**< Principal of this key */ + krb5_timestamp timestamp; /**< Time entry written to keytable */ + krb5_kvno vno; /**< Key version number */ + krb5_keyblock key; /**< The secret key */ } krb5_keytab_entry; struct _krb5_kt; typedef struct _krb5_kt *krb5_keytab; -/** Return a type of a key table. - * - * @param [in] context Context structure - * @param [in] keytab Type of key table handle - * - * The possible results might be "FILE", "MEMORY" etc +/** + * Return the type of a key table. * - * @warning The returned value must not be freed by the caller. + * @param [in] context Library context + * @param [in] keytab Key table handle * - * @return - * The key table prefix string. + * @return The type of a key table as an alias that must not be modified or + * freed by the caller. */ const char * KRB5_CALLCONV krb5_kt_get_type(krb5_context context, krb5_keytab keytab); -/** Get a 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 + * @param [in] context Library context + * @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. + * Fills in @a with the name of @a keytab including the type and delimiter. * * @sa MAX_KEYTAB_NAME_LEN * @@ -2312,32 +2333,34 @@ krb5_error_code KRB5_CALLCONV krb5_kt_get_name(krb5_context context, krb5_keytab keytab, char *name, unsigned int namelen); -/** Close a key table. - * - * @param [in] context Context structure - * @param [in] keytab Key table handle +/** + * Close a key table handle. * - * Close a key table, invalidate its handle, and release any other resources - * acquired during use of the key table. - * Undo anything done by krb5_kt_resolve(). + * @param [in] context Library context + * @param [in] keytab Key table handle * * @retval 0 */ krb5_error_code KRB5_CALLCONV krb5_kt_close(krb5_context context, krb5_keytab keytab); -/** Get an entry from a key table. +/** + * Get an entry from a key table. * - * @param [in] context Context structure - * @param [in] keytab Key table handle - * @param [in] principal Principal name - * @param [in] vno Key version number - * @param [in] enctype Encryption type. Use zero for any enctype. - * @param [out] entry Returned entry from key table + * @param [in] context Library context + * @param [in] keytab Key table handle + * @param [in] principal Principal name + * @param [in] vno Key version number (0 for highest available) + * @param [in] enctype Encryption type (0 zero for any enctype) + * @param [out] entry Returned entry from key table * - * 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. + * Retrieve an entry from a key table which matches the @a keytab, @a + * principal, @a vno, and @a enctype. If @a vno is zero, retrieve the + * highest-numbered kvno matching the other fields. If @a enctype is 0, match + * any enctype. + * + * Use krb5_free_keytab_entry_contents() to free @a 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. @@ -2352,15 +2375,15 @@ krb5_kt_get_entry(krb5_context context, krb5_keytab keytab, krb5_const_principal principal, krb5_kvno vno, krb5_enctype enctype, krb5_keytab_entry *entry); -/** Start a sequential retrieve of key table entries. +/** + * Start a sequential retrieval of key table entries. * - * @param [in] context Context structure - * @param [in] keytab Key table handle - * @param [out] cursor Cursor + * @param [in] context Library context + * @param [in] keytab Key table handle + * @param [out] cursor Cursor * - * Prepare to read sequentially every key in the specified key table. - * @a cursor is incremented for next call to krb5_kt_next_entry(). - * The function krb5_kt_end_seq_get() should be called to release the cursor. + * Prepare to read sequentially every key in the specified key table. Use + * krb5_kt_end_seq_get() to release the cursor when it is no longer needed. * * @sa krb5_kt_next_entry(), krb5_kt_end_seq_get() * @@ -2373,17 +2396,15 @@ krb5_error_code KRB5_CALLCONV krb5_kt_start_seq_get(krb5_context context, krb5_keytab keytab, krb5_kt_cursor *cursor); -/** Retrieve the next entry from the key table. +/** + * Retrieve the next entry from the key table. * - * @param [in] context Context structure - * @param [in] keytab Key table handle - * @param [out] entry Returned key table entry - * @param [in,out] cursor The cursor created by krb5_kt_start_seq_get() - * and updated by successful runs of this routine + * @param [in] context Library context + * @param [in] keytab Key table handle + * @param [out] entry Returned key table entry + * @param [in,out] cursor Key table cursor * - * 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. + * Return the next sequential entry in @a keytab and advance @a cursor. * * @sa krb5_kt_start_seq_get(), krb5_kt_end_seq_get() * @@ -2398,13 +2419,15 @@ krb5_error_code KRB5_CALLCONV krb5_kt_next_entry(krb5_context context, krb5_keytab keytab, krb5_keytab_entry *entry, krb5_kt_cursor *cursor); -/** Complete a series of sequential key table entry retrievals and invalidate @a cursor. +/** + * Release a keytab cursor. * - * @param [in] context Context structure - * @param [in] keytab Key table handle - * @param [out] cursor Cursor + * @param [in] context Library context + * @param [in] keytab Key table handle + * @param [out] cursor Cursor * - * This function should be called to release the cursor created by krb5_kt_start_seq_get() + * This function should be called to release the cursor created by + * krb5_kt_start_seq_get(). * * @retval * 0 Success @@ -2423,16 +2446,17 @@ krb5_kt_end_seq_get(krb5_context context, krb5_keytab keytab, * begin "func-proto.h" */ -/** Create and intialize a krb5_context structure. +/** + * Create a krb5 library context. * - * @param [out] context Context structure + * @param [out] context Library context * * The @a 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 - * the environment must use krb5_init_secure_context(), - * or clean out the environment. + * @warning Any program or module that needs the Kerberos code to not trust the + * environment must use krb5_init_secure_context(), or clean out the + * environment. * * @retval * 0 Success @@ -2442,13 +2466,13 @@ krb5_kt_end_seq_get(krb5_context context, krb5_keytab keytab, krb5_error_code KRB5_CALLCONV krb5_init_context(krb5_context *context); -/** Create and initialize a krb5_context structure using only configuration files. +/** + * Create a krb5 library context using only configuration files. * - * @param [out] context Context structure + * @param [out] context Library context * - * Initialize a context structure, using only configuration files that - * are safe for a @c setuid program. - * All information passed through the environment variables is ignored. + * Create a context structure, using only system configuration files. All + * information passed through the environment variables is ignored. * * The @a context must be released by calling krb5_free_context() when * it is no longer needed. @@ -2461,9 +2485,10 @@ krb5_init_context(krb5_context *context); krb5_error_code KRB5_CALLCONV krb5_init_secure_context(krb5_context *context); -/** Free a krb5_context structure. +/** + * Free a krb5 library context. * - * @param [in] context Context structure + * @param [in] context Library context * * This function frees a @a context that was created by krb5_init_context() * or krb5_init_secure_context(). @@ -2471,10 +2496,11 @@ krb5_init_secure_context(krb5_context *context); void KRB5_CALLCONV krb5_free_context(krb5_context context); -/** Copy a krb5_context structure. +/** + * Copy a krb5_context structure. * - * @param [in] ctx Context structure - * @param [out] nctx_out New "cloned" context structure + * @param [in] ctx Library context + * @param [out] nctx_out New context structure * * The newly created context must be released by calling krb5_free_context() * when it is no longer needed. @@ -2487,10 +2513,11 @@ krb5_free_context(krb5_context context); krb5_error_code KRB5_CALLCONV krb5_copy_context(krb5_context ctx, krb5_context *nctx_out); -/** Set default TGS encryption types in a krb5_context structure. +/** + * Set default TGS encryption types in a krb5_context structure. * - * @param [in,out] context Context structure - * @param [in] etypes Encryption type(s) to set + * @param [in,out] context Library context + * @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. @@ -2507,26 +2534,23 @@ krb5_copy_context(krb5_context ctx, krb5_context *nctx_out); krb5_error_code KRB5_CALLCONV krb5_set_default_tgs_enctypes(krb5_context context, const krb5_enctype *etypes); -/** Return a list of supported encryption types. - * - * @param [in] context Context structure - * @param [out] ktypes Zero-terminated list of encryption types +/** + * Return a list of encryption types permitted for session keys. * - * This function returns the content of @a context->tgs_etypes if it is non-NULL. - * Otherwise, the libdefaults profile string of permitted_enctypes, if it exists. - * Otherwise, the default enctype list that is defined as follows: - * ENCTYPE_AES256_CTS_HMAC_SHA1_96, ENCTYPE_AES128_CTS_HMAC_SHA1_96, - * ENCTYPE_DES3_CBC_SHA1, ENCTYPE_ARCFOUR_HMAC, - * ENCTYPE_DES_CBC_CRC, ENCTYPE_DES_CBC_MD5, ENCTYPE_DES_CBC_MD4. + * @param [in] context Library context + * @param [out] ktypes Zero-terminated list of encryption types * - * Use krb5_free_ktypes() to free @a ktypes when it is no longer needed. + * This function returns the list of encryption types permitted for session + * keys within @a context, as determined by configuration or by a previous call + * to krb5_set_default_tgs_enctypes(). * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_get_permitted_enctypes(krb5_context context, krb5_enctype **ktypes); -/** Test whether the Kerberos library was built with multithread support. +/** + * Test whether the Kerberos library was built with multithread support. * * @retval * TRUE if the library is threadsafe; FALSE otherwise @@ -2536,61 +2560,64 @@ krb5_is_thread_safe(void); /* libkrb.spec */ -/** Decrypt a ticket using the specified key table. +/** + * Decrypt a ticket using the specified key table. * - * @param [in] context Context structure - * @param [in] kt Key table - * @param [in,out] ticket Ticket to be decrypted + * @param [in] context Library context + * @param [in] kt Key table + * @param [in,out] ticket Ticket to be decrypted * - * 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. + * This function takes a @a ticket as input and decrypts it using + * key data from @a kt. The result is placed into @a ticket->enc_part2. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_server_decrypt_ticket_keytab(krb5_context context, const krb5_keytab kt, krb5_ticket *ticket); -/** Free the storage assigned to array of credentials. +/** + * Free an array of credential structures. * - * @param [in] context Context structure - * @param [in] tgts Array of credentials to be freed + * @param [in] context Library context + * @param [in] tgts Null-terminated array of credentials to free * * @note The last entry in the array @a tgts must be a NULL pointer. */ void KRB5_CALLCONV krb5_free_tgt_creds(krb5_context context, krb5_creds **tgts); -#define KRB5_GC_USER_USER 1 /**< want user-user ticket */ -#define KRB5_GC_CACHED 2 /**< want cached ticket only */ -#define KRB5_GC_CANONICALIZE 4 /**< set canonicalize KDC option */ -#define KRB5_GC_NO_STORE 8 /**< do not store in credentials cache */ -#define KRB5_GC_FORWARDABLE 16 /**< acquire forwardable tickets */ -#define KRB5_GC_NO_TRANSIT_CHECK 32 /**< disable transited check */ -#define KRB5_GC_CONSTRAINED_DELEGATION 64 /**< constrained delegation */ +#define KRB5_GC_USER_USER 1 /**< Want user-user ticket */ +#define KRB5_GC_CACHED 2 /**< Want cached ticket only */ +#define KRB5_GC_CANONICALIZE 4 /**< Set canonicalize KDC option */ +#define KRB5_GC_NO_STORE 8 /**< Do not store in credential cache */ +#define KRB5_GC_FORWARDABLE 16 /**< Acquire forwardable tickets */ +#define KRB5_GC_NO_TRANSIT_CHECK 32 /**< Disable transited check */ +#define KRB5_GC_CONSTRAINED_DELEGATION 64 /**< Constrained delegation */ -/** Get an additional ticket. +/** + * Get an additional ticket. * - * @param [in] context Context structure - * @param [in] options Options - * @param [in,out] ccache Credentials cache handle - * @param [in] in_creds Input credentials - * @param [out] out_creds Output updated credentials + * @param [in] context Library context + * @param [in] options Options + * @param [in,out] ccache Credential cache handle + * @param [in] in_creds Input credentials + * @param [out] out_creds Output updated credentials * - * Use the specified credentials cache or a TGS exchange to get an additional - * ticket for the client identified by @a in_creds->client. + * Use @a ccache or a TGS exchange to get a service ticket matching @a + * in_creds. * * Valid values for @a options are: - * @li @c KRB5_GC_CACHED Search only credentials cache for the ticket - * @li @c KRB5_GC_USER_USER Return a full user to user authentication ticket + * @li @c KRB5_GC_CACHED Search only credential cache for the ticket + * @li @c KRB5_GC_USER_USER Return a user to user authentication ticket * - * @a in_creds must be non-null. @a in_creds->client and @a in_creds->server - * must be filled in to specify the client and the server respectively. - * If any special data needs to be included in the ticket (such as restrictions - * on how the ticket can be used), specify it in @a in_creds->authdata. - * If there is no special data to be passed, set @a in_creds->authdata to NULL. - * The session key type is specified in @a in_creds->keyblock.keytype, - * if it is nonzero. + * @a in_creds must be non-null. @a in_creds->client and @a in_creds->server + * must be filled in to specify the client and the server respectively. If any + * authorization data needs to be requested for the service ticket (such as + * restrictions on how the ticket can be used), specify it in @a + * in_creds->authdata; otherwise set @a in_creds->authdata to NULL. The + * session key type is specified in @a in_creds->keyblock.enctype, if it is + * nonzero. * * The expiration date is specified in @a in_creds->times.endtime. * The KDC may return tickets with an earlier expiration date. @@ -2612,343 +2639,295 @@ krb5_get_credentials(krb5_context context, krb5_flags options, krb5_ccache ccache, krb5_creds *in_creds, krb5_creds **out_creds); -/** Contact the KDC to validate credentials. - * - * @param [in] context Context structure - * @param options Unused - * @param [in,out] ccache Credentials cache handle - * @param [in] in_creds Request credentials - * @param [out] out_creds Output credentials - * - * This function gets a validated credential matching @a in_creds, by - * retrieving a matching credential from @a ccache and validating it with the - * credential's realm's KDC. Upon successful completion the result is placed in - * @a out_creds, the @a ccache is re-initialized and updated with a new ticket. - * Use krb5_free_creds() to free @a out when it is no longer needed. - * - * @retval 0 Success; Otherwise - Kerberos error codes - */ +/** @deprecated Replaced by krb5_get_validated_creds. */ krb5_error_code KRB5_CALLCONV krb5_get_credentials_validate(krb5_context context, krb5_flags options, krb5_ccache ccache, krb5_creds *in_creds, krb5_creds **out_creds); -/** Contact the KDC to renew credentials. - * - * @param [in] context Context structure - * @param options Unused - * @param [in,out] ccache Credentials cache handle - * @param [in] in_creds Request credentials - * @param [out] out_creds Output credentials - * - * This function gets a renewed credential matching @a in_creds, by - * retrieving a matching credential from @a ccache and renewing it with the - * credential's realm's KDC. Upon successful completion the result is placed in - * @a out_creds, the @a ccache is re-initialized and updated with a new ticket. - * Use krb5_free_creds() to free @a out when it is no longer needed. - * - * @retval 0 Success; Otherwise - Kerberos error codes - */ +/** @deprecated Replaced by krb5_get_renewed_creds. */ krb5_error_code KRB5_CALLCONV krb5_get_credentials_renew(krb5_context context, krb5_flags options, krb5_ccache ccache, krb5_creds *in_creds, krb5_creds **out_creds); -/** Format a @c KRB_AP_REQ message. +/** + * Create a @c KRB_AP_REQ message. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context, containing the checksum - * method to be used; a new authentication - * context is returned if NULL is specified. + * @param [in] context Library context + * @param [in,out] auth_context Pre-existing or newly created auth context * @param [in] ap_req_options AP_OPTS_ options - * @param [in] service Service name, or NULL to use string @c host - * @param [in] hostname Host name, or NULL to use local host - * @param [in] in_data Application data's checksum to be - * included in the authenticator; specify NULL - * if no checksum is to be included - * @param [in] ccache Credentials cache that is to be used to obtain - * credentials to the desired service. + * @param [in] service Service name, or NULL to use @c "host" + * @param [in] hostname Host name, or NULL to use local hostname + * @param [in] in_data Application data to be checksummed in the + * authenticator, or NULL + * @param [in] ccache Credential cache used to obtain credentials + * for the desired service. * @param [out] outbuf @c AP-REQ message * - * Valid @a ap_req_options are: - * @li @c AP_OPTS_USE_SESSION_KEY - Use the session key when creating the - * request used for user to user authentication. - * @li @c AP_OPTS_MUTUAL_REQUIRED - Request a mutual authentication packet from - * the reciever. - * @li @c AP_OPTS_USE_SUBKEY - Generate a subsession key from the current - * session key obtained from the credentials. - - * This function is similar to krb5_mk_req_extended() except that it - * uses a given @a hostname, @a service and @a ccache to construct credentials. + * This function is similar to krb5_mk_req_extended() except that it uses a + * given @a hostname, @a service, and @a ccache to construct a service + * principal name and obtain credentials. * * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_mk_req(krb5_context context, krb5_auth_context *auth_context, krb5_flags ap_req_options, char *service, char *hostname, krb5_data *in_data, krb5_ccache ccache, krb5_data *outbuf); -/** Format a @c KRB_AP_REQ message using supplied credentials. +/** + * Create a @c KRB_AP_REQ message using supplied credentials. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context, containing the checksum - * method to be used; a new authentication - * context is returned if NULL is specified. + * @param [in] context Library context + * @param [in,out] auth_context Pre-existing or newly created auth context * @param [in] ap_req_options AP_OPTS_ options - * @param [in] in_data Application data's checksum to be - * included in the authenticator; specify NULL - * if no checksum is to be included + * @param [in] in_data Application data to be checksummed in the + * authenticator, or NULL * @param [in] in_creds Credentials for the service with valid ticket * and key * @param [out] outbuf @c AP-REQ message * * Valid @a ap_req_options are: * @li @c AP_OPTS_USE_SESSION_KEY - Use the session key when creating the - * request used for user to user authentication. + * request used for user to user + * authentication. * @li @c AP_OPTS_MUTUAL_REQUIRED - Request a mutual authentication packet from * the reciever. * @li @c AP_OPTS_USE_SUBKEY - Generate a subsession key from the current * session key obtained from the credentials. * - * This function creates a KRB_AP_REQ message using supplied credentials - * @a in_creds. The checksum @a in_data is included in the authenticator that - * is part of the KRB_AP_REQ message. - * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed. + * This function creates a KRB_AP_REQ message using supplied credentials @a + * in_creds. @a auth_context may point to an existing auth context or to NULL, + * in which case a new one will be created. If @a in_data is non-null, a + * checksum of it will be included in the authenticator contained in the + * KRB_AP_REQ message. Use krb5_free_data_contents() to free @a outbuf when it + * is no longer needed. * - * @note A newly generated authenticator is stored in @a auth_context with the - * @a client and @a checksum fields nulled out, unless an error is returned. - * (This is to prevent pointer-sharing problems; the caller should not need - * these fields anyway, since the caller supplied them.) - * The old @a auth_context->key is overwritten by keyblock from @a in_creds. + * On successful return, the authenticator is stored in @a auth_context with + * the @a client and @a checksum fields nulled out. (This is to prevent + * pointer-sharing problems; the caller should not need these fields anyway, + * since the caller supplied them.) * * @sa krb5_mk_req() * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_mk_req_extended(krb5_context context, krb5_auth_context *auth_context, krb5_flags ap_req_options, krb5_data *in_data, krb5_creds *in_creds, krb5_data *outbuf); -/** Format and encrypt a @c KRB_AP_REP message. - * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context - * @param [out] outbuf @c AP-REP message +/** + * Format and encrypt a @c KRB_AP_REP message. * - * The @c AP-REP message includes the data in the @a authentp field of @a - * auth_context, and it is encrypted using the @a key field from @a auth_context. + * @param [in] context Library context + * @param [in,out] auth_context Authentication context + * @param [out] outbuf @c AP-REP message * - * When successful, @a outbuf->length and @a outbuf->data are filled in with the - * length of the @c AP-REQ message and the allocated data holding it. + * This function fills in @a outbuf with an AP-REP message using information + * from @a auth_context. * - * If the flags in @a auth_context indicate that a sequence number should be used - * (either @c KRB5_AUTH_CONTEXT_DO_SEQUENCE or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE) - * and the local sequence number in @a auth_context is 0, a new number will - * be generated with krb5_generate_seq_number(). + * If the flags in @a auth_context indicate that a sequence number should be + * used (either @c KRB5_AUTH_CONTEXT_DO_SEQUENCE or @c + * KRB5_AUTH_CONTEXT_RET_SEQUENCE) and the local sequence number in @a + * auth_context is 0, a new number will be generated with + * krb5_generate_seq_number(). * * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_mk_rep(krb5_context context, krb5_auth_context auth_context, krb5_data *outbuf); -/** Format and encrypt a @c KRB_AP_REP message for DCE RPC. +/** + * Format and encrypt a @c KRB_AP_REP message for DCE RPC. * - * @param [in] context Context structure + * @param [in] context Library context * @param [in,out] auth_context Authentication context * @param [out] outbuf @c AP-REP message * * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_mk_rep_dce(krb5_context context, krb5_auth_context auth_context, krb5_data *outbuf); -/** Parse and decrypt a @c KRB_AP_REP message. +/** + * Parse and decrypt a @c KRB_AP_REP message. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] inbuf AP-REP message - * @param [out] repl Decrypted reply message + * @param [in] context Library context + * @param [in,out] auth_context Authentication context + * @param [in] inbuf AP-REP message + * @param [out] repl Decrypted reply message * * This function parses, decrypts and verifies a message from @a inbuf and * fills in @a repl with a pointer to allocated memory containing the fields * from the encrypted response. + * * Use krb5_free_ap_rep_enc_part() to free @a repl when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_rd_rep(krb5_context context, krb5_auth_context auth_context, const krb5_data *inbuf, krb5_ap_rep_enc_part **repl); -/** Parse and decrypt a @c KRB_AP_REP message for DCE RPC. +/** + * Parse and decrypt a @c KRB_AP_REP message for DCE RPC. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] inbuf AP-REP message - * @param [out] nonce Sequence number from the decrypted reply + * @param [in] context Library context + * @param [in,out] auth_context Authentication context + * @param [in] inbuf AP-REP message + * @param [out] nonce Sequence number from the decrypted reply * * This function parses, decrypts and verifies a message from @a inbuf and * fills in @a nonce with a decrypted reply sequence number. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_rd_rep_dce(krb5_context context, krb5_auth_context auth_context, const krb5_data *inbuf, krb5_ui_4 *nonce); -/** Format and encode a @c KRB_ERROR message. +/** + * Format and encode a @c KRB_ERROR message. * - * @param [in] context Context structure - * @param [in] dec_err Error structure to be encoded - * @param [out] enc_err Encoded error structure + * @param [in] context Library context + * @param [in] dec_err Error structure to be encoded + * @param [out] enc_err Encoded error structure * - * This function creates a @c KRB_ERROR message @a enc_err suitable to be - * sent to the remote partner instead of sending a reply message. - * Use krb5_free_data_contents() for free @a enc_err when it is no longer needed. + * This function creates a @c KRB_ERROR message in @a enc_err. Use + * krb5_free_data_contents() to free @a enc_err when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_mk_error(krb5_context context, const krb5_error *dec_err, krb5_data *enc_err); -/** Decode a @c KRB-ERROR message. +/** + * Decode a @c KRB-ERROR message. * - * @param [in] context Context structure - * @param [in] enc_errbuf Encoded error message - * @param [out] dec_error Decoded error message + * @param [in] context Library context + * @param [in] enc_errbuf Encoded error message + * @param [out] dec_error Decoded error message * * This function processes @c KRB-ERROR message @a enc_errbuf and returns * an allocated structure @a dec_error containing the error message. * Use krb5_free_error() to free @a dec_error when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_rd_error(krb5_context context, const krb5_data *enc_errbuf, krb5_error **dec_error); -/** Process @c KRB-SAFE message. +/** + * Process @c KRB-SAFE message. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication structure - * @param [in] inbuf @c KRB-SAFE message to be parsed - * @param [out] outbuf Data parsed from @c KRB-SAFE message - * @param [out] outdata Replay data. Specify NULL if not needed + * @param [in] context Library context + * @param [in,out] auth_context Authentication structure + * @param [in] inbuf @c KRB-SAFE message to be parsed + * @param [out] outbuf Data parsed from @c KRB-SAFE message + * @param [out] outdata Replay data. Specify NULL if not needed * * This function parses a @c KRB-SAFE message, verifies its integrity, and * stores its data into @a outbuf. * * @note The @a outdata argument is required if KRB5_AUTH_CONTEXT_RET_TIME or - * KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.` - * - * @note The @a remote_addr argument in @a auth_context argument is mandatory. - * It specifies the address of the sender. This address will be used - * to verify the sender address in the KRB-SAFE message. - * - * The keyblock used to verify the integrity of the message is taken from the - * fields @a recv_subkey or @a key in @a auth_context. - * The keyblock is chosen in the preceding order by the first one that is non-null. - * - * @a remote_addr and @a localaddr in @a auth_context specify - * the full addresses (host and port) of the sender and receiver, and must be of - * type @c ADDRTYPE_ADDRPORT. + * KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context. * - * If @a local_addr is non-null, then the address of the receiver in the message - * must match it. Otherwise, the receiver address in the message will be checked - * against the list of local addresses as returned by krb5_os_localaddr(). - * If the check fails, an error is returned. + * @note @a auth_context must have a remote address set. This address will be + * used to verify the sender address in the KRB-SAFE message. If @a + * auth_context has a local address set, it will be used to verify the + * receiver address in the KRB-SAFE message if the message contains one. + * Both addresses must use type @c ADDRTYPE_ADDRPORT. * - * If KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context - * the @a remote_seq_number field of @a auth_context is compared to the - * sequence number for the message, and error is returned - * if it does not match. Otherwise, the sequence number is not used. + * If the KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context, the + * sequence number of the KRB-SAFE message is checked against the remote + * sequence number field of @a auth_context. Otherwise, the sequence number is + * not used. * - * If KRB5_AUTH_CONTEXT_DO_TIME flag is set in @a auth_context, + * If the KRB5_AUTH_CONTEXT_DO_TIME flag is set in @a auth_context, * then two additional checks are performed: * @li The timestamp in the message must be within the permitted clock skew - * (which is usually five minutes), or error is returned. + * (which is usually five minutes). * @li The message must not be a replayed message field in @a auth_context. * * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_rd_safe(krb5_context context, krb5_auth_context auth_context, const krb5_data *inbuf, krb5_data *outbuf, krb5_replay_data *outdata); -/** Process a @c KRB-PRIV message. +/** + * Process a @c KRB-PRIV message. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication structure - * @param [in] inbuf @c KRB-PRIV message to be parsed - * @param [out] outbuf Data parsed from @c KRB-PRIV message - * @param [out] outdata Replay data. Specify NULL if not needed + * @param [in] context Library context + * @param [in,out] auth_context Authentication structure + * @param [in] inbuf @c KRB-PRIV message to be parsed + * @param [out] outbuf Data parsed from @c KRB-PRIV message + * @param [out] outdata Replay data. Specify NULL if not needed * * This function parses a @c KRB-PRIV message, verifies its integrity, and - * stores its data into @a outbuf. - * - * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE - * flag is set in @a auth_context, the @a outdata is required. - * - * @note The @a remote_addr argument in @a auth_context argument is mandatory. - * It specifies the address of the sender. This address will be used - * to verify the sender address in the KRB-SAFE message. + * stores its unencrypted data into @a outbuf. * - * The keyblock used to decrypt the data and verify the integrity of the message - * is taken from fields @a recv_subkey or @a key in @a auth_context. - * The keyblock is chosen in the preceding order by the first one that is non-null. + * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c + * KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in @a auth_context, @a + * outdata is required. * - * If @c local_addr field of @a auth_context is non-null, the address of the - * receiver in the message must match it. Otherwise, the receiver address in the - * message will be checked against the list of local addresses as returned by - * krb5_os_localaddr(). + * @note @a auth_context must have a remote address set. This address will be + * used to verify the sender address in the KRB-PRIV message. If @a + * auth_context has a local address set, it will be used to verify the + * receiver address in the KRB-PRIV message if the message contains one. + * Both addresses must use type @c ADDRTYPE_ADDRPORT. * - * If the @a i_vector field in @a auth_context is non-null, it is used as an - * initialization vector for the decryption (if the encryption type of - * the message supports initialization vectors) and its contents are replaced - * with the last block of encrypted data in the message. + * If the KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context, the + * sequence number of the KRB-SAFE message is checked against the remote + * sequence number field of @a auth_context. Otherwise, the sequence number is + * not used. * - * If KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context - * the @a remote_seq_number field of @a auth_context is compared to the - * sequence number for the message, and error is returned - * if it does not match. Otherwise, the sequence number is not used. + * If the KRB5_AUTH_CONTEXT_DO_TIME flag is set in @a auth_context, + * then two additional checks are performed: + * @li The timestamp in the message must be within the permitted clock skew + * (which is usually five minutes). + * @li The message must not be a replayed message field in @a auth_context. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_rd_priv(krb5_context context, krb5_auth_context auth_context, const krb5_data *inbuf, krb5_data *outbuf, krb5_replay_data *outdata); -/** Convert a single-string principal name to a krb5_principal structure. +/** + * Convert a string principal name to a krb5_principal structure. * - * @param [in] context Context structure - * @param [in] name Single string representation of a principal name - * @param [out] nprincipal Principal + * @param [in] context Library context + * @param [in] name String representation of a principal name + * @param [out] nprincipal Principal * - * Convert a single-string representation of a principal name to a - * krb5_principal structure. + * Convert a string representation of a principal name to a krb5_principal + * structure. * - * A single-string representation of a Kerberos name consists of one - * or more principal name components, separated by slashes, optionally followed by - * the \@ character and a realm name. - * If the realm name is not specified, the local realm is used. + * A string representation of a Kerberos name consists of one or more principal + * name components, separated by slashes, optionally followed by the \@ + * character and a realm name. If the realm name is not specified, the local + * realm is used. * - * To use the slash and \@ symbols as part of a component (quoted) - * instead of using them as a component separator or as a realm prefix), - * put a backslash (\) character in front of the symbol. - * Similarly, newline, tab, backspace, and NULL characters - * can be included in a component by using @a n, @a t,@a b or @a 0, respectively. + * To use the slash and \@ symbols as part of a component (quoted) instead of + * using them as a component separator or as a realm prefix), put a backslash + * (\) character in front of the symbol. Similarly, newline, tab, backspace, + * and NULL characters can be included in a component by using @c n, @c t, @c b + * or @c 0, respectively. * * @note The realm in a Kerberos @a name cannot contain slash, colon, * or NULL characters. @@ -2968,21 +2947,22 @@ krb5_parse_name(krb5_context context, const char *name, krb5_principal *nprincip #define KRB5_PRINCIPAL_PARSE_ENTERPRISE 0x4 /**< Create single-component enterprise principle */ -/** Convert a single-string principal name to a krb5_principal with restrictions. +/** + * Convert a string principal name to a krb5_principal with flags * - * @param [in] context Context structure - * @param [in] name Single string representation of a principal name - * @param [in] flags Flag - * @param [out] nprincipal Principal + * @param [in] context Library context + * @param [in] name String representation of a principal name + * @param [in] flags Flag + * @param [out] nprincipal Principal * - * Similar to krb5_parse_name(), this function converts a single-string - * representation of a principal name to a krb5_principal structure; - * takes the additional flags. + * Similar to krb5_parse_name(), this function converts a single-string + * representation of a principal name to a krb5_principal structure. * * The following flags are valid: * @li @c KRB5_PRINCIPAL_PARSE_NO_REALM - no realm must be present in @a name * @li @c KRB5_PRINCIPAL_PARSE_MUST_REALM - realm must be present in @a name - * @li @c KRB5_PRINCIPAL_PARSE_ENTERPRISE - Create single-component enterprise principal + * @li @c KRB5_PRINCIPAL_PARSE_ENTERPRISE - create single-component enterprise + * principal * * Use krb5_free_principal() to free @a nprincipal when it is no longer needed. * @@ -2995,13 +2975,14 @@ krb5_error_code KRB5_CALLCONV krb5_parse_name_flags(krb5_context context, const char *name, int flags, krb5_principal *nprincipal); -/** Convert a krb5_principal structure to a single-string representation. +/** + * Convert a krb5_principal structure to a string representation. * - * @param [in] context Context structure - * @param [in] principal Principal - * @param [out] name Single string representation of a Kerberos principal name + * @param [in] context Library context + * @param [in] principal Principal + * @param [out] name String representation of principal name * - * The resulting single-string representation uses the format and quoting conventions + * The resulting string representation uses the format and quoting conventions * described for krb5_parse_name(). * * Use krb5_free_unparsed_name() to free @a name when it is no longer needed. @@ -3015,14 +2996,16 @@ krb5_error_code KRB5_CALLCONV krb5_unparse_name(krb5_context context, krb5_const_principal principal, register char **name); -/** Convert krb5_principal structure to string format. +/** + * Convert krb5_principal structure to string and length. * - * @param [in] context Context structure - * @param [in] principal Principal - * @param [out] name Single string format of principal name - * @param [out] size Size of unparsed name buffer + * @param [in] context Library context + * @param [in] principal Principal + * @param [out] name String representation of principal name + * @param [out] size Size of unparsed name * - * @sa krb5_unparse_name() + * This function is similar to krb5_unparse_name(), but also returns the length + * of the string representation. * * @retval * 0 Success @@ -3037,20 +3020,21 @@ krb5_unparse_name_ext(krb5_context context, krb5_const_principal principal, #define KRB5_PRINCIPAL_UNPARSE_NO_REALM 0x2 /**< Omit realm always */ #define KRB5_PRINCIPAL_UNPARSE_DISPLAY 0x4 /**< Don't escape special characters */ -/** Convert krb5_principal structure to a single-string with restrictions. +/** + * Convert krb5_principal structure to a string with flags. * - * @param [in] context Context structure - * @param [in] principal Principal - * @param [in] flags Flags - * @param [out] name Single string representation of a Kerberos principal name + * @param [in] context Library context + * @param [in] principal Principal + * @param [in] flags Flags + * @param [out] name String representation of principal name * - * Similar to krb5_unparse_name(), this function converts a krb5_principal structure - * to a single-string representation; takes the additional flags. + * Similar to krb5_unparse_name(), this function converts a krb5_principal + * structure to a string representation. * * The following flags are valid: - * @li @c KRB5_PRINCIPAL_UNPARSE_SHORT - omit realm if it is the local realm - * @li @c KRB5_PRINCIPAL_UNPARSE_NO_REALM - omit realm in the principal name @a name - * @li @c KRB5_PRINCIPAL_UNPARSE_DISPLAY - no quoting in the principal name @a name + * @li @c KRB5_PRINCIPAL_UNPARSE_SHORT - omit realm if it is the local realm + * @li @c KRB5_PRINCIPAL_UNPARSE_NO_REALM - omit realm + * @li @c KRB5_PRINCIPAL_UNPARSE_DISPLAY - do not quote special characters * * Use krb5_free_unparsed_name() to free @a name when it is no longer needed. * @@ -3063,13 +3047,14 @@ krb5_error_code KRB5_CALLCONV krb5_unparse_name_flags(krb5_context context, krb5_const_principal principal, int flags, char **name); -/** Convert krb5_principal structure to string format with restrictions. +/** + * Convert krb5_principal structure to string format with flags. * - * @param [in] context Context structure - * @param [in] principal Principal - * @param [in] flags Flags - * @param [out] name Single string format of principal name - * @param [out] size Size of unparsed name buffer + * @param [in] context Library context + * @param [in] principal Principal + * @param [in] flags Flags + * @param [out] name Single string format of principal name + * @param [out] size Size of unparsed name buffer * * @sa krb5_unparse_name() krb5_unparse_name_flags() krb5_unparse_name_ext() * @@ -3082,15 +3067,15 @@ krb5_error_code KRB5_CALLCONV krb5_unparse_name_flags_ext(krb5_context context, krb5_const_principal principal, int flags, char **name, unsigned int *size); -/** Set the realm in the current context. - * - * @param [in,out] context Context structure - * @param [in] principal Principal name - * @param [in] realm Realm name +/** + * Set the realm field of a principal * - * Set the realm name part of @a principal to @a realm. + * @param [in,out] context Library context + * @param [in] principal Principal name + * @param [in] realm Realm name * - * @note This function frees the previous realm of @a principal. + * Set the realm name part of @a principal to @a realm, overwriting the + * previous realm. * * @retval * 0 Success @@ -3101,41 +3086,44 @@ krb5_error_code KRB5_CALLCONV krb5_set_principal_realm(krb5_context context, krb5_principal principal, const char *realm); -/** Search a list of addresses for a specified address. +/** + * Search a list of addresses for a specified address. * - * @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 + * @param [in] context Library context + * @param [in] addr Address to search for + * @param [in] addrlist Address list to be searched (or NULL) * - * @note If @a addrlist contains only a NetBIOS addresses, - * it will be treated as empty list. + * @note If @a addrlist contains only a NetBIOS addresses, it will be treated + * as a null list. * - * @retval - * TRUE if @a addr is listed in @a addrlist, or @c addrlist is NULL; FALSE otherwise + * @return + * 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, krb5_address *const *addrlist); -/** Compare two Kerberos addresses. +/** + * Compare two Kerberos addresses. * - * @param context Context structure - * @param [in] addr1 First address to be compared - * @param [in] addr2 Second address to be compared + * @param [in] context Library context + * @param [in] addr1 First address to be compared + * @param [in] addr2 Second address to be compared * - * @retval - * TRUE if the addresses are the same, FALSE otherwise + * @return + * TRUE if the addresses are the same, FALSE otherwise */ krb5_boolean KRB5_CALLCONV krb5_address_compare(krb5_context context, const krb5_address *addr1, const krb5_address *addr2); -/** Return an ordering of the specified addresses. +/** + * Return an ordering of the specified addresses. * - * @param context Context structure - * @param [in] addr1 First address - * @param [in] addr2 Second address + * @param [in] context Library context + * @param [in] addr1 First address + * @param [in] addr2 Second address * * @retval * 0 The two addresses are the same @@ -3148,11 +3136,12 @@ int KRB5_CALLCONV krb5_address_order(krb5_context context, const krb5_address *addr1, const krb5_address *addr2); -/** Compare the realms of two principals. +/** + * Compare the realms of two principals. * - * @param [in] context Context structure - * @param [in] princ1 First principal - * @param [in] princ2 Second principal + * @param [in] context Library context + * @param [in] princ1 First principal + * @param [in] princ2 Second principal * * @retval * TRUE if the realm names are the same; FALSE otherwise @@ -3161,11 +3150,12 @@ krb5_boolean KRB5_CALLCONV krb5_realm_compare(krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2); -/** Compare two principals. +/** + * Compare two principals. * - * @param [in] context Context structure - * @param [in] princ1 First principal - * @param [in] princ2 Second principal + * @param [in] context Library context + * @param [in] princ1 First principal + * @param [in] princ2 Second principal * * @retval * TRUE if the principals are the same; FALSE otherwise @@ -3175,14 +3165,15 @@ krb5_principal_compare(krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2); -/** Compare two principals ignoring realm components. +/** + * Compare two principals ignoring realm components. * - * @param [in] context Context structure - * @param [in] princ1 First principal - * @param [in] princ2 Second principal + * @param [in] context Library context + * @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 + * components of the principals. * * @retval * TRUE if the principals are the same; FALSE otherwise @@ -3197,9 +3188,10 @@ krb5_principal_compare_any_realm(krb5_context context, #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. +/** + * Compare two principals with additional flags. * - * @param [in] context Context structure + * @param [in] context Library context * @param [in] princ1 First principal * @param [in] princ2 Second principal * @param [in] flags Flags @@ -3221,154 +3213,163 @@ krb5_principal_compare_flags(krb5_context context, krb5_const_principal princ2, int flags); -/** Initialize an empty @c _krb5_keyblock. +/** + * Initialize an empty @c krb5_keyblock. * - * @param [in] context Context structure - * @param [in] enctype Encryption type - * @param [in] length Length of keyblock - * @param [out] out Pointer to empty keyblock + * @param [in] context Library context + * @param [in] enctype Encryption type + * @param [in] length Length of keyblock (or 0) + * @param [out] out New keyblock structure * - * Initialize a new keyblock and allocate storage - * for the contents of the key, which will be freed along - * with the keyblock when krb5_free_keyblock is called. - * It is legal to pass in a length of 0, in which - * case contents are left unallocated. - * Use krb5_free_keyblock() to free @a out when it is no longer needed. + * Initialize a new keyblock and allocate storage for the contents of the key. + * It is legal to pass in a length of 0, in which case contents are left + * unallocated. Use krb5_free_keyblock() to free @a out when it is no longer + * needed. * * @note If @a length is set to 0, contents are left unallocated. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_init_keyblock(krb5_context context, krb5_enctype enctype, size_t length, krb5_keyblock **out); -/** Copy a keyblock. +/** + * Copy a keyblock. * - * @param [in] context Context structure - * @param [in] from Keyblock to be copied - * @param [out] to Copy of keyblock @a from + * @param [in] context Library context + * @param [in] from Keyblock to be copied + * @param [out] to Copy of keyblock @a from * - * This function copies the content of @a from to @a to - * Use krb5_free_keyblock() to free @a to when it is no longer needed. + * This function creates a new keyblock with the same contents as @a from. Use + * krb5_free_keyblock() to free @a to when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_copy_keyblock(krb5_context context, const krb5_keyblock *from, krb5_keyblock **to); -/** Copy the contents of a keyblock. +/** + * Copy the contents of a keyblock. * - * @param [in] context Context structure - * @param [in] from Key to be copied - * @param [out] to Output key + * @param [in] context Library context + * @param [in] from Key to be copied + * @param [out] to Output key * - * This function copies @a from->contents to @a to. - * Use krb5_free_keyblock_contents() to zero out and free @a to - * when it is no longer needed. + * This function copies the contents of @a from to @a to. Use + * krb5_free_keyblock_contents() to free @a to when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_copy_keyblock_contents(krb5_context context, const krb5_keyblock *from, krb5_keyblock *to); -/** Copy a krb5_creds structure. +/** + * Copy a krb5_creds structure. * - * @param [in] context Context structure - * @param [in] incred Credentials structure to be copied - * @param [out] outcred Copy of @a incred + * @param [in] context Library context + * @param [in] incred Credentials structure to be copied + * @param [out] outcred Copy of @a incred * - * This function copies the content of @a incred to @a outcred - * Use krb5_free_creds() to free @a outcred when it is no longer needed. + * This function creates a new credential with the contents of @a incred. Use + * krb5_free_creds() to free @a outcred when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_copy_creds(krb5_context context, const krb5_creds *incred, krb5_creds **outcred); -/** Copy a krb5_data object. +/** + * Copy a krb5_data object. * - * @param [in] context Context structure + * @param [in] context Library context * @param [in] indata Data object to be copied * @param [out] outdata Copy of @a indata * - * This function copies the content of @a indata to @a outdata + * This function creates a new krb5_data object with the contents of @a indata. * Use krb5_free_data() to free @a outdata when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_copy_data(krb5_context context, const krb5_data *indata, krb5_data **outdata); -/** Copy a principal. +/** + * Copy a principal. * - * @param [in] context Context structure - * @param [in] inprinc Principal to be copied - * @param [out] outprinc Copy of @a inprinc + * @param [in] context Library context + * @param [in] inprinc Principal to be copied + * @param [out] outprinc Copy of @a inprinc * - * This function copies the content of @a inprinc to @a outprinc - * Use krb5_free_principal() to free @a outprinc when it is no longer needed. + * This function creates a new principal structure with the contents of @a + * inprinc. Use krb5_free_principal() to free @a outprinc when it is no longer + * needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_copy_principal(krb5_context context, krb5_const_principal inprinc, krb5_principal *outprinc); -/** Copy an array of addresses. +/** + * Copy an array of addresses. * - * @param [in] context Context structure - * @param [in] inaddr Array of addresses to be copied - * @param [out] outaddr Copy of array of addresses + * @param [in] context Library context + * @param [in] inaddr Array of addresses to be copied + * @param [out] outaddr Copy of array of addresses * - * This function copies the content of @a inaddr to @a outaddr. + * This function creates a new address array containing a copy of @a inaddr. * Use krb5_free_addresses() to free @a outaddr when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_copy_addresses(krb5_context context, krb5_address *const *inaddr, krb5_address ***outaddr); -/** Copy a krb5_ticket structure. +/** + * Copy a krb5_ticket structure. * - * @param [in] context Context structure - * @param [in] from Ticket to be copied - * @param [out] pto Copy of ticket + * @param [in] context Library context + * @param [in] from Ticket to be copied + * @param [out] pto Copy of ticket * - * This function copies the content of @a from to @a pto - * Use krb5_free_ticket() to free @a pto when it is no longer needed. + * This function creates a new krb5_ticket structure containing the contents of + * @a from. Use krb5_free_ticket() to free @a pto when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_copy_ticket(krb5_context context, const krb5_ticket *from, krb5_ticket **pto); -/** Copy an array of authorization data structures. +/** + * Copy an authorization data list. * - * @param [in] context Context structure - * @param [in] in_authdat Array of @a krb5_authdata structures - * @param [out] out New array of @a krb5_authdata structures + * @param [in] context Library context + * @param [in] in_authdat List of @a krb5_authdata structures + * @param [out] out New array of @a krb5_authdata structures * - * This function copies the content of @a in_authdat to @a out - * Use krb5_free_authdata() to free @a out when it is no longer needed. + * This function creates a new authorization data list containing a copy of @a + * in_authdat, which must be null-terminated. Use krb5_free_authdata() to free + * @a out when it is no longer needed. * * @note The last array entry in @a in_authdat must be a NULL pointer. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_copy_authdata(krb5_context context, krb5_authdata *const *in_authdat, krb5_authdata ***out); -/** Merge two authdata arrays with fresh allocation. +/** + * Merge two authorization data lists into a new list. * - * @param [in] context Context structure - * @param [in] inauthdat1 1st array of @a krb5_authdata structures - * @param [in] inauthdat2 2d array of @a krb5_authdata structures - * @param [out] outauthdat New array of @a krb5_authdata structures + * @param [in] context Library context + * @param [in] inauthdat1 First list of @a krb5_authdata structures + * @param [in] inauthdat2 Second list of @a krb5_authdata structures + * @param [out] outauthdat Merged list of @a krb5_authdata structures * * Merge two authdata arrays, such as the array from a ticket * and authenticator. @@ -3377,7 +3378,7 @@ krb5_copy_authdata(krb5_context context, * @note The last array entry in @a inauthdat1 and @a inauthdat2 * must be a NULL pointer. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_merge_authdata(krb5_context context, @@ -3385,74 +3386,80 @@ krb5_merge_authdata(krb5_context context, krb5_authdata * const *inauthdat2, krb5_authdata ***outauthdat); -/** Copy a krb5_authenticator srtucture. +/** + * Copy a krb5_authenticator structure. * - * @param [in] context Context structure - * @param [in] authfrom krb5_authenticator structure to be copied - * @param [out] authto Copy of krb5_authenticator structure + * @param [in] context Library context + * @param [in] authfrom krb5_authenticator structure to be copied + * @param [out] authto Copy of krb5_authenticator structure * - * This function copies the content of @a authfrom to @a authto - * Use krb5_free_authenticator() to free @a authto when it is no longer needed. + * This function creates a new krb5_authenticator structure with the content of + * @a authfrom. Use krb5_free_authenticator() to free @a authto when it is no + * longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_copy_authenticator(krb5_context context, const krb5_authenticator *authfrom, krb5_authenticator **authto); -/** Copy a krb5_checksum structure. +/** + * Copy a krb5_checksum structure. * - * @param [in] context Context structure - * @param [in] ckfrom Checksum to be copied - * @param [out] ckto Copy of krb5_checksum structure + * @param [in] context Library context + * @param [in] ckfrom Checksum to be copied + * @param [out] ckto Copy of krb5_checksum structure * - * This function copies the content of @a ckfrom to @a ckto - * Use krb5_free_checksum() to free @a ckto when it is no longer needed. + * This function creates a new krb5_checksum structure with the contents of @a + * ckfrom. Use krb5_free_checksum() to free @a ckto when it is no longer + * needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_copy_checksum(krb5_context context, const krb5_checksum *ckfrom, krb5_checksum **ckto); -/** Generate a replay cache object for server use and open it. +/** + * Generate a replay cache object for server use and open it. * - * @param [in] context Context structure - * @param [in] piece Unique identifier for replay cache - * @param [out] rcptr Handle to an open rcache + * @param [in] context Library context + * @param [in] piece Unique identifier for replay cache + * @param [out] rcptr Handle to an open rcache * - * This function generates a replay cache name, allocates memory for its - * handle @a rcptr, and then opens it. Unique identifier @a piece is used - * to differentiate this replay cache from the others on the system and - * typically it is the first component of the principal name of the caller. - * The handle @a rcptr should be closed with krb5_rc_close(). - * Use krb5_rc_destroy() to destroy @a rcptr when it is no longer needed. + * This function generates a replay cache name based on @a piece and opens a + * handle to it. Typically @a piece is the first component of the service + * principal name. Use krb5_rc_close() to close @a rcptr when it is no longer + * needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_get_server_rcache(krb5_context context, const krb5_data *piece, krb5_rcache *rcptr); -/** Build a principal name using length-counted strings. +/** + * Build a principal name using length-counted strings. * - * @param [in] context Context structure + * @param [in] context Library context * @param [out] princ Principal name * @param [in] rlen Realm name length * @param [in] realm Realm name - * @param [in] ... List of arguments specifying length and content for each argument - * - * Call krb5_free_principal() to free allocated memory for principal when it is no longer needed. + * @param [in] ... List of unsigned int/char * components, followed by 0 * - * @note krb5_build_principal() and krb5_build_principal_va() perform the same task. - * krb5_build_principal() takes variadic arguments. - * krb5_build_principal_va() takes a pre-computed @a varargs pointer. + * This function creates a principal from a length-counted string and a + * variable-length list of length-counted components. The list of components + * ends with the first 0 length argument (so it is not possible to specify an + * empty component with this function). Call krb5_free_principal() to free + * allocated memory for principal when it is no longer needed. * * @code * Example of how to build principal WELLKNOWN/ANONYMOUS@R * krb5_build_principal_ext(context, &principal, strlen("R"), "R", - * strlen(KRB5_WELLKNOWN_NAMESTR), KRB5_WELLKNOWN_NAMESTR, - * strlen(KRB5_ANONYMOUS_PRINCSTR), KRB5_ANONYMOUS_PRINCSTR, 0); + * (unsigned int)strlen(KRB5_WELLKNOWN_NAMESTR), + * KRB5_WELLKNOWN_NAMESTR, + * (unsigned int)strlen(KRB5_ANONYMOUS_PRINCSTR), + * KRB5_ANONYMOUS_PRINCSTR, 0); * @endcode * * @retval @@ -3464,19 +3471,20 @@ krb5_error_code KRB5_CALLCONV_C krb5_build_principal_ext(krb5_context context, krb5_principal * princ, unsigned int rlen, const char * realm, ...); -/** Build a principal name using null-terminated strings. +/** + * Build a principal name using null-terminated strings. * - * @param [in] context Context structure - * @param [out] princ Principal name - * @param [in] rlen Realm name length - * @param [in] realm Realm name - * @param [in] ... List of len1, sl1, len2, sl2... + * @param [in] context Library context + * @param [out] princ Principal name + * @param [in] rlen Realm name length + * @param [in] realm Realm name + * @param [in] ... List of char * components, ending with NULL * * 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. - * krb5_build_principal_va() takes a pre-computed @a varargs pointer. + * @note krb5_build_principal() and krb5_build_principal_alloc_va() perform the + * same task. krb5_build_principal() takes variadic arguments. + * krb5_build_principal_alloc_va() takes a pre-computed @a varargs pointer. * * @code * Example of how to build principal H/S@R @@ -3499,25 +3507,7 @@ krb5_build_principal(krb5_context context, #endif ; #if KRB5_DEPRECATED -/** - * @param [in] context Context structure - * @param [out] princ Principal structure - * @param [in] rlen Realm name length - * @param [in] realm Realm name - * @param [in] ap @c va_list of argument - * - * @deprecated Replaced by krb5_build_principal() and krb5_build_principal_va(). - * - * Build a principal name, using a precomputed @c va_list. - * - * @note krb5_build_principal() and krb5_build_principal_va() perform the same task. - * krb5_build_principal() takes variadic arguments. - * krb5_build_principal_va() takes a pre-computed @a varargs pointer. - * - * Use krb5_free_principal() to free @a princ when it is no longer needed. - * - * @retval 0 Success; otherwise - Kerberos error codes - */ +/** @deprecated Replaced by krb5_build_principal_alloc_va(). */ KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV krb5_build_principal_va(krb5_context context, krb5_principal princ, @@ -3526,18 +3516,20 @@ krb5_build_principal_va(krb5_context context, va_list ap); #endif -/** Build a principal name, using a precomputed variable argument list +/** + * Build a principal name, using a precomputed variable argument list * - * @param [in] context Context structure - * @param [out] princ Principal structure. Locally allocated. - * @param [in] rlen Realm name length - * @param [in] realm Realm name - * @param [in] ap @c va_list of arguments + * @param [in] context Library context + * @param [out] princ Principal structure + * @param [in] rlen Realm name length + * @param [in] realm Realm name + * @param [in] ap List of char * components, ending with NULL * - * Similar to krb5_build_principal() this function builds a principal name, - * but its name components are specified as va_list. + * Similar to krb5_build_principal(), this function builds a principal name, + * but its name components are specified as a va_list. * - * Use krb5_free_principal() to deallocate the @a princ when it is no longer needed. + * Use krb5_free_principal() to deallocate @a princ when it is no longer + * needed. * * @code * Function usage example: @@ -3559,35 +3551,38 @@ krb5_build_principal_alloc_va(krb5_context context, const char *realm, va_list ap); -/** Convert a Kerberos V4 principal to a Kerberos V5 principal. +/** + * Convert a Kerberos V4 principal to a Kerberos V5 principal. * - * @param [in] context Context structure - * @param [in] name V4 name - * @param [in] instance V4 instance - * @param [in] realm Realm - * @param [out] princ V5 principal + * @param [in] context Library context + * @param [in] name V4 name + * @param [in] instance V4 instance + * @param [in] realm Realm + * @param [out] princ V5 principal * * This function builds a @a princ from V4 specification based on given input * @a name.instance\@realm. * * Use krb5_free_principal() to free @a princ when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_425_conv_principal(krb5_context context, const char *name, const char *instance, const char *realm, krb5_principal *princ); -/** Convert a Kerberos V5 principal to a Kerberos V4 principal. +/** + * Convert a Kerberos V5 principal to a Kerberos V4 principal. * - * @param [in] context Context structure - * @param [in] princ V5 Principal - * @param [out] name V4 principal's name to be filled in - * @param [out] inst V4 principal's instance name to be filled in - * @param [out] realm Principal's realm name to be filled in + * @param [in] context Library context + * @param [in] princ V5 Principal + * @param [out] name V4 principal's name to be filled in + * @param [out] inst V4 principal's instance name to be filled in + * @param [out] realm Principal's realm name to be filled in * - * This function separates a V5 principal @a princ into @a name, @a instance, and @a realm. + * This function separates a V5 principal @a princ into @a name, @a instance, + * and @a realm. * * @retval * 0 Success @@ -3606,11 +3601,12 @@ krb5_524_conv_principal(krb5_context context, krb5_const_principal princ, */ struct credentials; -/** Convert a Kerberos V5 credentials to a Kerberos V4 credentials +/** + * Convert a Kerberos V5 credentials to a Kerberos V4 credentials * * @note Not implemented * - * @retval KRB524_KRB4_DISABLED (always) + * @retval KRB524_KRB4_DISABLED (always) */ int KRB5_CALLCONV krb5_524_convert_creds(krb5_context context, krb5_creds *v5creds, @@ -3623,17 +3619,19 @@ krb5_524_convert_creds(krb5_context context, krb5_creds *v5creds, /* libkt.spec */ -/** Get a handle for a key table. +/** + * Get a handle for a key table. * - * @param [in] context Context structure - * @param [in] name Name of the key table - * @param [out] ktid Key table handle + * @param [in] context Library context + * @param [in] name Name of the key table + * @param [out] ktid Key table handle * - * Resolve the key table name @a name and fill in a handle identifying the key table. - * The key table is not opened. + * Resolve the key table name @a name and fill in a handle identifying the key + * table. The key table is not opened. * - * @note @a name must be of the form @c type:residual, where @a type must be a type known - * to the library and @a residual portion should be specific to the particular keytab type. + * @note @a name must be of the form @c type:residual, where @a type must be a + * type known to the library and @a residual portion should be specific to the + * particular keytab type. * * @sa krb5_kt_close() * @@ -3649,17 +3647,15 @@ krb5_524_convert_creds(krb5_context context, krb5_creds *v5creds, krb5_error_code KRB5_CALLCONV krb5_kt_resolve(krb5_context context, const char *name, krb5_keytab *ktid); -/** Get default key table name. +/** + * Get default key table name. * - * @param [in] context Context structure - * @param [in,out] name Key table name to be resolved - * @param [in] name_size Size of @a name to return + * @param [in] context Library context + * @param [in,out] name Key table name to be resolved + * @param [in] name_size Size of @a name to return * - * Fill @a name with the first @a name_size bytes of the name of the - * default key table for the current user. The name is obtained either - * from the environment variable KRB5_KTNAME or from @a default_keytab_name - * entry in @a libdefaults section of krb5 configuration file or - * falls back on the default keytab name for the OS. + * Fill @a name with the first @a name_size bytes of the name of the default + * key table for the current user. * * @sa MAX_KEYTAB_NAME_LEN * @@ -3673,10 +3669,11 @@ krb5_kt_resolve(krb5_context context, const char *name, krb5_keytab *ktid); krb5_error_code KRB5_CALLCONV krb5_kt_default_name(krb5_context context, char *name, int name_size); -/** Resolve default key table. +/** + * Resolve default key table. * - * @param [in] context Context structure - * @param [in,out] id Key table handle + * @param [in] context Library context + * @param [in,out] id Key table handle * * Fill @a keytab with the default key table's @a handle. * @@ -3688,26 +3685,20 @@ krb5_kt_default_name(krb5_context context, char *name, int name_size); krb5_error_code KRB5_CALLCONV krb5_kt_default(krb5_context context, krb5_keytab *id); -/** Free the contents of a key table entry. +/** + * Free the contents of a key table entry. * - * @param [in] context Context structure - * @param [in] entry Key table entry whose contents are to be freed + * @param [in] context Library context + * @param [in] entry Key table entry whose contents are to be freed * * @note The pointer is not freed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_free_keytab_entry_contents(krb5_context context, krb5_keytab_entry *entry); -/** Free the contents of a key table entry. - * - * @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. - */ +/** @deprecated Use krb5_free_keytab_entry_contents instead. */ krb5_error_code KRB5_CALLCONV krb5_kt_free_entry(krb5_context context, krb5_keytab_entry *entry); @@ -3715,11 +3706,12 @@ krb5_kt_free_entry(krb5_context context, krb5_keytab_entry *entry); /* remove and add are functions, so that they can return NOWRITE if not a writable keytab */ -/** Remove an entry from a key table. +/** + * Remove an entry from a key table. * - * @param [in] context Context structure - * @param [in] id Key table handle - * @param [in] entry Entry to remove from key table + * @param [in] context Library context + * @param [in] id Key table handle + * @param [in] entry Entry to remove from key table * * @retval * 0 Success @@ -3731,11 +3723,12 @@ krb5_kt_free_entry(krb5_context context, krb5_keytab_entry *entry); krb5_error_code KRB5_CALLCONV krb5_kt_remove_entry(krb5_context context, krb5_keytab id, krb5_keytab_entry *entry); -/** Add a new entry to a key table. +/** + * Add a new entry to a key table. * - * @param [in] context Context structure - * @param [in] id Key table handle - * @param [in] entry Entry to be added + * @param [in] context Library context + * @param [in] id Key table handle + * @param [in] entry Entry to be added * * @retval * 0 Success @@ -3749,13 +3742,14 @@ krb5_kt_remove_entry(krb5_context context, krb5_keytab id, krb5_keytab_entry *en krb5_error_code KRB5_CALLCONV krb5_kt_add_entry(krb5_context context, krb5_keytab id, krb5_keytab_entry *entry); -/** Convert a principal name into the default salt for that principal. +/** + * Convert a principal name into the default salt for that principal. * - * @param [in] context Context structure - * @param [in] pr Principal name - * @param [out] ret Default salt for @a pr to be filled in + * @param [in] context Library context + * @param [in] pr Principal name + * @param [out] ret Default salt for @a pr to be filled in * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV_WRONG krb5_principal2salt(krb5_context context, @@ -3764,16 +3758,17 @@ krb5_principal2salt(krb5_context context, /* libcc.spec */ -/** Resolve a credentials cache name. +/** + * Resolve a credential cache name. * - * @param [in] context Context structure - * @param [in] name Credentials cache name to be resolved - * @param [out] cache Credentials cache handle + * @param [in] context Library context + * @param [in] name Credential cache name to be resolved + * @param [out] cache Credential cache handle * - * Fills in @a cache with a @a cache handle that corresponds to the name in @a name. - * @a name should be of the form @c type:residual, - * 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. + * Fills in @a cache with a @a cache handle that corresponds to the name in @a + * name. @a name should be of the form @c type:residual, 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. * * @code * Example: krb5_cc_resolve(context, "MEMORY:C_", &cache); @@ -3787,11 +3782,12 @@ krb5_principal2salt(krb5_context context, krb5_error_code KRB5_CALLCONV krb5_cc_resolve(krb5_context context, const char *name, krb5_ccache *cache); -/** Duplicate ccache handle. +/** + * Duplicate ccache handle. * - * @param [in] context Context structure - * @param [in] in Credentials cache handle to be duplicated - * @param [out] out Credentials cache handle + * @param [in] context Library context + * @param [in] in Credential cache handle to be duplicated + * @param [out] out Credential cache handle * * Create a new handle referring to the same cache as @a in. * The new handle and @a in can be closed independently. @@ -3799,26 +3795,28 @@ krb5_cc_resolve(krb5_context context, const char *name, krb5_ccache *cache); krb5_error_code KRB5_CALLCONV krb5_cc_dup(krb5_context context, krb5_ccache in, krb5_ccache *out); -/** Return the name of the default credentials cache. +/** + * Return the name of the default credential cache. * - * @param [in] context Context structure + * @param [in] context Library context * * Try the environment variable KRB5CCNAME first then, if it is not set, * fall back on the default ccache name for the OS. * * @return - * Name of default credentials cache for the current user. + * Name of default credential cache for the current user. */ const char *KRB5_CALLCONV krb5_cc_default_name(krb5_context context); -/** Set the default credentials cache name. +/** + * Set the default credential cache name. * - * @param [in,out] context Context structure - * @param [in] name Default credentials cache name + * @param [in,out] context Library context + * @param [in] name Default credential cache name * - * This function frees the old default credentials cache name and then - * sets it to @a name. + * This function frees the old default credential cache name and then sets it + * to @a name. * * @retval * 0 Success @@ -3830,42 +3828,48 @@ krb5_cc_default_name(krb5_context context); krb5_error_code KRB5_CALLCONV krb5_cc_set_default_name(krb5_context context, const char *name); -/** Resolve the default crendentials cache name. +/** + * Resolve the default crendentials cache name. * - * @param [in,out] context Context structure - * @param [out] ccache Pointer to credentials cache name + * @param [in,out] context Library context + * @param [out] ccache Pointer to credential cache name * * @retval * 0 Success * @retval * KV5M_CONTEXT Bad magic number for @c _krb5_context structure * @retval - * KRB5_FCC_INTERNAL The name of the default credentials cache cannot be obtained + * KRB5_FCC_INTERNAL The name of the default credential cache cannot be + * obtained * @return * Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cc_default(krb5_context context, krb5_ccache *ccache); -/** Copy a credentials cache. +/** + * Copy a credential cache. * - * @param [in] context Context structure - * @param [in] incc Credentials cache to be copied - * @param [out] outcc Copy of credentials cache to be filled in + * @param [in] context Library context + * @param [in] incc Credential cache to be copied + * @param [out] outcc Copy of credential cache to be filled in * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cc_copy_creds(krb5_context context, krb5_ccache incc, krb5_ccache outcc); -/** Get some configuration for the credential cache in the cache. +/** + * Get a configuration value from a credential cache. * - * @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() + * @param [in] context Library context + * @param [in] id Credential cache handle + * @param [in] principal Configuration for this principal; + * if NULL, global for the whole cache + * @param [in] key Name of config variable + * @param [out] data Data to be fetched + * + * Use krb5_free_data_contents() to free @a data when it is no longer needed. * * @retval * 0 Success @@ -3877,18 +3881,19 @@ krb5_cc_get_config(krb5_context context, krb5_ccache id, krb5_const_principal principal, const char *key, krb5_data *data); -/** Store some configuration for the credential cache in the cache. +/** + * Store a configuration value in a credential cache. * - * @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] key name under which the configuraion is stored. - * @param [in] data data to store. If NULL, old configuration is removed. + * @param [in] context Library context + * @param [in] id Credential cache handle + * @param [in] principal Configuration for a specific principal; + * if NULL, global for the whole cache + * @param [in] key Name of config variable + * @param [in] data Data to store, or NULL to remove * * @note Existing configuration under the same key is over-written. * - * @warning Before version 1.10 @a data was assumed to be always non-zero + * @warning Before version 1.10 @a data was assumed to be always non-null. * * @retval * 0 Success @@ -3900,206 +3905,212 @@ krb5_cc_set_config(krb5_context context, krb5_ccache id, krb5_const_principal principal, const char *key, krb5_data *data); -/** Test whether a principal is a configuration principal. +/** + * Test whether a principal is a configuration principal. * - * @param [in] context a Keberos context - * @param [in] principal principal to check if it a configuration principal + * @param [in] context Library context + * @param [in] principal Principal to check * * @return - * TRUE (non zero) if the principal is a configuration principal - * (generated part of krb5_cc_set_config()); FALSE (zero) otherwise. + * @c TRUE if the principal is a configuration principal (generated part of + * krb5_cc_set_config()); @c FALSE otherwise. */ krb5_boolean KRB5_CALLCONV krb5_is_config_principal(krb5_context context, krb5_const_principal principal); /* krb5_free.c */ -/** Free the storage assigned to a principal. +/** + * Free the storage assigned to a principal. * - * @param [in] context Context structure - * @param [in] val Principal to be freed + * @param [in] context Library context + * @param [in] val Principal to be freed */ void KRB5_CALLCONV krb5_free_principal(krb5_context context, krb5_principal val); -/** Free a krb5_authenticator structure. +/** + * Free a krb5_authenticator structure. * - * @param context Context structure - * @param [in] val Pointer to authenticator structure to be freed + * @param [in] context Library context + * @param [in] val Authenticator structure to be freed * - * This function frees the storage assigned to @a krb5_authenticator - * structure, and then @a val itself is released. + * This function frees the contents of @a val and the structure itself. */ void KRB5_CALLCONV krb5_free_authenticator(krb5_context context, krb5_authenticator *val); -/** Free the data stored in array of addresses. +/** + * Free the data stored in array of addresses. * - * @param context Context structure - * @param [in] val Array of addresses to be freed + * @param [in] context Library context + * @param [in] val Array of addresses to be freed * - * This function frees the storage assigned to array of @a krb5_address - * structures, and then @a val itself is released. + * This function frees the contents of @a val and the array itself. * * @note The last entry in the array must be a NULL pointer. */ void KRB5_CALLCONV krb5_free_addresses(krb5_context context, krb5_address **val); -/** Free the storage assigned to array of authentication data. +/** + * Free the storage assigned to array of authentication data. * - * @param context Context structure - * @param [in] val Array of authentication data to be freed + * @param [in] context Library context + * @param [in] val Array of authentication data to be freed * - * This function frees the storage assigned to array of @a krb5_authdata - * structures, and then @a val itself is released. + * This function frees the contents of @a val and the array itself. * * @note The last entry in the array must be a NULL pointer. */ void KRB5_CALLCONV krb5_free_authdata(krb5_context context, krb5_authdata **val); -/** Free a ticket. +/** + * Free a ticket. * - * @param [in] context Context structure - * @param [in] val Ticket to be freed + * @param [in] context Library context + * @param [in] val Ticket to be freed * - * This function frees the storage assigned to @a krb5_ticket - * structure, and then @a val itself is released. + * This function frees the contents of @a val and the structure itself. */ void KRB5_CALLCONV krb5_free_ticket(krb5_context context, krb5_ticket *val); -/** Free an error allocated by either krb5_read_error() or krb5_sendauth(). +/** + * Free an error allocated by krb5_read_error() or krb5_sendauth(). * - * @param [in] context Context structure - * @param [in] val Error data structure to be freed + * @param [in] context Library context + * @param [in] val Error data structure to be freed * - * This function frees the storage assigned to @a krb5_error - * structure, and then @a val itself is released. + * This function frees the contents of @a val and the structure itself. */ void KRB5_CALLCONV krb5_free_error(krb5_context context, register krb5_error *val); -/** Free a credentials structure and invalidate its pointer. +/** + * Free a krb5_creds structure. * - * @param [in] context Context structure - * @param [in] val Pointer to data structure to be freed + * @param [in] context Library context + * @param [in] val Credential structure to be freed. * - * This function frees the storage assigned to @a krb5_creds - * structure, and then @a val itself is released. + * This function frees the contents of @a val and the structure itself. */ void KRB5_CALLCONV krb5_free_creds(krb5_context context, krb5_creds *val); -/** Zero out the session key and free the credentials structure. +/** + * Free the contents of a krb5_creds structure. * - * @param [in] context Context structure - * @param [in,out] val Pointer to the data structure to be freed + * @param [in] context Library context + * @param [in] val Credential structure to free contents of * - * @note The pointer to @a val is not freed. + * This function frees the contents of @a val but not the structure itself. */ void KRB5_CALLCONV krb5_free_cred_contents(krb5_context context, krb5_creds *val); -/** Free a krb5_checksum structure. +/** + * Free a krb5_checksum structure. * - * @param context Context structure - * @param [in] val Pointer to data structure to be freed + * @param [in] context Library context + * @param [in] val Checksum structure to be freed * - * This function frees the contents of a @a val and then releases @a val itself. + * This function frees the contents of @a val and the structure itself. */ void KRB5_CALLCONV krb5_free_checksum(krb5_context context, register krb5_checksum *val); -/** Free the contents of a krb5_checksum structure. +/** + * Free the contents of a krb5_checksum structure. * - * @param context Context structure - * @param [in] val Checksum structure to be released + * @param [in] context Library context + * @param [in] val Checksum structure to free contents of * - * @note The pointer to @a val itself is not freed. + * This function frees the contents of @a val but not the structure itself. */ void KRB5_CALLCONV krb5_free_checksum_contents(krb5_context context, register krb5_checksum *val); -/** Free the storage assigned to a keyblock. +/** + * Free a krb5_keyblock structure. * - * @param [in] context Context structure - * @param [in] val Keyblock to be freed + * @param [in] context Library context + * @param [in] val Keyblock to be freed * - * This function zeros out and frees the contents of a @a val and then - * releases @a val itself. + * This function frees the contents of @a val and the structure itself. */ void KRB5_CALLCONV krb5_free_keyblock(krb5_context context, register krb5_keyblock *val); -/** Zero out and free the contents of a keyblock. +/** + * Free the contents of a krb5_keyblock structure. * - * @param [in] context Context structure - * @param [in] key Keyblock to be freed + * @param [in] context Library context + * @param [in] key Keyblock to be freed * - * @note The pointer to @a key itself is not freed. + * This function frees the contents of @a key but not the structure itself. */ void KRB5_CALLCONV krb5_free_keyblock_contents(krb5_context context, register krb5_keyblock *key); -/** Free the subkey keyblock. +/** + * Free a krb5_ap_rep_enc_part structure. * - * @param [in] context Context structure - * @param [in] val Pointer to data structure to be freed + * @param [in] context Library context + * @param [in] val AP-REP enc part to be freed * - * This function frees the storage assigned to the decrypted portion of an AP-REP - * message, and then @a val itself is released. + * This function frees the contents of @a val and the structure itself. */ void KRB5_CALLCONV krb5_free_ap_rep_enc_part(krb5_context context, krb5_ap_rep_enc_part *val); -/** Free the storage assigned to a krb5_data object +/** + * Free a krb5_data structure. * - * @param context Context structure - * @param [in] val Pointer to data structure to be freed + * @param [in] context Library context + * @param [in] val Data structure to be freed * - * This function zeros out and frees the contents field of @a val and then - * frees @a val itself. + * This function frees the contents of @a val and the structure itself. */ void KRB5_CALLCONV krb5_free_data(krb5_context context, krb5_data *val); -/** Zero out and free the contents of a krb5_data object +/** + * Free the contents of a krb_data structure. * - * @param context Context structure - * @param [in] val Pointer to data structure to be freed + * @param [in] context Library context + * @param [in] val Data structure to free contents of * - * @note The pointer to @a val itself is not freed. + * This function frees the contents of @a val but not the structure itself. */ void KRB5_CALLCONV krb5_free_data_contents(krb5_context context, krb5_data *val); -/** Free a simple character name string returned by krb5_unparse_name(). - * - * @param context Context structure - * @param [in] val Pointer to name string to be freed +/** + * Free a string representation of a principal. * - * @note The pointer to @a val itself is not freed. + * @param [in] context Library context + * @param [in] val Name string to be freed */ void KRB5_CALLCONV krb5_free_unparsed_name(krb5_context context, char *val); -/** Free an array of checksum types. - * - * @param context Context structure - * @param [in] val Array of checksum types to be freed +/** + * Free an array of checksum types. * - * @note Make sure the checksum contents have already been freed. + * @param [in] context Library context + * @param [in] val Array of checksum types to be freed */ void KRB5_CALLCONV krb5_free_cksumtypes(krb5_context context, krb5_cksumtype *val); /* From krb5/os but needed but by the outside world */ -/** Retrieve the system time of day, in sec and ms, since the epoch. +/** + * Retrieve the system time of day, in sec and ms, since the epoch. * - * @param [in] context Context structure - * @param [out] seconds System timeofday, seconds portion - * @param [out] microseconds System timeofday, microseconds portion + * @param [in] context Library context + * @param [out] seconds System timeofday, seconds portion + * @param [out] microseconds System timeofday, microseconds portion * * This function retrieves the system time of day with the context * specific time offset adjustment. @@ -4115,13 +4126,14 @@ krb5_error_code KRB5_CALLCONV krb5_us_timeofday(krb5_context context, krb5_timestamp *seconds, krb5_int32 *microseconds); -/** Retrieve the current time with context specific time offset adjustment. +/** + * Retrieve the current time with context specific time offset adjustment. * - * @param [in] context Context structure - * @param [in,out] timeret Timestamp to fill in + * @param [in] context Library context + * @param [in,out] timeret Timestamp to fill in * - * This function retrieves the system time of day with the context - * specific time offset adjustment. + * This function retrieves the system time of day with the context specific + * time offset adjustment. * * @retval * 0 Success @@ -4131,28 +4143,28 @@ krb5_us_timeofday(krb5_context context, krb5_error_code KRB5_CALLCONV krb5_timeofday(krb5_context context, register krb5_timestamp *timeret); -/** Return all protocol addresses for this host. - * - * @param [in] context Context structure - * @param [out] addr Array of krb5_address pointers. - * The last entry is a NULL pointer +/** + * Return all interface addresses for this host. * - * Compile-time configuration flags indicate which protocol family addresses - * can be returned. Both AF_INET and AF_INET6 are currently supported. + * @param [in] context Library context + * @param [out] addr Array of krb5_address pointers, ending with + * NULL * * Use krb5_free_addresses() to free @a addr when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_os_localaddr(krb5_context context, krb5_address ***addr); -/** Retrieve the default realm. +/** + * Retrieve the default realm. * - * @param [in] context Context structure - * @param [out] lrealm Pointer to default realm for the host + * @param [in] context Library context + * @param [out] lrealm Default realm name * - * Retrieves the default realm to be used if no user-specified realm is available. + * Retrieves the default realm to be used if no user-specified realm is + * available. * * Use krb5_free_default_realm() to free @a lrealm when it is no longer needed. * @@ -4164,10 +4176,11 @@ krb5_os_localaddr(krb5_context context, krb5_address ***addr); krb5_error_code KRB5_CALLCONV krb5_get_default_realm(krb5_context context, char **lrealm); -/** Override the default realm for the specified context. +/** + * Override the default realm for the specified context. * - * @param [in,out] context Context structure - * @param [in] lrealm Realm name for the default realm + * @param [in] context Library context + * @param [in] lrealm Realm name for the default realm * * If @a lrealm is NULL, clear the default realm setting. * @@ -4179,35 +4192,36 @@ krb5_get_default_realm(krb5_context context, char **lrealm); krb5_error_code KRB5_CALLCONV krb5_set_default_realm(krb5_context context, const char *lrealm); -/** Free the default realm string returned by krb5_get_default_realm(). +/** + * Free a default realm string returned by krb5_get_default_realm(). * - * @param context Context structure - * @param [in] lrealm Realm to be freed + * @param [in] context Library context + * @param [in] lrealm Realm to be freed */ void KRB5_CALLCONV krb5_free_default_realm(krb5_context context, char *lrealm); -/** Generate a full principal name from a service name. +/** + * Generate a full principal name from a service name. * - * @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 + * @param [in] context Library context + * @param [in] hostname Host name, or NULL to use local host + * @param [in] sname Service name, or NULL to use @c "host" + * @param [in] type Principal type + * @param [out] ret_princ Generated principal * - * This function converts a given @a hostname and @a sname into @a krb5_principal - * structure @a ret_princ. + * This function converts a @a hostname and @a sname into @a krb5_principal + * structure @a ret_princ. The returned principal will be of the form @a + * sname\/hostname\@REALM where REALM is determined by krb5_get_host_realm(). + * In some cases this may be the referral (empty) realm. * * The @a type can be one of the following: * - * @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 - * sname//hostname\@LOCAL.REALM. Most applications should use @a KRB5_NT_SRV_HOST. + * @li @c KRB5_NT_SRV_HOST canonicalizes the host name before looking up the + * realm and generating the principal. * - * @li @c KRB5_NT_UNKNOWN generates a principal name with - * 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. + * @li @c KRB5_NT_UNKNOWN accepts the hostname as given, and does not + * canonicalize it. * * Use krb5_free_principal to free @a ret_princ when it is no longer needed. * @@ -4220,15 +4234,16 @@ krb5_error_code KRB5_CALLCONV krb5_sname_to_principal(krb5_context context, const char *hostname, const char *sname, krb5_int32 type, krb5_principal *ret_princ); -/** Test whether a principal matches a matching principal. +/** + * Test whether a principal matches a matching principal. * - * @param [in] context Context structure - * @param [in] matching Matching principal - * @param [in] princ Principal to test + * @param [in] context Library context + * @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 + * @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 former has the same non-empty (and non-ignored) * components of the latter. * @@ -4243,14 +4258,15 @@ krb5_boolean KRB5_CALLCONV krb5_sname_match(krb5_context context, krb5_const_principal matching, krb5_const_principal princ); -/** Change a password for an existing Kerberos account. +/** + * Change a password for an existing Kerberos account. * - * @param [in] context Context structure - * @param [in] creds Kerberos credentials to the kadmin/changepw service - * @param [in] newpw New password - * @param [out] result_code A numeric error code - * @param [out] result_code_string String equivalent to @a result_code - * @param [out] result_string Change password response from the KDC + * @param [in] context Library context + * @param [in] creds Credentials for kadmin/changepw service + * @param [in] newpw New password + * @param [out] result_code Numeric error code from server + * @param [out] result_code_string String equivalent to @a result_code + * @param [out] result_string Change password response from the KDC * * Change the password for the existing principal identified by @a creds. * @@ -4262,27 +4278,28 @@ krb5_sname_match(krb5_context context, krb5_const_principal matching, * @li KRB5_KPASSWD_AUTHERROR (3) - Authentication error * @li KRB5_KPASSWD_SOFTERROR (4) - Password change rejected * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_change_password(krb5_context context, krb5_creds *creds, char *newpw, int *result_code, krb5_data *result_code_string, krb5_data *result_string); -/** Set a password for a principal using specified credentials. +/** + * Set a password for a principal using specified credentials. * - * @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 + * @param [in] context Library context + * @param [in] creds Credentials for kadmin/changepw service + * @param [in] newpw New password + * @param [in] change_password_for Change the password for this principal + * @param [out] result_code Numeric error code from server + * @param [out] result_code_string String equivalent to @a result_code + * @param [out] result_string Data returned from the remote system * - * 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. + * 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 @@ -4303,30 +4320,31 @@ 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); -/** Set a password for a principal using cached credentials. +/** + * Set a password for a principal using cached credentials. * - * @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 + * @param [in] context Library context + * @param [in] ccache Credential cache + * @param [in] newpw New password + * @param [in] change_password_for Change the password for this principal + * @param [out] result_code Numeric error code from server + * @param [out] result_code_string String equivalent to @a result_code + * @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. + * @a newpw for the principal @a change_password_for. It implements RFC 3244 + * set password operation (interoperable with MS Windows implementations) using + * the credential 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 default principal in @a ccache. If @a change_password_for is non null, + * @note If @a change_password_for is set to NULL, the change is performed on + * the default principal in @a ccache. If @a change_password_for is non null, * the change is performed on the specified principal. * + * @sa krb5_set_password() + * * @retval * 0 Success * @return @@ -4338,9 +4356,10 @@ krb5_set_password_using_ccache(krb5_context context, krb5_ccache ccache, int *result_code, krb5_data *result_code_string, krb5_data *result_string); -/** Retrieve configuration data from the context. +/** + * Retrieve configuration profile from the context. * - * @param [in] context Context structure + * @param [in] context Library context * @param [out] profile Pointer to data read from a configuration file * * This function creates a new @a profile object that reflects profile @@ -4384,36 +4403,39 @@ krb5_get_in_tkt_with_keytab(krb5_context context, krb5_flags options, #endif /* KRB5_DEPRECATED */ -/** Parse and decrypt a @c KRB_AP_REQ message. +/** + * Parse and decrypt a @c KRB_AP_REQ message. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context. A new authentication - * context is returned if NULL is specified + * @param [in] context Library context + * @param [in,out] auth_context Pre-existing or newly created auth context * @param [in] inbuf AP-REQ message to be parsed - * @param [in] server Server's principal for the @a ticket. - * Use NULL for the principal of the @a keytab - * @param [in] keytab Key table that contains a decryption key. - * Use NULL for the default key table. + * @param [in] server Matching principal for server, or NULL to + * allow any principal in keytab + * @param [in] keytab Key table, or NULL to use the default * @param [out] ap_req_options If non-null, the AP-REQ flags on output - * @param [out] ticket Returned ticket from the AP-REQ message. - * Use NULL to specify that no ticket needed. + * @param [out] ticket If non-null, ticket from the AP-REQ message * * This function parses, decrypts and verifies a AP-REQ message from @a inbuf * and stores the authenticator in @a auth_context. * - * If a keyblock is present in the @a auth_context, it is used to decrypt - * the ticket in AP-REQ message. (This is useful for user-to-user authentication.) - * Otherwise, the decryption key is obtained from the @a keytab. + * If a keyblock is present in the @a auth_context, it is used to decrypt the + * ticket in AP-REQ message. (This is useful for user-to-user authentication.) + * Otherwise, the decryption key is obtained from the @a keytab. If @a keytab + * is iterable, all of its key entries it will be tried against the ticket; + * otherwise, the server principal in the ticket will be looked up in the + * keytab and that key will be tried. * * The client specified in the decrypted authenticator must match the client - * specified in the @a ticket. + * specified in the decrypted ticket. If @a server is non-null, the key in + * which the ticket is encrypted must correspond to a principal in @a keytab + * matching @a server according to the rules of krb5_sname_match(). * - * If the @a remote_addr field of @a auth_context is set, the request must came + * If the @a remote_addr field of @a auth_context is set, the request must come * from that address. * - * If a replay cache handle is provided in the @a auth_context, the authenticator - * and @a ticket are verified against it. If no conflicts found, the new - * authenticator is then stored in the replay cash of @a auth_context. + * If a replay cache handle is provided in the @a auth_context, the + * authenticator and ticket are verified against it. If no conflict is found, + * the new authenticator is then stored in the replay cash of @a auth_context. * * Various other checks are performed on the decoded data, including * cross-realm policy, clockskew, and ticket validation times. @@ -4425,7 +4447,7 @@ krb5_get_in_tkt_with_keytab(krb5_context context, krb5_flags options, * * Use krb5_free_ticket() to free @a ticket when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_rd_req(krb5_context context, krb5_auth_context *auth_context, @@ -4433,19 +4455,18 @@ krb5_rd_req(krb5_context context, krb5_auth_context *auth_context, krb5_keytab keytab, krb5_flags *ap_req_options, krb5_ticket **ticket); -/** Retrieve a service key from a key table. +/** + * Retrieve a service key from a key table. * - * @param [in] context Context structure - * @param [in] keyprocarg Name of a key table or NULL to use default key table + * @param [in] context Library context + * @param [in] keyprocarg Name of a key table (NULL to use default name) * @param [in] principal Service principal - * @param [in] vno Key version number; use 0 to specify the key with - * the highest version number - * @param [in] enctype Key encryption type; use a keytype of 0 if - * encryption type does not matter - * @param [out] key Returned service key + * @param [in] vno Key version number (0 for highest available) + * @param [in] enctype Encryption type (0 for any type) + * @param [out] key Service key from key table * - * Open and search the specified key table for the entry identified by @a principal, @a enctype, - * and @a vno. If no key is found, return an error code. + * Open and search the specified key table for the entry identified by @a + * principal, @a enctype, and @a vno. If no key is found, return an error code. * * The default key table is used, unless @a keyprocarg is non-null. * @a keyprocarg designates a specific key table. @@ -4461,13 +4482,14 @@ krb5_kt_read_service_key(krb5_context context, krb5_pointer keyprocarg, krb5_principal principal, krb5_kvno vno, krb5_enctype enctype, krb5_keyblock **key); -/** Format a @c KRB-SAFE message. +/** + * Format a @c KRB-SAFE message. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] userdata User data in the message - * @param [out] outbuf Formatted @c KRB-SAFE buffer - * @param [out] outdata Replay data. Specify NULL if not needed + * @param [in] context Library context + * @param [in,out] auth_context Authentication context + * @param [in] userdata User data in the message + * @param [out] outbuf Formatted @c KRB-SAFE buffer + * @param [out] outdata Replay data. Specify NULL if not needed * * This function creates an integrity protected @c KRB-SAFE message * using data supplied by the application. @@ -4476,59 +4498,57 @@ krb5_kt_read_service_key(krb5_context context, krb5_pointer keyprocarg, * can be used to seed the checksum, full addresses (host and port) for * the sender and receiver, and KRB5_AUTH_CONTEXT_ flags. * - * The @a local_addr field of @a auth_context is used to - * form the addresses used in the KRB-SAFE message. The remote_addr is optional; - * if the receiver's address is unknown, it can be replaced by NULL. + * The local address in @a auth_context must be set, and is used to form the + * sender address used in the KRB-SAFE message. The remote address is + * optional; if specified, it will be used to form the receiver address used in + * the message. + * + * If @c KRB5_AUTH_CONTEXT_DO_TIME flag is set in the @a auth_context, an entry + * describing the message is entered in the replay cache @a + * auth_context->rcache which enables the caller to detect if this message is + * reflected by an attacker. If @c KRB5_AUTH_CONTEXT_DO_TIME is not set, the + * replay cache is not used. + * + * If either @c KRB5_AUTH_CONTEXT_DO_SEQUENCE or @c + * KRB5_AUTH_CONTEXT_RET_SEQUENCE is set, the @a auth_context local sequence + * number will be placed in @a outdata as its sequence number. * - * @note The @a local_addr argument is mandatory. * @note The @a outdata argument is required if KRB5_AUTH_CONTEXT_RET_TIME or * KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context. * - * If @c KRB5_AUTH_CONTEXT_DO_TIME flag is set in the @a auth_context, an entry - * describing the message is entered in the replay cache @a auth_context->rcache - * which enables the caller to detect if this message is sent back by an attacker. - * If @c KRB5_AUTH_CONTEXT_DO_TIME is not set, the replay cache is not used. - * - * If either @c KRB5_AUTH_CONTEXT_DO_SEQUENCE or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE - * is set, the @a auth_context local sequence number will be placed in the - * @a outdata as its sequence number. + * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_mk_safe(krb5_context context, krb5_auth_context auth_context, const krb5_data *userdata, krb5_data *outbuf, krb5_replay_data *outdata); -/** Format a @c KRB-PRIV message. +/** + * Format a @c KRB-PRIV message. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] userdata User data for @c KRB-PRIV message - * @param [out] outbuf Formatted @c KRB-PRIV message - * @param [out] outdata Replay cache handle. Specify NULL if not needed. + * @param [in] context Library context + * @param [in,out] auth_context Authentication context + * @param [in] userdata User data for @c KRB-PRIV message + * @param [out] outbuf Formatted @c KRB-PRIV message + * @param [out] outdata Replay cache handle (NULL if not needed) * * This function is similar to krb5_mk_safe(), but the message is encrypted and * integrity-protected, not just integrity-protected. * - * The @a remote_addr and @a remote_port fields of @a auth_context are - * optional; @a local_addr, is mandatory. If the receiver's address is unknown, - * it can be replaced by NULL. - * - * The encryption type is taken either from @a send_subkey or, if NULL, - * from @a key field of @a auth_context. + * The local address in @a auth_context must be set, and is used to form the + * sender address used in the KRB-SAFE message. The remote address is + * optional; if specified, it will be used to form the receiver address used in + * the message. * - * If the @a i_vector field in @a auth_context is non-null, it is used - * as an initialization vector for the encryption (if the chosen encryption - * type supports initialization vectors), and its contents are replaced with - * the last block of encrypted data upon return. - * - * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE - * flag is set in @a auth_context, the @a outdata is required. + * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c + * KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in @a auth_context, the @a + * outdata is required. * * @note The flags from @a auth_context specify whether sequence numbers or - * timestamps will be used to identify the message. - * Valid values are: + * timestamps will be used to identify the message. Valid values are: + * * @li @c KRB5_AUTH_CONTEXT_DO_TIME - Use timestamps in @a outdata * @li @c KRB5_AUTH_CONTEXT_RET_TIME - Copy timestamp to @a outdata. * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE - Use local sequence numbers from @@ -4537,28 +4557,27 @@ krb5_mk_safe(krb5_context context, krb5_auth_context auth_context, * @a auth_context as a sequence number * in the encrypted message @a outbuf. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_mk_priv(krb5_context context, krb5_auth_context auth_context, const krb5_data *userdata, krb5_data *outbuf, krb5_replay_data *outdata); -/** Client function for @c sendauth protocol. +/** + * Client function for @c sendauth protocol. * - * @param [in] context Context structure + * @param [in] context Library context * @param [in,out] auth_context Authentication context * @param [in] fd File descriptor that describes network socket * @param [in] appl_version Application protocol version to be matched * with the receiver's application version - * @param [in] client Client principal name; - * ignored if @a in_creds is non-null - * @param [in] server Server principal name; - * ignored if @a in_creds is non-null + * @param [in] client Client principal + * @param [in] server Server principal * @param [in] ap_req_options AP_OPTS options * @param [in] in_data Data to be sent to the server - * @param [in] in_creds Input credentials, or NULL to use @a ccache instead - * @param [in] ccache Credentials cache + * @param [in] in_creds Input credentials, or NULL to use @a ccache + * @param [in] ccache Credential cache * @param [out] error If non-null, contains KRB_ERROR message * returned from server * @param [out] rep_result If non-null and @a ap_req_options is @@ -4566,33 +4585,33 @@ krb5_mk_priv(krb5_context context, krb5_auth_context auth_context, * of mutual authentication exchange * @param [out] out_creds If non-null, the retrieved credentials * - * This function performs the exchange by sending and receiving messages over fd. + * This function performs the client side of a sendauth/recvauth exchange by + * sending and receiving messages over @a fd. * - * If @a in_creds is NULL: - * @li @a server must be non-null - * @li @a client can be NULL. If @a client is NULL, the credentials cache - * default principal is used. + * Credentials may be specified in three ways: * - * If @a in_creds is non-null, @a in_creds->client and @a in_creds->server must be - * filled in. If the other structure fields are filled in with valid credentials, - * @a in_creds->ticket.length must be zero. + * @li If @a in_creds is NULL, credentials are obtained with + * krb5_get_credentials() using the principals @a client and @a server. @a + * server must be non-null; @a client may NULL to use the default principal of + * @a ccache. * - * If @a in_creds->ticket.length is nonzero, @a in_creds is used - * as the credentials to send to the server, and @a ccache is ignored. Otherwise, - * @a ccache is used. + * @li If @a in_creds is non-null but does not contain a ticket, credentials + * for the exchange are obtained with krb5_get_credentials() using @a in_creds. + * In this case, the values of @a client and @a server are unused. * - * @a ccache specifies the credential cache to use only when @a in_creds is - * NULL or @a in_creds->ticket.length is zero. + * @li If @a in_creds is a complete credentials structure, it used directly. + * In this case, the values of @a client, @a server, and @a ccache are unused. * - * If the server is using a different application protocol than that specified in - * @a appl_version, an error will be returned. + * If the server is using a different application protocol than that specified + * in @a appl_version, an error will be returned. * - * Use krb5_free_creds() to free @a out_creds, krb5_free_ap_rep_enc_part() to free - * @a rep_result and krb5_free_error() to free @a error when they are no longer needed. + * Use krb5_free_creds() to free @a out_creds, krb5_free_ap_rep_enc_part() to + * free @a rep_result, and krb5_free_error() to free @a error when they are no + * longer needed. * * @sa krb5_recvauth() * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_sendauth(krb5_context context, krb5_auth_context *auth_context, @@ -4602,50 +4621,49 @@ krb5_sendauth(krb5_context context, krb5_auth_context *auth_context, krb5_error **error, krb5_ap_rep_enc_part **rep_result, krb5_creds **out_creds); -/** Server function for @a sendauth protocol. +/** + * Server function for @a sendauth protocol. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] fd File descriptor - * @param [in] appl_version Application protocol version to be matched - * against the client's application version - * @param [in] server Server principal; if NULL - any server principal - * @param [in] flags Additional specifications - * @param [in] keytab Decryption key - * @param [out] ticket Ticket (optional); only filled in with client - * ticket data if non-null + * @param [in] context Library context + * @param [in,out] auth_context Authentication context + * @param [in] fd File descriptor + * @param [in] appl_version Application protocol version to be matched + * against the client's application version + * @param [in] server Server principal (NULL for any in @a keytab) + * @param [in] flags Additional specifications + * @param [in] keytab Key table containing service keys + * @param [out] ticket Ticket (NULL if not needed) * - * This function performs the exchange by sending and receiving messages over fd. + * This function performs the srever side of a sendauth/recvauth exchange by + * sending and receiving messages over @a fd. * * Use krb5_free_ticket() to free @a ticket when it is no longer needed. * * @sa krb5_sendauth() * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_recvauth(krb5_context context, krb5_auth_context *auth_context, krb5_pointer fd, char *appl_version, krb5_principal server, krb5_int32 flags, krb5_keytab keytab, krb5_ticket **ticket); -/** Server function for @a sendauth protocol with version parameter. +/** + * Server function for @a sendauth protocol with version parameter. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] fd File descriptor - * @param [in] appl_version Application protocol version to be matched - * against the client's application version - * @param [in] server Server principal; if NULL - any server principal - * @param [in] flags Additional specifications - * @param [in] keytab Decryption key - * @param [out] ticket Ticket (optional); only filled in with client - * ticket data if non-null - * @param [out] version If not NULL, contains the @c sendauth version + * @param [in] context Library context + * @param [in,out] auth_context Authentication context + * @param [in] fd File descriptor + * @param [in] server Server principal (NULL for any in @a keytab) + * @param [in] flags Additional specifications + * @param [in] keytab Decryption key + * @param [out] ticket Ticket (NULL if not needed) + * @param [out] version sendauth protocol version (NULL if not needed) * * This function is similar to krb5_recvauth() with the additional output - * information place into @a version buffer. + * information place into @a version. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_recvauth_version(krb5_context context, @@ -4657,24 +4675,23 @@ krb5_recvauth_version(krb5_context context, krb5_ticket **ticket, krb5_data *version); -/** Format a @c KRB-CRED message for an array of credentials. +/** + * Format a @c KRB-CRED message for an array of credentials. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] ppcreds NULL terminated array of credentials - * @param [out] ppdata Encoded credentials - * @param [out] outdata Replay cache handle. - * Specify NULL if not needed + * @param [in] context Library context + * @param [in,out] auth_context Authentication context + * @param [in] ppcreds Null-terminated array of credentials + * @param [out] ppdata Encoded credentials + * @param [out] outdata Replay cache information (NULL if not needed) * * This function takes an array of credentials @a ppcreds and formats * a @c KRB-CRED message @a ppdata to pass to krb5_rd_cred(). * * @note If the KRB5_AUTH_CONTEXT_RET_TIME or KRB5_AUTH_CONTEXT_RET_SEQUENCE - * flag is set in @a auth_context, the @a outdata is required. + * flag is set in @a auth_context, @a outdata is required. * - * The message will be decrypted and verified using the @a recv_subkey - * field of @a auth_context if it is non-null, or by the @a key field if - * @a recv_subkey is null or fails to decrypt the message. + * The message will be encrypted using the send subkey of @a auth_context if it + * is present, or the session key otherwise. * * @retval * 0 Success @@ -4690,21 +4707,18 @@ krb5_mk_ncred(krb5_context context, krb5_auth_context auth_context, krb5_creds **ppcreds, krb5_data **ppdata, krb5_replay_data *outdata); -/** Format a @c KRB-CRED message for a single set of credentials. +/** + * Format a @c KRB-CRED message for a single set of credentials. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] pcreds Pointer to credentials - * @param [out] ppdata Encoded credentials - * @param [out] outdata Replay cache handle + * @param [in] context Library context + * @param [in,out] auth_context Authentication context + * @param [in] pcreds Pointer to credentials + * @param [out] ppdata Encoded credentials + * @param [out] outdata Replay cache data (NULL if not needed) * * This is a convenience function that calls krb5_mk_ncred() with a single set * of credentials. * - * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE - * flag is set in @a auth_context, the @a outdata is required. Otherwise it can be - * NULL. - * * @retval * 0 Success * @retval @@ -4719,47 +4733,46 @@ krb5_mk_1cred(krb5_context context, krb5_auth_context auth_context, krb5_creds *pcreds, krb5_data **ppdata, krb5_replay_data *outdata); -/** Read and validate a @c KRB-CRED message. +/** + * Read and validate a @c KRB-CRED message. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] pcreddata @c KRB-CRED message - * @param [out] pppcreds Array of forwarded credentials - * @param [out] outdata Replay data - * Specify NULL if not needed. + * @param [in] context Library context + * @param [in,out] auth_context Authentication context + * @param [in] pcreddata @c KRB-CRED message + * @param [out] pppcreds Null-terminated array of forwarded credentials + * @param [out] outdata Replay data (NULL if not needed) * - * @note The @a outdata argument is required if RB5_AUTH_CONTEXT_RET_TIME or + * @note The @a outdata argument is required if KRB5_AUTH_CONTEXT_RET_TIME or * KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.` * - * The keyblock used to decrypt the data and verify the integrity of the message - * is taken from fields @a recv_subkey or @a key in @a auth_context. - * The keyblock is chosen in the preceding order by the first one that is non-null. - * However, if the first non-null key fails to decrypt the message, the second one - * will be used. + * @a pcreddata will be decrypted using the receiving subkey if it is present + * in @a auth_context, or the session key if the receiving subkey is not + * present or fails to decrypt the message. * * Use krb5_free_tgt_creds() to free @a pppcreds when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_rd_cred(krb5_context context, krb5_auth_context auth_context, krb5_data *pcreddata, krb5_creds ***pppcreds, krb5_replay_data *outdata); -/** Get a forwarded TGT and format a @c KRB-CRED message. +/** + * Get a forwarded TGT and format a @c KRB-CRED message. * - * @param [in] context Context structure - * @param [in] auth_context Authentication context with the key to encrypt @a outbuf - * @param [in] rhost Remote host - * @param [in] client Client principal for the TGT - * @param [in] server Server principal for the TGT - * @param [in] cc Credentials cache handle. - * @param [in] forwardable Boolean indicating whether TGT should be forwardable - * @param [out] outbuf Output buffer containing the TGT to be filled in + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [in] rhost Remote host + * @param [in] client Client principal of TGT + * @param [in] server Principal of server to receive TGT + * @param [in] cc Credential cache handle (NULL to use default) + * @param [in] forwardable Whether TGT should be forwardable + * @param [out] outbuf KRB-CRED message * - * Get a TGT for use at the remote host @a rhost. - * If @a rhost is NULL, @a server service principal will be used. - * If @a cc is NULL, the default credential cache will be used. + * Get a TGT for use at the remote host @a rhost and format it into a KRB-CRED + * message. If @a rhost is NULL and @a server is of type @c KRB5_NT_SRV_HST, + * the second component of @a server will be used. * * @retval * 0 Success @@ -4779,80 +4792,89 @@ 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); -/** Create and initialize an authentication context. +/** + * Create and initialize an authentication context. * - * @param [in] context Context structure - * @param [out] auth_context Authentication context + * @param [in] context Library context + * @param [out] auth_context Authentication context * - * The @c _krb5_auth_context contains all data pertinent to the various authentication routines. + * This function creates an authentication context to hold configuration and + * state relevant to krb5 functions for authenticating principals and + * protecting messages once authentication has occurred. * - * By default, @a flags for the context are set to enable the use of the replay cache - * (KRB5_AUTH_CONTEXT_DO_TIME) but not sequence numbers. - * Use krb5_auth_con_setflags() to change the flags. + * By default, flags for the context are set to enable the use of the replay + * cache (KRB5_AUTH_CONTEXT_DO_TIME) but not sequence numbers. Use + * krb5_auth_con_setflags() to change the flags. * * The allocated @a auth_context must be freed with krb5_auth_con_free() when * it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_init(krb5_context context, krb5_auth_context *auth_context); -/** Free a @c _krb5_auth_context structure. +/** + * Free a krb5_auth_context structure. * - * @param [in] context Context structure - * @param [in] auth_context Authentication context to be freed + * @param [in] context Library context + * @param [in] auth_context Authentication context to be freed * - * This function frees @a auth_context allocated by krb5_auth_con_init() + * This function frees an auth context allocated by krb5_auth_con_init(). * * @retval 0 (always) */ krb5_error_code KRB5_CALLCONV krb5_auth_con_free(krb5_context context, krb5_auth_context auth_context); -/** Set a flags field in a krb5_auth_context structure. +/** + * Set a flags field in a krb5_auth_context structure. * - * @param context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] flags Flags bit mask + * @param [in] context Library context + * @param [in,out] auth_context Authentication context + * @param [in] flags Flags bit mask * * Valid values for @a flags are: - * @li @c KRB5_AUTH_CONTEXT_DO_TIME Use timestamps - * @li @c KRB5_AUTH_CONTEXT_RET_TIME Save timestamps to output structure - * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers - * @li @c KRB5_AUTH_RET_SEQUENCE Copy sequence numbers to output structure + * @li @c KRB5_AUTH_CONTEXT_DO_TIME Use timestamps + * @li @c KRB5_AUTH_CONTEXT_RET_TIME Save timestamps + * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers + * @li @c KRB5_AUTH_CONTEXT_RET_SEQUENCE Save sequence numbers * * @retval 0 (always) */ krb5_error_code KRB5_CALLCONV krb5_auth_con_setflags(krb5_context context, krb5_auth_context auth_context, krb5_int32 flags); -/** Retrieve a flags field from a krb5_auth_context structure. +/** + * Retrieve flags from a krb5_auth_context structure. * - * @param context Context structure - * @param [in] auth_context Authentication context - * @param [out] flags Flags bit mask + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [out] flags Flags bit mask * * Valid values for @a flags are: - * @li @c KRB5_AUTH_CONTEXT_DO_TIME Use timestamps in the message - * @li @c KRB5_AUTH_CONTEXT_RET_TIME Save timestamps to output structure. - * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers in the message - * @li @c KRB5_AUTH_RET_SEQUENCE Copy sequence numbers to output structure. - * + * @li @c KRB5_AUTH_CONTEXT_DO_TIME Use timestamps + * @li @c KRB5_AUTH_CONTEXT_RET_TIME Save timestamps + * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers + * @li @c KRB5_AUTH_CONTEXT_RET_SEQUENCE Save sequence numbers * * @retval 0 (always) */ krb5_error_code KRB5_CALLCONV -krb5_auth_con_getflags(krb5_context context, krb5_auth_context auth_context, krb5_int32 *flags); +krb5_auth_con_getflags(krb5_context context, krb5_auth_context auth_ + krb5_int32 *flags); -/** Set checksum_function related fields in krb5_auth_contex structure. +/** + * Set a checksum callback in an auth context. * - * @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 + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [in] func Checksum callback + * @param [in] data Callback argument * - * The checksum data is received when krb5_mk_req_extended() calls it. + * Set a callback to obtain checksum data in krb5_mk_req(). The callback will + * be invoked after the subkey and local sequence number are stored in @a + * auth_context. * * @retval 0 (always) */ @@ -4862,12 +4884,13 @@ krb5_auth_con_set_checksum_func( krb5_context context, krb5_mk_req_checksum_func func, void *data); -/** Get checksum_function related fields from krb5_auth_contex structure. +/** + * Get the checksum callback from an auth context. * - * @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 + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [out] func Checksum callback + * @param [out] data Callback argument * * @retval 0 (always) */ @@ -4877,81 +4900,83 @@ krb5_auth_con_get_checksum_func( krb5_context context, krb5_mk_req_checksum_func *func, void **data); -/** Sep the local and remote addresses in a krb5_auth_context structure. +/** + * Set the local and remote addresses in an auth context. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] local_addr Local address - * @param [in] remote_addr Remote address + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [in] local_addr Local address + * @param [in] remote_addr Remote address * - * This function releases the storage assigned to the contents of - * the local and remote addresses of @a auth_context structure and - * then sets them to @a local_addr and @a remote_addr respectively. + * This function releases the storage assigned to the contents of the local and + * remote addresses of @a auth_context and then sets them to @a local_addr and + * @a remote_addr respectively. * * @sa krb5_auth_con_genaddrs() * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV_WRONG krb5_auth_con_setaddrs(krb5_context context, krb5_auth_context auth_context, krb5_address *local_addr, krb5_address *remote_addr); -/** Retrieve address fields from a krb5_auth_con structure. - * - * @param [in] context Context structure - * @param [in] auth_context Authentication context - * @param [out] local_addr Local address; if NULL - not requested - * @param [out] remote_addr Remote address; if NULL - not requested +/** + * Retrieve address fields from an auth context. * - * If @a local_addr or @a remote_addr is non-null, the buffers are freed and - * then newly allocated. + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [out] local_addr Local address (NULL if not needed) + * @param [out] remote_addr Remote address (NULL if not needed) * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_getaddrs(krb5_context context, krb5_auth_context auth_context, krb5_address **local_addr, krb5_address **remote_addr); -/** Set local and remote port fields in a krb5_auth_context structure. +/** + * Set local and remote port fields in an auth context. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] local_port Local port - * @param [in] remote_port Remote port + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [in] local_port Local port + * @param [in] remote_port Remote port * - * This function releases the storage assigned to the contents of - * the local and remote ports of @a auth_context structure and - * then sets them to @a local_port and @a remote_port respectively. + * This function releases the storage assigned to the contents of the local and + * remote ports of @a auth_context and then sets them to @a local_port and @a + * remote_port respectively. * * @sa krb5_auth_con_genaddrs() * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_setports(krb5_context context, krb5_auth_context auth_context, krb5_address *local_port, krb5_address *remote_port); -/** Set an encryption key field in a krb5_auth_context structure. +/** + * Set the session key in an auth context. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] keyblock User key + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [in] keyblock User key * - * @retval 0 Success. Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_setuseruserkey(krb5_context context, krb5_auth_context auth_context, krb5_keyblock *keyblock); -/** Retrieve an encryption key from a krb5_auth_context structure. +/** + * Retrieve the session key from an auth context as a keyblock. * - * @param [in] context Context structure - * @param [in] auth_context Authentication context - * @param [out] keyblock Keyblock structure containing a key + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [out] keyblock Session key * - * This function allocates the output @a keyblock and populates it with the - * content of @a ac->send_key. - * Use krb5_free_keyblock() to free @a keyblock when it it no longer needed + * This function creates a keyblock containing the session key from @a + * auth_context. Use krb5_free_keyblock() to free @a keyblock when it is no + * longer needed * * @retval 0 Success. Otherwise - Kerberos error codes */ @@ -4959,14 +4984,15 @@ krb5_error_code KRB5_CALLCONV krb5_auth_con_getkey(krb5_context context, krb5_auth_context auth_context, krb5_keyblock **keyblock); -/** Get a copy of an encryption key from a krb5_auth_context structure. +/** + * Retrieve the session key from an auth context. * - * @param context Context structure - * @param [in] auth_context Authentication context - * @param [in,out] key Output key structure to be filled in + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [out] key Session key * - * This function populates the output @a key with the - * content of @a auth_context->send_subkey. + * This function sets @a key to the session key from @a auth_context. Use + * krb5_k_free_key() to release @a key when it is no longer needed. * * @retval 0 (always) */ @@ -4974,72 +5000,77 @@ krb5_error_code KRB5_CALLCONV krb5_auth_con_getkey_k(krb5_context context, krb5_auth_context auth_context, krb5_key *key); -/** Retrieve a send_subkey keyblock from a krb5_auth_context structure. +/** + * Retrieve the send subkey from an auth context as a keyblock. * - * @param [in] ctx Context structure - * @param [in] ac Authentication context - * @param [out] keyblock Key block structure. + * @param [in] ctx Library context + * @param [in] ac Authentication context + * @param [out] keyblock Send subkey * - * This function allocates the output @a keyblock and populates it with the - * content of @a ac->send_subkey. - * Use krb5_free_keyblock() to free @a keyblock when it is no longer needed. + * This function creates a keyblock containing the send subkey from @a + * auth_context. Use krb5_free_keyblock() to free @a keyblock when it is no + * longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_getsendsubkey(krb5_context ctx, krb5_auth_context ac, krb5_keyblock **keyblock); -/** Get a copy of a send_subkey key from a krb5_auth_context structure. +/** + * Retrieve the send subkey from an auth context. * - * @param ctx Context structure - * @param [in] ac Authentication context - * @param [in,out] key Key structure to be filled in + * @param [in] ctx Library context + * @param [in] ac Authentication context + * @param [out] key Send subkey * - * This function populates the output @a key with the - * content of @a auth_context->send_subkey. + * This function sets @a key to the send subkey from @a auth_context. Use + * krb5_k_free_key() to release @a key when it is no longer needed. * - * @retval 0 (always) + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_getsendsubkey_k(krb5_context ctx, krb5_auth_context ac, krb5_key *key); -/** Retrieve a recv_subkey keyblock from a krb5_auth_context structure. +/** + * Retrieve the receiving subkey from an auth context as a keyblock. * - * @param ctx Context structure - * @param [in] ac Authentication context - * @param [out] keyblock Key block structure + * @param [in] ctx Library context + * @param [in] ac Authentication context + * @param [out] keyblock Receiving subkey * - * This function populates the output @a keyblock with the - * content of @a auth_context->recv_subkey. - * Use krb5_free_keyblock() to free @a keyblock when it is no longer needed. + * This function creates a keyblock containing the receiving subkey from @a + * auth_context. Use krb5_free_keyblock() to free @a keyblock when it is no + * longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_getrecvsubkey(krb5_context ctx, krb5_auth_context ac, krb5_keyblock **keyblock); -/** Get a copy of a recv_subkey key from a krb5_auth_context structure. +/** + * Retrieve the receiving subkey from an auth context as a keyblock. * - * @param ctx Context structure - * @param [in] ac Authentication context - * @param [in,out] key Key block structure to be filled in + * @param [in] ctx Library context + * @param [in] ac Authentication context + * @param [out] key Receiving subkey * - * This function populates the output @a key with the - * content of @a auth_context->recv_subkey. + * This function sets @a key to the receiving subkey from @a auth_context. Use + * krb5_k_free_key() to release @a key when it is no longer needed. * - * @retval 0 (always) + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_getrecvsubkey_k(krb5_context ctx, krb5_auth_context ac, krb5_key *key); -/** Set a send_subkey field in a krb5_auth_context structure. +/** + * Set the send subkey in an auth context with a keyblock. * - * @param [in] ctx Context structure - * @param [in,out] ac Authentication context - * @param [in] keyblock Key to be stored in @a ac->send_subkey + * @param [in] ctx Library context + * @param [in] ac Authentication context + * @param [in] keyblock Send subkey * - * The old @a ac->send_subkey is freed. + * This function sets the send subkey in @a ac to a copy of @a keyblock. * * @retval 0 Success. Otherwise - Kerberos error codes */ @@ -5047,44 +5078,47 @@ krb5_error_code KRB5_CALLCONV krb5_auth_con_setsendsubkey(krb5_context ctx, krb5_auth_context ac, krb5_keyblock *keyblock); -/** Assign send_subkey field in a krb5_auth_context structure to a given key. +/** + * Set the send subkey in an auth context. * - * @param [in] ctx Context structure - * @param [in,out] ac Authentication context - * @param [in] key Key to be assigned to @a ac->send_subkey + * @param [in] ctx Library context + * @param [in] ac Authentication context + * @param [out] key Send subkey * - * The old @a ac->send_subkey is freed. - * The @a key reference count is incremented. + * This function sets the send subkey in @a ac to @a key, incrementing its + * reference count. * - * @retval 0 (always) + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_setsendsubkey_k(krb5_context ctx, krb5_auth_context ac, krb5_key key); -/** Set a recv_subkey field in a krb5_auth_context structure. +/** + * Set the receiving subkey in an auth context with a keyblock. * - * @param [in] ctx Context structure - * @param [in,out] ac Authentication context - * @param [in] keyblock Keyblock to be stored in @a ac->recv_subkey + * @param [in] ctx Library context + * @param [in] ac Authentication context + * @param [in] keyblock Receiving subkey * - * The old @a ac->recv_subkey is freed. + * This function sets the receiving subkey in @a ac to a copy of @a keyblock. * - * @retval 0 Success. Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_setrecvsubkey(krb5_context ctx, krb5_auth_context ac, krb5_keyblock *keyblock); -/** Assign recv_subkey field in a krb5_auth_context structure to a given key. +/** + * Set the receiving subkey in an auth context. * - * @param [in] ctx Context structure - * @param [in,out] ac Authentication context - * @param [in] key Key to be assigned to @a ac->send_subkey + * @param [in] ctx Library context + * @param [in] ac Authentication context + * @param [in] key Receiving subkey * - * The old @a ac->recv_subkey is freed. - * The @a key reference count is incremented. + * This function sets the receiving subkey in @a ac to @a key, incrementing its + * reference count. * - * @retval 0 (always) + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_setrecvsubkey_k(krb5_context ctx, krb5_auth_context ac, @@ -5102,35 +5136,35 @@ krb5_auth_con_getremotesubkey(krb5_context context, krb5_auth_context auth_conte krb5_keyblock **keyblock); #endif -/** Retrieve a local sequence number from a krb5_auth_context structure. +/** + * Retrieve the local sequence number from an auth context. * - * @param context Context structure - * @param [in] auth_context Authentication context - * @param [in,out] seqnumber Local sequence number to be filled in + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [out] seqnumber Local sequence number * - * Retrieve the local sequence number used during authentication and store - * it in the @a seqnumber. - * The @c KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a auth_context - * for this function to have an effect. + * Retrieve the local sequence number from @a auth_context and return it in @a + * seqnumber. The @c KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a + * auth_context for this function to be useful. * - * @retval 0 (always) + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_getlocalseqnumber(krb5_context context, krb5_auth_context auth_context, krb5_int32 *seqnumber); -/** Retrieve a remote sequence number from a krb5_auth_context structure. +/** + * Retrieve the remote sequence number from an auth context. * - * @param context Context structure - * @param [in] auth_context Authentication context - * @param [in,out] seqnumber Remote sequence number to be filled in + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [out] seqnumber Remote sequence number * - * Retrieve the remote sequence number used during authentication and store - * it in the @a seqnumber. - * The @c KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a auth_context - * for this function to have an effect. + * Retrieve the remote sequence number from @a auth_context and return it in @a + * seqnumber. The @c KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a + * auth_context for this function to be useful. * - * @retval 0 (always) + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_getremoteseqnumber(krb5_context context, krb5_auth_context auth_context, @@ -5146,25 +5180,32 @@ KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV krb5_auth_con_initivector(krb5_context context, krb5_auth_context auth_context); #endif -/** Set the replay cache field in a krb5_auth_context structure. +/** + * Set the replay cache in an auth context. * - * @param context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] rcache Replay cache haddle + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [in] rcache Replay cache haddle * - * @retval 0 (always) + * This function sets the replay cache in @a auth_context to @a rcache. @a + * rcache will be closed when @a auth_context is freed, so the caller should + * relinguish that responsibility. + * + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_setrcache(krb5_context context, krb5_auth_context auth_context, krb5_rcache rcache); -/** Retrieve rcache field from a krb5_auth_context structure. +/** + * Retrieve the replay cache from an auth context. * - * @param context Context structure - * @param [in] auth_context Authentication context - * @param [out] rcache Replay cache handle + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [out] rcache Replay cache handle * - * Set the output @a rcache to @a auth_context->rcache. + * This function fetches the replay cache from @a auth_context. The caller + * should not close @a rcache. * * @retval 0 (always) */ @@ -5172,15 +5213,15 @@ krb5_error_code KRB5_CALLCONV_WRONG krb5_auth_con_getrcache(krb5_context context, krb5_auth_context auth_context, krb5_rcache *rcache); -/** Retrieve an authenticator from the authentication context. - * - * @param [in] context Context structure - * @param [in] auth_context Authentication context - * @param [out] authenticator Authenticator +/** + * Retrieve the authenticator from an auth context. * - * Use krb5_free_authenticator() to free @a authenticator when it is no longer needed + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [out] authenticator Authenticator * - * @sa krb5_copy_authenticator() + * Use krb5_free_authenticator() to free @a authenticator when it is no longer + * needed. * * @retval 0 Success. Otherwise - Kerberos error codes */ @@ -5188,17 +5229,17 @@ krb5_error_code KRB5_CALLCONV krb5_auth_con_getauthenticator(krb5_context context, krb5_auth_context auth_context, krb5_authenticator **authenticator); -/** Set a checksum types field in a krb5_auth_context structure. +/** + * Set checksum type in an an auth context. * - * @param context Context structure - * @param [in,out] auth_context Authentication context - * @param [in] cksumtype Checksun type + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [in] cksumtype Checksum type * - * Sets @a auth_context->req_cksumtype field to @a cksumtype. - * This function is used to override the default checksum types defined in the - * configuration file. + * This function sets the checksum type in @a auth_context to be used by + * krb5_mk_req() for the authenticator checksum. * - * @retval 0 (always) + * @retval 0 Success. Otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_set_req_cksumtype(krb5_context context, krb5_auth_context auth_context, @@ -5215,30 +5256,26 @@ krb5_auth_con_set_req_cksumtype(krb5_context context, krb5_auth_context auth_con */ /** - * @brief Read a password from the keyboard input. + * @brief Read a password from keyboard input. * - * @param context Context structure [input] - * @param prompt First user prompt when reading password [input] - * @param prompt2 Second user prompt, or NULL to read password only once [input] - * @param return_pwd Returned password [output] - * @param size_return During input, maximum size of password; - * during output, total number of bytes in @a return_pwd [input, output] + * @param [in] context Library context + * @param [in] prompt First user prompt when reading password + * @param [in] prompt2 Second user prompt (NULL to prompt only once) + * @param [out] return_pwd Returned password + * @param [in,out] size_return On input, maximum size of password; on output, + * size of password read * - * The first *size_return bytes of the password entered are - * returned in @a return_pwd. If fewer than *size_return bytes are entered as a password, - * the remainder of @a return_pwd is zeroed. - * Upon success, the total number of bytes filled in is stored in *size_return. + * This function reads a password from keyboard input and stores it in @a + * return_pwd. @a size_return should be set by the caller to the amount of + * storage space available in @a return_pwd; on successful return, it will be + * set to the length of the password read. * - * @a prompt is the prompt for the first reading of a password. It is printed - * to the terminal, and then a password is read from the keyboard. No newlines - * or spaces are emitted between the prompt and the cursor, unless the newline/space - * is included in the prompt. + * @a prompt is printed to the terminal, followed by ": ", and then a password + * is read from the keyboard. * - * If @a prompt2 is a NULL pointer, the password is read only once. - * - * If @a prompt2 is set, it is used as a prompt to read another - * password in the same manner as described for the first password. After the - * second password is read, the two passwords are compared, and an error is returned if they are not identical. + * If @a prompt2 is NULL, the password is read only once. Otherwise, @a + * prompt2 is printed to the terminal and a second password is read. If the + * two passwords entered are not identical, KRB5_LIBOS_BADPWDMATCH is returned. * * Echoing is turned off when the password is read. * @@ -5254,19 +5291,21 @@ krb5_read_password(krb5_context context, const char *prompt, const char *prompt2, char *return_pwd, unsigned int *size_return); -/** Convert a principal name to a local name. +/** + * Convert a principal name to a local name. * - * @param [in] context Context structure - * @param [in] aname Principal name - * @param [in] lnsize_in Maximum length name to be filled into @a lname - * @param [out] lname Local name buffer to be filled in + * @param [in] context Library context + * @param [in] aname Principal name + * @param [in] lnsize_in Space available in @a lname + * @param [out] lname Local name buffer to be filled in * - * If @a aname isn't in one of the local realms an error is returned. - * If @a lnsize_in of @a lname is to small, an error is returned. + * If @a aname does not correspond to any local account, KRB5_LNAME_NOTRANS is + * returned. If @a lnsize_in is too small for the local name, + * KRB5_CONFIG_NOTENUFSPACE is returned. * * Local names, rather than principal names, can be used by programs that - * translate to an environment-specific name (for example, a user account - * name). The translation is null-terminated in all non-error returns. + * translate to an environment-specific name (for example, a user account + * name). * * @retval * 0 Success @@ -5279,19 +5318,21 @@ krb5_error_code KRB5_CALLCONV krb5_aname_to_localname(krb5_context context, krb5_const_principal aname, int lnsize_in, char *lname); -/** Get the Kerberos realm names for a host. +/** + * Get the Kerberos realm names for a host. * - * @param [in] context Context structure - * @param [in] host Host name - * @param [out] realmsp Pointer to list of realm names + * @param [in] context Library context + * @param [in] host Host name (or NULL) + * @param [out] realmsp Null-terminated list of realm names * - * Fill in @a realmsp with a pointer to an @c argv style list of names, - * terminated with a NULL pointer. - * If there are no known realms for the host, the filled-in pointer is set to NULL. + * Fill in @a realmsp with a pointer to a null-terminated list of realm names. + * If there are no known realms for the host, a list containing the referral + * (empty) realm is returned. * * If @a host is NULL, the local host's realms are determined. * - * Use krb5_free_host_realm() to release @a realmsp when it is no longer needed. + * Use krb5_free_host_realm() to release @a realmsp when it is no longer + * needed. * * @retval * 0 Success @@ -5305,21 +5346,28 @@ krb5_get_host_realm(krb5_context context, const char *host, char ***realmsp); /** * - * @param context Context structure [input, output] - * @param hdata - * @param realmsp + * @param [in] context Library context + * @param [in] hdata Host name (or NULL) + * @param [out] realmsp Null-terminated list of realm names * - * @todo part of referrals support? param descriptions? added pointer descr. + * Fill in @a realmsp with a pointer to a null-terminated list of realm names + * obtained through heuristics or insecure resolution methods which have lower + * priority than KDC referrals. + * + * If @a host is NULL, the local host's realms are determined. * + * Use krb5_free_host_realm() to release @a realmsp when it is no longer + * needed. */ krb5_error_code KRB5_CALLCONV krb5_get_fallback_host_realm(krb5_context context, krb5_data *hdata, char ***realmsp); -/** Free the memory allocated by krb5_get_host_realm(). +/** + * Free the memory allocated by krb5_get_host_realm(). * - * @param context Context structure - * @param [in] realmlist List of the realm names to be released + * @param [in] context Library context + * @param [in] realmlist List of realm names to be released * * @retval * 0 Success @@ -5329,219 +5377,231 @@ krb5_get_fallback_host_realm(krb5_context context, krb5_error_code KRB5_CALLCONV krb5_free_host_realm(krb5_context context, char *const *realmlist); -/** Determine if the principal is authorized to log in as a local user. - * - * @param [in] context Context structure - * @param [in] principal Principal name - * @param [in] luser Local username +/** + * Determine if a principal is authorized to log in as a local user. * - * Determine whether the @a principal is authorized to log in - * as a local user @a luser + * @param [in] context Library context + * @param [in] principal Principal name + * @param [in] luser Local username * - * If there is either no local account for @a luser or @a principal does not - * match luser\@realm for any default relam or it is not recorded in the existing - * .k5login, the @a luser is not authorized to log into an account. + * Determine whether @a principal is authorized to log in as a local user @a + * luser. * * @retval - * TRUE User is authorized to log in; FALSE otherwise + * TRUE Principal is authorized to log in as user; FALSE otherwise. */ krb5_boolean KRB5_CALLCONV krb5_kuserok(krb5_context context, krb5_principal principal, const char *luser); -/** Generate a full IP address from @a address and port. +/** + * Generate auth context addresses from a connected socket. * - * @param [in] context Context structure - * @param [in,out] auth_context Authentication context to be updated with - * new local and remote addresses. - * @param [in] infd Input socket file descriptor - * @param [in] flags Input flags, defined in @c KRB\$ROOT:[INCLUDE]KRB5. + * @param [in] context Library context + * @param [in] auth_context Authentication context + * @param [in] infd Connected socket descriptor + * @param [in] flags Flags * - * The values for the symbols can be OR'd together. Valid values are: + * This function sets the local and/or remote addresses in @a auth_context + * based on the local and remote endpoints of the socket @a infd. The + * following flags determine the operations performed: * * @li @c KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR + * Generate local address. * @li @c KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR + * Generate remote address. * @li @c KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR + * Generate local address and port. * @li @c KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR + * Generate remote address and port. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_auth_con_genaddrs(krb5_context context, krb5_auth_context auth_context, int infd, int flags); -/** Set time offset field in a krb5_context structure. - * - * @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 +/** + * Set time offset field in a krb5_context structure. * - * 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. + * @param [in] context Library context + * @param [in] seconds Real time, seconds portion + * @param [in] microseconds Real time, microseconds portion * - * Make sure to free the allocated memory when it is no longer needed. + * This function sets the time offset in @a context to the difference between + * the system time and the real time as determined by @a seconds and @a + * microseconds. * - * @retval 0 Success; Otherwise - 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); -/** Return the time offsets from the os context. +/** + * Return the time offsets from the os context. * - * @param [in] context Context structure - * @param [out] seconds Time offset from the OS context, seconds portion - * @param [out] microseconds Time offset from the OS context, microseconds portion + * @param [in] context Library context + * @param [out] seconds Time offset, seconds portion + * @param [out] microseconds Time offset, microseconds portion * - * This function returns the time offsets from @a context->os_context. + * This function returns the time offsets in @a context. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_get_time_offsets(krb5_context context, krb5_timestamp *seconds, krb5_int32 *microseconds); /* str_conv.c */ -/** Convert a string to an encryption type. +/** + * Convert a string to an encryption type. * - * @param [in] string String to convert to an encryption type - * @param [out] enctypep Encryption type to be filled in + * @param [in] string String to convert to an encryption type + * @param [out] enctypep Encryption type * - * @retval 0 Success; Otherwise - EINVAL + * @retval 0 Success; otherwise - EINVAL */ krb5_error_code KRB5_CALLCONV krb5_string_to_enctype(char *string, krb5_enctype *enctypep); -/** Convert a string to a salt type. +/** + * Convert a string to a salt type. * - * @param [in] string String to convert to an encryption type - * @param [out] salttypep Salt type to be filled in + * @param [in] string String to convert to an encryption type + * @param [out] salttypep Salt type to be filled in * - * @retval 0 Success; Otherwise - EINVAL + * @retval 0 Success; otherwise - EINVAL */ krb5_error_code KRB5_CALLCONV krb5_string_to_salttype(char *string, krb5_int32 *salttypep); -/** Convert a string to a checksum type. +/** + * Convert a string to a checksum type. * - * @param [in] string String to be converted - * @param [out] cksumtypep Checksum type to be filled in + * @param [in] string String to be converted + * @param [out] cksumtypep Checksum type to be filled in * - * @retval 0 Success; Otherwise - EINVAL + * @retval 0 Success; otherwise - EINVAL */ krb5_error_code KRB5_CALLCONV krb5_string_to_cksumtype(char *string, krb5_cksumtype *cksumtypep); -/** Convert a string to a timestamp. +/** + * Convert a string to a timestamp. * - * @param [in] string String to be converted - * @param [out] timestampp Pointer to timestamp + * @param [in] string String to be converted + * @param [out] timestampp Pointer to timestamp * - * @retval 0 Success; Otherwise - EINVAL + * @retval 0 Success; otherwise - EINVAL */ krb5_error_code KRB5_CALLCONV krb5_string_to_timestamp(char *string, krb5_timestamp *timestampp); -/** Convert a string to a delta time value. +/** + * Convert a string to a delta time value. * - * @param [in] string String to be converted - * @param [out] deltatp Delta time to be filled in + * @param [in] string String to be converted + * @param [out] deltatp Delta time to be filled in * - * @retval 0 Success; Otherwise - KRB5_DELTAT_BADFORMAT + * @retval 0 Success; otherwise - KRB5_DELTAT_BADFORMAT */ krb5_error_code KRB5_CALLCONV krb5_string_to_deltat(char *string, krb5_deltat *deltatp); -/** Convert a Kerberos encryption type value to a string. +/** + * Convert an encryption type to a string. * - * @param [in] enctype Encrytion type value to convert - * @param [out] buffer Buffer to hold encryption type string - * @param [in] buflen Maximum length of the string that can fit in @a buffer + * @param [in] enctype Encryption type + * @param [out] buffer Buffer to hold encryption type string + * @param [in] buflen Storage available in @a buffer * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_enctype_to_string(krb5_enctype enctype, char *buffer, size_t buflen); -/** Convert a Kerberos encryption type value to a name +/** + * Convert an encryption type to a name or alias. * - * @param [in] enctype Encrytion type value to convert - * @param [in] shortest Flag - * @param [out] buffer Buffer to hold encryption type string - * @param [in] buflen Maximum length of the string that can fit in @a buffer + * @param [in] enctype Encryption type + * @param [in] shortest Flag + * @param [out] buffer Buffer to hold encryption type string + * @param [in] buflen Storage available in @a buffer * * If @a shortest is FALSE, this function returns the enctype's canonical name - * (like "aes128-cts-hmac-sha1-96"). If @a shortest is TRUE, it return the enctype's - * shortest alias (like "aes128-cts"). + * (like "aes128-cts-hmac-sha1-96"). If @a shortest is TRUE, it return the + * enctype's shortest alias (like "aes128-cts"). * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_enctype_to_name(krb5_enctype enctype, krb5_boolean shortest, char *buffer, size_t buflen); -/** Convert a @a salttype to a string. +/** + * Convert a salt type to a string. * - * @param [in] salttype Salttype to convert - * @param [out] buffer Buffer to receive the converted string - * @param [in] buflen Length of @a buffer + * @param [in] salttype Salttype to convert + * @param [out] buffer Buffer to receive the converted string + * @param [in] buflen Storage available in @a buffer * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_salttype_to_string(krb5_int32 salttype, char *buffer, size_t buflen); -/** Convert a checksum type to a string. - * - * @param [in] cksumtype Checksum type to be converted - * @param [out] buffer Buffer to hold converted checksum type - * @param [in] buflen Maximum length of @a buffer +/** + * Convert a checksum type to a string. * - * The string is returned in the locale's appropriate date and time representation. + * @param [in] cksumtype Checksum type + * @param [out] buffer Buffer to hold converted checksum type + * @param [in] buflen Storage available in @a buffer * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_cksumtype_to_string(krb5_cksumtype cksumtype, char *buffer, size_t buflen); -/** Convert a timestamp to a string. +/** + * Convert a timestamp to a string. * - * @param [in] timestamp Timestamp to be converted - * @param [out] buffer Buffer to hold converted timestamp - * @param [in] buflen Maximum length of buffer + * @param [in] timestamp Timestamp to convert + * @param [out] buffer Buffer to hold converted timestamp + * @param [in] buflen Storage available in @a buffer * - * The string is returned in the locale's appropriate date and time representation. + * The string is returned in the locale's appropriate date and time + * representation. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_timestamp_to_string(krb5_timestamp timestamp, char *buffer, size_t buflen); -/** Convert a timestamp to a string, allowing optional padding in the output buffer. +/** + * Convert a timestamp to a string, with optional output padding * - * @param [in] timestamp Timestamp to convert - * @param [out] buffer Buffer to hold the converted timestamp - * @param [in] buflen Length of buffer - * @param [in] pad Optional value to pad @a buffer - * if converted timestamp does not fill it + * @param [in] timestamp Timestamp to convert + * @param [out] buffer Buffer to hold the converted timestamp + * @param [in] buflen Length of buffer + * @param [in] pad Optional value to pad @a buffer if converted + * timestamp does not fill it * - * This function also tries multiple possible formats if the default - * locale-specific fails. + * If @a pad is not NULL, @a buffer is padded out to @a buflen - 1 characters + * with the value of *@a pad. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_timestamp_to_sfstring(krb5_timestamp timestamp, char *buffer, size_t buflen, char *pad); -/** Convert a relative time value to a string. +/** + * Convert a relative time value to a string. * - * @param [in] deltat Relative time value to convert - * @param [out] buffer Buffer to hold time string - * @param [in] buflen Maximum length of string that fits in @a buffer + * @param [in] deltat Relative time value to convert + * @param [out] buffer Buffer to hold time string + * @param [in] buflen Storage available in @a buffer * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_deltat_to_string(krb5_deltat deltat, char *buffer, size_t buflen); @@ -5557,9 +5617,9 @@ krb5_deltat_to_string(krb5_deltat deltat, char *buffer, size_t buflen); /** Text for prompt used in prompter callback function. */ typedef struct _krb5_prompt { - 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 */ + char *prompt; /**< The prompt to show to the user */ + int hidden; /**< Boolean; informative prompt or hidden (e.g. PIN) */ + krb5_data *reply; /**< Must be allocated before call to prompt routine */ } krb5_prompt; /** Pointer to a prompter callback function. */ @@ -5569,19 +5629,23 @@ typedef krb5_error_code int num_prompts, krb5_prompt prompts[]); /** - * @brief Prompt user for password. + * Prompt user for password. + * + * @param [in] context Library context + * @param data Unused (callback argument) + * @param [in] name Name to output during prompt + * @param [in] banner Banner to output during prompt + * @param [in] num_prompts Number of prompts in @a prompts + * @param [in,out] prompts Array of output prompts and replies * - * @param context Context structure [input, output] - * @param data Unused - * @param name Name to output during prompt [input] - * @param banner Banner to output during prompt [input] - * @param num_prompts Number of prompts passed in @a prompts [input] - * @param prompts Array of krb5_prompt structures containing output prompts and replies [input, output] + * This function is intended to be used as a prompter callback for + * krb5_get_init_creds_password() or krb5_init_creds_init(). * - * Prompt the user for the password associated with the given principal name, - * and set the reply field of the @a prompts argument to the password input. The hidden - * flag in the @c prompts structure controls whether the password input is echoed back - * to the terminal. + * Writes @a name and @a banner to stdout, each followed by a newline, then + * writes each prompt field in the @a prompts array, followed by ": ", and sets + * the reply field of the entry to a line of input read from stdin. If the + * hidden flag is set for a prompt, then terminal echoing is turned off when + * input is read. * * @retval * 0 Success @@ -5622,13 +5686,16 @@ typedef struct _krb5_get_init_creds_opt { #define KRB5_GET_INIT_CREDS_OPT_ANONYMOUS 0x0400 -/** Allocate a new extended krb5_get_init_creds_opt structure. +/** + * Allocate a new initial credential options structure. * - * @param [in,out] context Context structure - * @param [out] opt Pointer to @c _krb5_get_init_creds_opt structure to be allocated + * @param [in] context Library context + * @param [out] opt New options structure * - * The caller of this function must call krb5_get_init_creds_opt_free() to free @a opt - * when it is no longer needed. + * This function is the preferred way to create an options structure for + * getting initial credentials, and is required to make use of certain options. + * Use krb5_get_init_creds_opt_free() to free @a opt when it is no longer + * needed. * * @retval 0 - Success; Kerberos errors otherwise. */ @@ -5636,10 +5703,11 @@ krb5_error_code KRB5_CALLCONV krb5_get_init_creds_opt_alloc(krb5_context context, krb5_get_init_creds_opt **opt); -/** Free an extended krb5_get_init_creds_opt structure. +/** + * Free initial credential options. * - * @param context Context structure - * @param [in] opt Pointer to @c _krb5_get_init_creds_opt structure to be freed + * @param [in] context Library context + * @param [in] opt Options structure to free * * @sa krb5_get_init_creds_opt_alloc() */ @@ -5647,165 +5715,137 @@ void KRB5_CALLCONV krb5_get_init_creds_opt_free(krb5_context context, krb5_get_init_creds_opt *opt); -/** Initialize a krb5_get_init_creds_opt structure. - * - * @param [in,out] opt Pointer to krb5_get_init_creds_opt structure to be initialized - * - * @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. - * - * Sets @a opt->flag to KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT - */ +/** @deprecated Use krb5_get_init_creds_opt_alloc() instead. */ void KRB5_CALLCONV krb5_get_init_creds_opt_init(krb5_get_init_creds_opt *opt); -/** Initialize the ticket lifetime field in krb5_get_init_creds_opt structure. - * - * @param [in,out] opt Options - * @param [in] tkt_life Ticket lifetime - * - * Sets KRB5_GET_INIT_CREDS_OPT_TKT_LIFE flag in @a opt +/** + * Set the ticket lifetime in initial credential options. * - * The @a opt pointer supplied to this function must have been - * obtained using krb5_get_init_creds_opt_alloc() + * @param [in] opt Options structure + * @param [in] tkt_life Ticket lifetime */ void KRB5_CALLCONV krb5_get_init_creds_opt_set_tkt_life(krb5_get_init_creds_opt *opt, krb5_deltat tkt_life); -/** Set the ticket renewal lifetime field in krb5_get_init_creds_opt structure. - * - * @param [in,out] opt Pointer to @a options field - * @param [in] renew_life Ticket renewal lifetime - * - * Sets KRB5_GET_INIT_CREDS_OPT_iRENEW_LIFE flag in @a opt +/** + * Set the ticket renewal lifetime in initial credential options. * - * The @a opt pointer supplied to this function must have been - * obtained using krb5_get_init_creds_opt_alloc() + * @param [in] opt Pointer to @a options field + * @param [in] renew_life Ticket renewal lifetime */ void KRB5_CALLCONV krb5_get_init_creds_opt_set_renew_life(krb5_get_init_creds_opt *opt, krb5_deltat renew_life); -/** Set the forwardable field in krb5_get_init_creds_opt structure. - * - * @param [in,out] opt Options - * @param [in] forwardable Flag indicating whether credentials are forwardable +/** + * Set or unset the forwardable flag in initial credential options. * - * 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() + * @param [in] opt Options structure + * @param [in] forwardable Whether credentials should be forwardable */ void KRB5_CALLCONV krb5_get_init_creds_opt_set_forwardable(krb5_get_init_creds_opt *opt, int forwardable); -/** Set the proxiable field in krb5_get_init_creds_opt structure. - * - * @param [in,out] opt Options - * @param [in] proxiable Flag indicating whether credentials are proxiable +/** + * Set or unset the proxiable flag in initial credential options. * - * 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() + * @param [in] opt Options structure + * @param [in] proxiable Whether credentials should be proxiable */ 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 +/** + * Set or unset the canonicalize flag in initial credential options. * - * The @a opt pointer supplied to this function must have been - * obtained using krb5_get_init_creds_opt_alloc() + * @param [in] opt Options structure + * @param [in] canonicalize Whether to canonicalize client principal */ void KRB5_CALLCONV krb5_get_init_creds_opt_set_canonicalize(krb5_get_init_creds_opt *opt, int canonicalize); -/** Set an anonymous flag in krb5_get_init_creds_opt structure. - * - * @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. +/** + * Set or unset the anonymous flag in initial credential options. * - * Sets KRB5_GET_INIT_CREDS_OPT_ANONYMOUS flag in @a opt. + * @param [in] opt Options structure + * @param [in] anonymous Whether to make an anonymous request * - * The @a opt pointer supplied to this function must have been - * obtained using krb5_get_init_creds_opt_alloc() + * 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. */ void KRB5_CALLCONV krb5_get_init_creds_opt_set_anonymous(krb5_get_init_creds_opt *opt, int anonymous); -/** Set an encryption list field in the krb5_get_init_creds_opt structure. - * - * @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 +/** + * Set allowable encryption types in initial credential options. * - * The @a opt pointer supplied to this function must have been - * obtained using krb5_get_init_creds_opt_alloc() + * @param [in] opt Options structure + * @param [in] etype_list Array of encryption types + * @param [in] etype_list_length Length of @a etype_list */ 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); -/** Set an address list field in krb5_get_init_creds_opt structure. - * - * @param [in,out] opt Options - * @param [in] addresses Addresses to be stored in the ticket +/** + * Set address restrictions in initial credential options. * - * Sets KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST flag in @a opt + * @param [in] opt Options structure + * @param [in] addresses Null-terminated array of addresses */ void KRB5_CALLCONV krb5_get_init_creds_opt_set_address_list(krb5_get_init_creds_opt *opt, krb5_address **addresses); -/** Set the preauth_list field in krb5_get_init_creds_opt structure. - * - * @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 +/** + * Set preauthentication types in initial credential options. * - * Sets KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST flag in @a opt + * @param [in] opt Options structure + * @param [in] preauth_list Array of preauthentication types + * @param [in] preauth_list_length Length of @a preauth_list * - * The @a opt pointer supplied to this function must have been - * obtained using krb5_get_init_creds_opt_alloc() + * This function can be used to perform optimistic preauthentication when + * getting initial credentials, in combination with + * krb5_get_init_creds_opt_set_salt() and krb5_get_init_creds_opt_set_pa(). */ 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. +/** + * Set salt for optimistic preauthentication in initial credential options. * - * @param [in,out] opt Options - * @param [in] salt Salt data + * @param [in] opt Options structure + * @param [in] salt Salt data * - * Sets KRB5_GET_INIT_CREDS_OPT_SALT flag in @a opt. + * When getting initial credentials with a password, a salt string it used to + * convert the password to a key. Normally this salt is obtained from the + * first KDC reply, but when performing optimistic preauthentication, the + * client may need to supply the salt string with this function. */ void KRB5_CALLCONV krb5_get_init_creds_opt_set_salt(krb5_get_init_creds_opt *opt, krb5_data *salt); -/** Set prompt for a password flag in krb5_get_init_creds_opt structure. +/** + * Set or unset change-password-prompt flag in initial credential options. * - * @param [in,out] opt Options - * @param [in] prompt Boolean prompt to change password + * @param [in] opt Options structure + * @param [in] prompt Whether to prompt to change password * - * Sets KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT flag in @a opt. + * This flag is on by default. It controls whether + * krb5_get_init_creds_password() will react to an expired-password error by + * prompting for a new password and attempting to change the old one. */ void KRB5_CALLCONV krb5_get_init_creds_opt_set_change_password_prompt(krb5_get_init_creds_opt *opt, @@ -5817,84 +5857,85 @@ typedef struct _krb5_gic_opt_pa_data { char *value; } krb5_gic_opt_pa_data; -/** Feed preauth plugins with the given options. +/** + * Supply options for preauthentication in initial credential options. * - * @param [in,out] context Context structure - * @param [in] opt Pre options - * @param [in] attr Pre attribute - * @param [in] value Pre value + * @param [in] context Library context + * @param [in] opt Options structure + * @param [in] attr Preauthentication option name + * @param [in] value Preauthentication option value * - * 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 order - * to check the validity of the option. - * The @a opt pointer supplied to this function must have been - * obtained using krb5_get_init_creds_opt_alloc() + * This function allows the caller to supply options for preauthentication. + * The values of @a attr and @a value are supplied to each preauthentication + * module available within @a context. */ krb5_error_code KRB5_CALLCONV krb5_get_init_creds_opt_set_pa(krb5_context context, krb5_get_init_creds_opt *opt, const char *attr, const char *value); -/** Set a location of FAST cache containing TGT based on cache name. +/** + * Set location of FAST armor ccache in initial credential options. + * + * @param [in] context Library context + * @param [in] opt Options + * @param [in] fast_ccache_name Credential cache name * - * @param [in,out] context Context structure - * @param [in,out] opt Options - * @param [in] fast_ccache_name Credential cache name + * Sets the location of a credential cache containing an armor ticket to + * protect an initial credential exchange using the FAST protocol extension. * - * 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() + * In version 1.7, setting an armor ccache requires that FAST be used for the + * exchange. In version 1.8 or later, setting the armor ccache causes FAST to + * be used if the KDC supports it; krb5_get_init_creds_opt_set_fast_flags() + * must be used to require that FAST be used. */ 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 a location of FAST cache containing TGT based on krb5_ccache object. +/** + * Set FAST armor cache in initial credential options. * - * @param [in,out] context Context structure - * @param [in,out] opt Options - * @param [in] fast_ccache_name Credential cache handle + * @param [in] context Library context + * @param [in] opt Options + * @param [in] ccache 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() + * This function is similar to krb5_get_init_creds_opt_set_fast_ccache_name(), + * but uses a credential cache handle instead of a name. */ 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); + krb5_ccache ccache); -/** Set an output credentials cache in krb5_get_init_creds_opt structure. +/** + * Set an output credential cache in initial credential options. * - * @param [in,out] context Context structure - * @param [in,out] opt Options - * @param [in] ccache Credential cache to use + * @param [in] context Library context + * @param [in] opt Options + * @param [in] ccache Credential cache handle * - * 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. + * If an output credential cache is set, then the krb5_get_init_creds family of + * APIs will write credentials to it. 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. +/** + * Set FAST flags in initial credential options. * - * @param [in,out] context Context structure - * @param [in,out] opt Options - * @param [in] flags FAST flags (for example, KRB5_FAST_REQUIRED) + * @param [in] context Library context + * @param [in] opt Options + * @param [in] flags FAST flags * - * This function may be used to require that the request fail if FAST is unavailable. + * The following flag values are valid: + * @li @c KRB5_FAST_REQUIRED - Require FAST to be used * * @retval * 0 - Success; Kerberos errors otherwise. @@ -5904,14 +5945,12 @@ 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 +/** + * Retrieve FAST flags from initial credential options. * - * Get FAST @a out_flags from @a opt - * This function may be used to verify if KDC supports FAST. + * @param [in] context Library context + * @param [in] opt Options + * @param [out] out_flags FAST flags * * @retval * 0 - Success; Kerberos errors otherwise. @@ -5930,12 +5969,13 @@ typedef void krb5_timestamp account_expiration, krb5_boolean is_last_req); -/** Set an expire callback in extended krb5_get_init_creds_opt structure. +/** + * Set an expiration callback in initial credential options. * - * @param [in,out] context Context structure - * @param [in,out] opt Options structure - * @param [in] cb Callback function - * @param [in] data Data + * @param [in] context Library context + * @param [in] opt Options structure + * @param [in] cb Callback function + * @param [in] data Callback argument * * Set a callback to receive password and account expiration times. * @@ -5972,20 +6012,24 @@ krb5_get_init_creds_opt_set_expire_callback(krb5_context context, krb5_expire_callback_func cb, void *data); -/** Get initial credentials using a password. - * - * @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 - * - * This function requests KDC for an initial credentials for @a client using - * @a password. +/** + * Get initial credentials using a password. + * + * @param [in] context Library context + * @param [out] creds New credentials + * @param [in] client Client principal + * @param [in] password Password (or NULL) + * @param [in] prompter Prompter function + * @param [in] data Prompter callback data + * @param [in] start_time Time when ticket becomes valid (0 for now) + * @param [in] in_tkt_service Service name of initial credentials (or NULL) + * @param [in] k5_gic_options Initial credential options + * + * This function requests KDC for an initial credentials for @a client using @a + * password. If @a password is NULL, a password will be prompted for using @a + * prompter if necessary. If @a in_tkt_service is specified, it is parsed as a + * principal name (with the realm ignored) and used as the service principal + * for the request; otherwise the ticket-granting service is used. * * @sa krb5_verify_init_creds() * @@ -6024,71 +6068,76 @@ typedef struct _krb5_init_creds_context *krb5_init_creds_context; #define KRB5_INIT_CREDS_STEP_FLAG_CONTINUE 0x1 /* More responses needed */ -/** Free an initial credentials asynchronous context. +/** + * Free an initial credentials context. * - * @param [in] context A krb5 library context - * @param [in] ctx Initial credentials context to free. + * @param [in] context Library context + * @param [in] ctx Initial credentials context */ void KRB5_CALLCONV krb5_init_creds_free(krb5_context context, krb5_init_creds_context ctx); -/** Acquire credentials asynchronously. +/** + * Acquire credentials using an initial credentials context. * - * @param [in] context A krb5 library context - * @param [in,out] ctx Initial credentials context + * @param [in] context Library context + * @param [in] ctx Initial credentials context * - * @retval 0 Success; Otherwise - Kerberos error codes + * This function synchronously obtains credentials using a context created by + * krb5_init_creds_init(). On successful return, the credentials can be + * retrieved with krb5_init_creds_get_creds(). + * + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_init_creds_get(krb5_context context, krb5_init_creds_context ctx); -/** Copy the acquired initial credentials contents. +/** + * Retrieve acquired credentials from an initial credentials context. * - * @param [in] context A krb5 library context - * @param [in] ctx Initial credentials context - * @param [out] creds Copy of @a ctx->cred + * @param [in] context Library context + * @param [in] ctx Initial credentials context + * @param [out] creds Acquired credentials * - * This function copies the acquired initial credentials from - * @a ctx->cred into @a creds. - * Use krb5_free_cred_contents() to free @a creds when it is no longer needed. + * This function copies the acquired initial credentials from @a ctx into @a + * creds, after the successful completion of krb5_init_creds_get() or + * krb5_init_creds_step(). Use krb5_free_cred_contents() to free @a creds when + * it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_init_creds_get_creds(krb5_context context, krb5_init_creds_context ctx, krb5_creds *creds); -/** Get the last error data from KDC while acquiring initial credentials. +/** + * Get the last error from KDC from an initial credentials context. * - * @param [in] context A krb5 library context - * @param [in] ctx Initial credentials context - * @param [out] error If non-null, contains error packet returned from KDC + * @param [in] context Library context + * @param [in] ctx Initial credentials context + * @param [out] error Error from KDC, or NULL if none was received * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_init_creds_get_error(krb5_context context, krb5_init_creds_context ctx, krb5_error **error); -/** Create a context for acquiring initial credentials. +/** + * Create a context for acquiring initial credentials. * - * @param [in] context A krb5 library context - * @param [in] client Client principal to get initial credentials for. - * If NULL - the default principal is used - * @param [in] prompter Prompter - * @param [in] data Prompter data - * @param [in] start_time Time when credentials should become valid; - * 0 means from now - * @param [in] options KRB5_GET_INIT_CREDS_OPT options for this request. - * If NULL - the default options are used - * (see krb5_get_init_creds_opt_init()) - * @param [out] ctx A new initial credentials context. + * @param [in] context Library context + * @param [in] client Client principal to get initial creds for + * @param [in] prompter Prompter callback + * @param [in] data Prompter callback argument + * @param [in] start_time Time when credentials become valid (0 for now) + * @param [in] options Options structure (NULL for default) + * @param [out] ctx New initial credentials context * - * This function initializes a new context for acquiring initial credentials - * asynchronously. - * Use krb5_init_creds_free() to free @a ctx when it is no longer needed. + * This function creates a new context for acquiring initial credentials. Use + * krb5_init_creds_free() to free @a ctx when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_init_creds_init(krb5_context context, krb5_principal client, @@ -6096,73 +6145,98 @@ krb5_init_creds_init(krb5_context context, krb5_principal client, krb5_deltat start_time, krb5_get_init_creds_opt *options, krb5_init_creds_context *ctx); -/** Specify a keytab to use for acquiring initial credentials. +/** + * Specify a keytab to use for acquiring initial credentials. + * + * @param [in] context Library context + * @param [in] ctx Initial credentials context + * @param [in] keytab Key table handle * - * @param [in] context A krb5 library context - * @param [in,out] ctx Initial credentials context - * @param [in] keytab Key table handle + * This function supplies a keytab containing the client key for an initial + * credentials request. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_init_creds_set_keytab(krb5_context context, krb5_init_creds_context ctx, krb5_keytab keytab); -/** Perform the next step of asynchronous initial credentials acquisition. - * - * @param [in] context A krb5 library context - * @param [in,out] ctx Initial credentials context - * @param [in] in KDC response (empty on the first call) - * @param [out] out Buffer to be sent by the caller to the KDC - * for the indicated @a realm. - * @param [out] realm The realm for which the next request should be sent - * @param [out] flags Indicates whether more responses are needed - * (see KRB5_INIT_CREDS_STEP_FLAG_CONTINUE ) - * - * Once the credentials have been acquired, the @a out buffer is empty and - * @a flags is set to 0. If the request should be retried with TCP, - * KRB5KRB_ERR_RESPONSE_TOO_BIG is returned. +/** + * Get the next KDC request for acquiring initial credentials. + * + * @param [in] context Library context + * @param [in] ctx Initial credentials context + * @param [in] in KDC response (empty on the first call) + * @param [out] out Next KDC request + * @param [out] realm Realm for next KDC request + * @param [out] flags Output flags + * + * This function constructs the next KDC request in an initial credential + * exchange, allowing the caller to control the transport of KDC requests and + * replies. On the first call, @a in should be set to an empty buffer; on + * subsequent calls, it should be set to the KDC's reply to the previous + * request. + * + * If more requests are needed, @a flags will be set to @c + * KRB5_INIT_CREDS_STEP_FLAG_CONTINUE and the next request will be placed in @a + * out. If no more requests are needed, @a flags will not contain @c + * KRB5_INIT_CREDS_STEP_FLAG_CONTINUE and @a out will be empty. + * + * If this function returns @c KRB5KRB_ERR_RESPONSE_TOO_BIG, the caller should + * transmit the next request using TCP rather than UDP. If this function + * returns any other error, the initial credential exchange has failed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_init_creds_step(krb5_context context, krb5_init_creds_context ctx, krb5_data *in, krb5_data *out, krb5_data *realm, unsigned int *flags); -/** Set a password for acquiring initial credentials. +/** + * Set a password for acquiring initial credentials. * - * @param [in] context A krb5 library context - * @param [in,out] ctx Initial credentials context - * @param [in] password Password + * @param [in] context Library context + * @param [in] ctx Initial credentials context + * @param [in] password Password * - * @retval 0 Success; Otherwise - Kerberos error codes + * This function supplies a password to be used to construct the client key for + * an initial credentials request. + * + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_init_creds_set_password(krb5_context context, krb5_init_creds_context ctx, const char *password); -/** Specify a requested service for the initial credentials. +/** + * Specify a service principal for acquiring initial credentials. * - * @param [in] context A krb5 library context - * @param [in,out] ctx Initial credentials context - * @param [in] service Requested service + * @param [in] context Library context + * @param [in] ctx Initial credentials context + * @param [in] service Service principal string * - * The old @a ctx->in_tkt_service is overriden by the new @a service. + * This function supplies a service principal string to acquire initial + * credentials for instead of the default krbtgt service. @a service is parsed + * as a principal name; any realm part is ignored. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_init_creds_set_service(krb5_context context, krb5_init_creds_context ctx, const char *service); -/** Retrieve the ticket times from the initial credentials context. +/** + * Retrieve ticket times from an initial credentials context. * - * @param [in] context A krb5 library context - * @param [in] ctx Initial credentials context - * @param [out] times Ticket times for the acquired credentials + * @param [in] context Library context + * @param [in] ctx Initial credentials context + * @param [out] times Ticket times for acquired credentials * - * @retval 0 Success; Otherwise - Kerberos error codes + * The initial credentials context must have completed obtaining credentials + * via either krb5_init_creds_get() or krb5_init_creds_step(). + * + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_init_creds_get_times(krb5_context context, krb5_init_creds_context ctx, @@ -6174,14 +6248,16 @@ typedef struct _krb5_tkt_creds_context *krb5_tkt_creds_context; /** * 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[in] creds Input credentials - * @param[in] options KRB5_GC_* options for this request. - * @param[out] ctx The TGS acquisition context. + * @param[in] context Library context + * @param[in] ccache Credential cache handle + * @param[in] creds Input credentials + * @param[in] options KRB5_GC_* options for this request. + * @param[out] ctx New TGS request context + * + * This function prepares to obtain credentials matching @a creds, either by + * retrieving them from @a ccache or by making requests to ticket-granting + * services beginning with a ticket-granting ticket for the client principal's + * realm. * * The resulting TGS acquisition context can be used asynchronously with * krb5_tkt_creds_step() or synchronously with krb5_tkt_creds_get(). See also @@ -6189,7 +6265,7 @@ typedef struct _krb5_tkt_creds_context *krb5_tkt_creds_context; * * Use krb5_tkt_creds_free() to free @a ctx when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache, @@ -6197,41 +6273,43 @@ krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache, krb5_tkt_creds_context *ctx); /** - * Synchronously obtain credentials within an acquisition context. + * Synchronously obtain credentials using a TGS request context. * - * @param[in] context A krb5 library context (see krb5_init_context()) - * @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init()) + * @param[in] context Library context + * @param[in] ctx TGS request context * - * 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(). + * This function synchronously obtains credentials using a context created by + * krb5_tkt_creds_init(). On successful return, the credentials can be + * retrieved with krb5_tkt_creds_get_creds(). * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_tkt_creds_get(krb5_context context, krb5_tkt_creds_context ctx); /** - * Retrieve credentials from an acquisition context, filling in @a creds. + * Retrieve acquired credentials from a TGS request context. * - * @param[in] context A krb5 library context (see krb5_init_context()) - * @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init()) - * @param[out] creds The acquired credentials + * @param[in] context Library context + * @param[in] ctx TGS request context + * @param[out] creds Acquired credentials * - * The acquisition context must have completed obtaining credentials via either - * krb5_tkt_creds_get() or krb5_tkt_creds_step(). + * This function copies the acquired initial credentials from @a ctx into @a + * creds, after the successful completion of krb5_tkt_creds_get() or + * krb5_tkt_creds_step(). Use krb5_free_cred_contents() to free @a creds when + * it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @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); /** - * Release the resources used by an acquisition context. + * Free a TGS request context. * - * @param[in] context A krb5 library context (see krb5_init_context()) - * @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init()) + * @param[in] context Library context + * @param[in] ctx TGS request context */ void KRB5_CALLCONV krb5_tkt_creds_free(krb5_context context, krb5_tkt_creds_context ctx); @@ -6239,22 +6317,30 @@ krb5_tkt_creds_free(krb5_context context, krb5_tkt_creds_context ctx); #define KRB5_TKT_CREDS_STEP_FLAG_CONTINUE 0x1 /* More responses needed. */ /** - * Process a response and generate the next request to acquire credentials. + * Get the next KDC request in a TGS exchange. + * + * @param[in] context Library context + * @param[in] ctx TGS request context + * @param[in] in KDC response (empty on the first call) + * @param[out] out Next KDC request + * @param[out] realm Realm for next KDC request + * @param[out] flags Output flags + * + * This function constructs the next KDC request for a TGS exchange, allowing + * the caller to control the transport of KDC requests and replies. On the + * first call, @a in should be set to an empty buffer; on subsequent calls, it + * should be set to the KDC's reply to the previous request. * - * @param[in] context A krb5 library context (see krb5_init_context()) - * @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init()) - * @param[in] in The last response (empty or NULL for first call) - * @param[out] out The next request to be sent - * @param[out] realm The realm to which the next request should be sent - * @param[out] flags Indicates whether more responses are needed + * If more requests are needed, @a flags will be set to @c + * KRB5_TKT_CREDS_STEP_FLAG_CONTINUE and the next request will be placed in @a + * out. If no more requests are needed, @a flags will not contain @c + * KRB5_TKT_CREDS_STEP_FLAG_CONTINUE and @a out will be empty. * - * On the first call, @a in should be empty or NULL. If more responses are - * needed, the @a flags output parameter will contain @a - * 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. + * If this function returns @c KRB5KRB_ERR_RESPONSE_TOO_BIG, the caller should + * transmit the next request using TCP rather than UDP. If this function + * returns any other error, the TGS exchange has failed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_tkt_creds_step(krb5_context context, krb5_tkt_creds_context ctx, @@ -6262,33 +6348,37 @@ krb5_tkt_creds_step(krb5_context context, krb5_tkt_creds_context ctx, unsigned int *flags); /** - * Retrieve ticket times for obtained credentials, filling in @a times. + * Retrieve ticket times from a TGS request context. * - * @param[in] context A krb5 library context (see krb5_init_context()) - * @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init()) - * @param[out] times Ticket times for the acquired credentials + * @param[in] context Library context + * @param[in] ctx TGS request context + * @param[out] times Ticket times for acquired credentials * - * The acquisition context must have completed obtaining credentials via either + * The TGS request context must have completed obtaining credentials via either * krb5_tkt_creds_get() or krb5_tkt_creds_step(). * - * @retval 0 Success; Otherwise - Kerberos error codes + * @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, krb5_ticket_times *times); -/** Get initial credentials using a key table. - * - * @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 - * - * 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. +/** + * Get initial credentials using a key table. + * + * @param [in] context Library context + * @param [out] creds New credentials + * @param [in] client Client principal + * @param [in] arg_keytab Key table handle + * @param [in] start_time Time when ticket becomes valid (0 for now) + * @param [in] in_tkt_service Service name of initial credentials (or NLUL) + * @param [in] k5_gic_options Initial credential options + * + * This function requests KDC for an initial credentials for @a client using a + * client key stored in @a arg_keytab. If @a in_tkt_service is specified, it + * is parsed as a principal name (with the realm ignored) and used as the + * service principal for the request; otherwise the ticket-granting service is + * used. * * @sa krb5_verify_init_creds() * @@ -6310,69 +6400,84 @@ typedef struct _krb5_verify_init_creds_opt { #define KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL 0x0001 -/** Initialize a @a flags field in krb5_verify_init_creds_opt structure. - * - * @param [out] k5_vic_options Pointer to krb5_verify_init_creds_opt structure +/** + * Initialize a credential verification options structure. * - * Sets @a k5_vic_options flags fiels to zero. + * @param [in] k5_vic_options Verification options structure */ void KRB5_CALLCONV krb5_verify_init_creds_opt_init(krb5_verify_init_creds_opt *k5_vic_options); -/** Set a @a ap_req_nofail field in krb5_verify_init_creds_opt structure. +/** + * Set whether credential verification is required. + * + * @param [in] k5_vic_options Verification options structure + * @param [in] ap_req_nofail Whether to require successful verification * - * @param [out] k5_vic_options Pointer to krb5_verify_init_creds_opt structure - * @param [in] ap_req_nofail Boolean value to set for the ap_req_nofail field + * This function determines how krb5_verify_init_creds() behaves if no keytab + * information is available. If @a ap_req_nofail is @c FALSE, verification + * will be skipped in this case and krb5_verify_init_creds() will return + * successfully. If @a ap_req_nofail is @c TRUE, krb5_verify_init_creds() will + * not return successfully unless verification can be performed. * - * This function sets KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL flag and - * ap_req_nofail field to @a ap_req_nofail in @a k5_vic_options. - * If @a ap_req_nofail is FALSE and keytab is missing (empty or unreadable), - * krb5_verify_init_creds() will succeed even though verification cannot be - * performed. - * This function may be used to override the krb5 configuration setting for - * verify_ap_req_nofail attribute. + * If this function is not used, the behavior of krb5_verify_init_creds() is + * determined through configuration. */ void KRB5_CALLCONV krb5_verify_init_creds_opt_set_ap_req_nofail(krb5_verify_init_creds_opt * k5_vic_options, int ap_req_nofail); -/** Verify initial credentials and store them in the credentials cache. +/** + * Verify initial credentials against a keytab. + * + * @param [in] context Library context + * @param [in] creds Initial credentials to be verified + * @param [in] server_arg Server principal (or NULL) + * @param [in] keytab_arg Key table (NULL to use default keytab) + * @param [in,out] ccache_arg Credential cache for fetched creds (or NULL) + * @param [in] options Verification options (NULL for default options) * - * @param [in] context Context structure - * @param [in] creds Initial credentials to be verified - * @param [in] server_arg Server principal; - * if NULL - use a principal name from @a keytab_arg - * @param [in] keytab_arg Key table to verify @a creds against - * @param [out] ccache_arg Credentials cache to store all fetched from KDC credentials - * if NULL - memory credential will be used and then destroyed. - * @param [in] options Pointer to krb5_verify_init_creds_opt structure + * This function attempts to verify that @a creds were obtained from a KDC with + * knowledge of a key in @a keytab_arg. If @a server_arg is provided, the + * highest-kvno key entry for that principal name is used to verify the + * credentials; otherwise, the highest-kvno key entry for the first principal + * listed in @a keytab_arg is used. * + * If the specified keytab does not exist, or is empty, or cannot be read, or + * does not contain an entry for @a server_arg, then credential verification + * may be skipped unless configuration demands that it succeed. The caller can + * control this behavior by providing a verification options structure; see + * krb5_verify_init_creds_opt_init() and + * krb5_verify_init_creds_opt_set_ap_req_nofail(). * - * @sa krb5_verify_init_creds_opt_set_ap_req_nofail() and - * krb5_verify_init_creds_opt_init() + * If @a ccache_arg is NULL, any additional credentials fetched during the + * verification process will be destroyed. If @a ccache_arg points to NULL, a + * memory ccache will be created for the additional credentials and returned in + * @a ccache_arg. If @a ccache_arg points to a valid credential cache handle, + * the additional credentials will be stored in that cache. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_verify_init_creds(krb5_context context, krb5_creds *creds, krb5_principal server_arg, krb5_keytab keytab_arg, krb5_ccache *ccache_arg, krb5_verify_init_creds_opt *options); -/** Get validated credentials from the KDC. +/** + * Get validated credentials from the KDC. + * + * @param [in] context Library context + * @param [out] creds Validated credentials + * @param [in] client Client principal name + * @param [in] ccache Credential cache + * @param [in] in_tkt_service Server principal string (or NULL) * - * @param [in,out] context Context structure - * @param [out] creds Credential structure to fill in - * @param [in] client Client principal name - * @param [in] ccache Credentials cache - * @param [in] in_tkt_service Principal name of requesting server + * This function gets a validated credential using a postdated credential from + * @a ccache. If @a in_tkt_service is specified, it is parsed (with the realm + * part ignored) and used as the server principal of the credential; + * otherwise, the ticket-granting service is used. * - * This function gets a validated single service ticket, that is specified as - * @a in_tkt_service parameter, from KDC. - * It uses credentials provided by @a client and @a in_tkt_service to retrieve the - * old existing credentials from @a ccache so they can be used to get a validated - * credential from KDC. - * If @a in_tkt_service is NULL, the TGT name for the client's realm will be used. - * The result is placed in @a creds. + * If successful, the validated credential is placed in @a creds. * * @sa krb5_get_renewed_creds() * @@ -6396,23 +6501,21 @@ krb5_get_validated_creds(krb5_context context, krb5_creds *creds, krb5_principal client, krb5_ccache ccache, char *in_tkt_service); -/** Get renewed credential from KDC using the existing one. +/** + * Get renewed credential from KDC using an existing credential. * - * @param [in,out] context Context structure - * @param [out] creds Credentials structure to fill in - * @param [in] client Client principal name - * @param [in] ccache Credentials cache - * @param [in] in_tkt_service Principal name of requesting server + * @param [in] context Library context + * @param [out] creds Renewed credentials + * @param [in] client Client principal name + * @param [in] ccache Credential cache + * @param [in] in_tkt_service Server principal string (or NULL) * - * This function gets a renewed single service ticket, that is specified as - * @a in_tkt_service parameter, from KDC. - * It uses credentials provided by @a client and @a in_tkt_service to retrieve the - * old existing credentials from @a ccache so they can be used to get a new - * credential from KDC. - * If @a in_tkt_service is NULL, the TGT name for the client's realm will be used. - * The result is placed in @a creds. + * This function gets a renewed credential using an existing one from @a + * ccache. If @a in_tkt_service is specified, it is parsed (with the realm + * part ignored) and used as the server principal of the credential; otherwise, + * the ticket-granting service is used. * - * @sa krb5_get_validated_creds() + * If successful, the renewed credential is placed in @a creds. * * @retval * 0 Success @@ -6424,24 +6527,26 @@ krb5_get_renewed_creds(krb5_context context, krb5_creds *creds, krb5_principal client, krb5_ccache ccache, char *in_tkt_service); -/** Decode a formatted ticket. +/** + * Decode an ASN.1-formatted ticket. * - * @param [in] code Formatted ticket - * @param [out] rep Decoded ticket information + * @param [in] code ASN.1-formatted ticket + * @param [out] rep Decoded ticket information * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_decode_ticket(const krb5_data *code, krb5_ticket **rep); -/** Retrieve an attribute value from @a appdefaults section of krb5.conf. +/** + * Retrieve a string value from the appdefaults section of krb5.conf. * - * @param [in] context Context structure - * @param [in] appname Application name - * @param [in] realm Realm name - * @param [in] option Option to be checked - * @param [in] default_value Default Boolean value to return if no match is found - * @param [out] ret_value String value of @a option + * @param [in] context Library context + * @param [in] appname Application name + * @param [in] realm Realm name + * @param [in] option Option to be checked + * @param [in] default_value Default value to return if no match is found + * @param [out] ret_value String value of @a option * * This function gets the application defaults for @a option based on the given * @a appname and/or @a realm. @@ -6453,14 +6558,15 @@ krb5_appdefault_string(krb5_context context, const char *appname, const krb5_data *realm, const char *option, const char *default_value, char ** ret_value); -/** Retrieve a booloean attribute value from @a appdefaults section of krb5.conf. +/** + * Retrieve a boolean value from the appdefaults section of krb5.conf. * - * @param [in] context Context structure - * @param [in] appname Application name - * @param [in] realm Realm name - * @param [in] option Option to be checked - * @param [in] default_value Default Boolean value to return if no match is found - * @param [out] ret_value Boolean value of @a option + * @param [in] context Library context + * @param [in] appname Application name + * @param [in] realm Realm name + * @param [in] option Option to be checked + * @param [in] default_value Default value to return if no match is found + * @param [out] ret_value Boolean value of @a option * * This function gets the application defaults for @a option based on the given * @a appname and/or @a realm. @@ -6483,28 +6589,30 @@ krb5_appdefault_boolean(krb5_context context, const char *appname, typedef krb5_int32 krb5_prompt_type; -/** Get @a prompt_types field from a context. +/** + * Get prompt types array from a context. * - * @param [in] context Context structure + * @param [in] context Library context * * @return - * Pointer to the @a krb5_prompt_type field, which contains one - * of the following values: - * @li @c KRB5_PROMPT_TYPE_PASSWORD - * @li @c KRB5_PROMPT_TYPE_NEW_PASSWORD - * @li @c KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN - * @li @c KRB5_PROMPT_TYPE_PREAUTH + * Pointer to an array of prompt types corresponding to the prompter's @a + * prompts arguments. Each type has one of the following values: + * @li @c KRB5_PROMPT_TYPE_PASSWORD + * @li @c KRB5_PROMPT_TYPE_NEW_PASSWORD + * @li @c KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN + * @li @c KRB5_PROMPT_TYPE_PREAUTH */ krb5_prompt_type* KRB5_CALLCONV krb5_get_prompt_types(krb5_context context); /* Error reporting */ -/** Set error message state in a context structure. +/** + * Set an extended error message for an error code. * - * @param [in,out] ctx Context structure - * @param [in] code Error code - * @param [in] fmt Error string for the error code - * @param [in] ... printf(3) style parameters + * @param [in] ctx Library context + * @param [in] code Error code + * @param [in] fmt Error string for the error code + * @param [in] ... printf(3) style parameters */ void KRB5_CALLCONV_C krb5_set_error_message(krb5_context ctx, krb5_error_code code, const char *fmt, ...) @@ -6513,12 +6621,13 @@ krb5_set_error_message(krb5_context ctx, krb5_error_code code, const char *fmt, #endif ; -/** Set error message state in a context structure using a precomputed va_list. +/** + * Set an extended error message for an error code using a va_list. * - * @param [in,out] ctx Context structure - * @param [in] code Error code - * @param [in] fmt Error string for the error code - * @param [in] args @c va_list of arguments + * @param [in] ctx Library context + * @param [in] code Error code + * @param [in] fmt Error string for the error code + * @param [in] args List of vprintf(3) style arguments */ void KRB5_CALLCONV krb5_vset_error_message(krb5_context ctx, krb5_error_code code, @@ -6528,26 +6637,28 @@ krb5_vset_error_message(krb5_context ctx, krb5_error_code code, #endif ; -/** Set the error message state of dest_ctx to that of src_ctx. +/** + * Copy the most recent extended error message from one context to another. * - * @param [in] dest_ctx Context structure where the error message state is copied to - * @param [in] src_ctx Context structure where the error message state is copied from + * @param [in] dest_ctx Library context to copy message to + * @param [in] src_ctx Library context with current message */ void KRB5_CALLCONV krb5_copy_error_message(krb5_context dest_ctx, krb5_context src_ctx); -/** Get error message state specific to the context. +/** + * Get the (possibly extended) error message for a code. * - * @param [in] ctx Context structure - * @param [in] code Error code + * @param [in] ctx Library context + * @param [in] code Error code * - * The behavior of krb5_get_error_message() is only defined the first - * time it is called after a failed call to a krb5 function using the - * same context, and only when the error code passed in is the same as - * that returned by the krb5 function. + * The behavior of krb5_get_error_message() is only defined the first time it + * is called after a failed call to a krb5 function using the same context, and + * only when the error code passed in is the same as that returned by the krb5 + * function. * - * This function never returns NULL, so its result may be used - * unconditionally as a C string. + * This function never returns NULL, so its result may be used unconditionally + * as a C string. * * The string returned by this function must be freed using * krb5_free_error_message() @@ -6558,19 +6669,22 @@ krb5_copy_error_message(krb5_context dest_ctx, krb5_context src_ctx); 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 generated by krb5_get_error_message(). * - * @param [in] ctx Context structure - * @param [in] msg Pointer to error message + * @param [in] ctx Library context + * @param [in] msg Pointer to error message */ void KRB5_CALLCONV krb5_free_error_message(krb5_context ctx, const char *msg); -/** Clear the error message state. +/** + * Clear the extended error message in a context. * - * @param [in,out] ctx Context structure + * @param [in] ctx Library context * - * Similar to krb5_free_error_message() but @a ctx->msg is set to NULL. + * This function unsets the extended error message in a context, to ensure that + * it is not mistakenly applied to another occurrence of the same error code. */ void KRB5_CALLCONV krb5_clear_error_message(krb5_context ctx); @@ -6590,17 +6704,18 @@ krb5_encode_authdata_container(krb5_context context, /* * AD-KDCIssued */ -/** This function both encodes and signs AD-KDCIssued authorization data. +/** + * Encode and sign AD-KDCIssued authorization data. * - * @param [in] context Context structure - * @param [in] key Session key - * @param [in] issuer The name of the issuing principal - * @param [in] authdata Authorization data to be signed - * @param [out] ad_kdcissued Authorization data to be filled in + * @param [in] context Library context + * @param [in] key Session key + * @param [in] issuer The name of the issuing principal + * @param [in] authdata List of authorization data to be signed + * @param [out] ad_kdcissued List containing AD-KDCIssued authdata * - * This function both encodes and signs AD-KDCIssued authorization data @a authdata - * (RFC 4120 section 5.2.6.2). A set of authorization data @a ad_kdcissued containing - * a single AD-KDCIssued element is returned to the caller. + * This function wraps a list of authorization data entries @a authdata in an + * AD-KDCIssued container (see RFC 4120 section 5.2.6.2) signed with @a key. + * The result is returned in @a ad_kdcissued as a single-element list. */ krb5_error_code KRB5_CALLCONV krb5_make_authdata_kdc_issued(krb5_context context, @@ -6609,17 +6724,19 @@ krb5_make_authdata_kdc_issued(krb5_context context, krb5_authdata *const *authdata, krb5_authdata ***ad_kdcissued); -/** Decode and verify AD-KDCIssued authorization data. +/** + * Unwrap and verify AD-KDCIssued authorization data. * - * @param [in] context Context structure - * @param [in] key Session key - * @param [in] ad_kdcissued KDC issued authorization data to be verified - * @param [out] issuer The name of the issuing principal to be filled in (optional) - * @param [out] authdata Authorization data to be filled in + * @param [in] context Library context + * @param [in] key Session key + * @param [in] ad_kdcissued AD-KDCIssued authorization data to be unwrapped + * @param [out] issuer Name of issuing principal (or NULL) + * @param [out] authdata Unwrapped list of authorization data * - * This function both decodes and verifies AD-KDCIssued authorization data @a ad_kdcissued - * (RFC 4120 section 5.2.6.2). The @a issuer and unwrapped authorization data @a authdata - * are returned to the caller. + * This function unwraps an AD-KDCIssued authdatum (see RFC 4120 section + * 5.2.6.2) and verifies its signature against @a key. The issuer field of the + * authdatum element is returned in @a issuer, and the unwrapped list of + * authdata is returned in @a authdata. */ krb5_error_code KRB5_CALLCONV krb5_verify_authdata_kdc_issued(krb5_context context, @@ -6646,15 +6763,16 @@ krb5_verify_authdata_kdc_issued(krb5_context context, struct krb5_pac_data; typedef struct krb5_pac_data *krb5_pac; -/** Add a buffer to the provided PAC and update header. +/** + * Add a buffer to a PAC handle. * - * @param [in] context Context structure - * @param [in,out] pac PAC handle - * @param [in] type Type of data contained in @a data - * @param [in] data Buffer to add + * @param [in] context Library context + * @param [in] pac PAC handle + * @param [in] type Buffer type + * @param [in] data contents * - * This function adds a new @a data to @a pac if there isn't already a buffer - * of this type in @a pac. + * This function adds a buffer of type @a type and contents @a data to @a pac + * if there isn't already a buffer of this type present. * * The valid values of @a type is one of the following: * @li @c PAC_LOGON_INFO - Logon information @@ -6665,115 +6783,121 @@ typedef struct krb5_pac_data *krb5_pac; * @li @c PAC_DELEGATION_INFO - Constrained delegation information * @li @c PAC_UPN_DNS_INFO - User principal name and DNS information * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_pac_add_buffer(krb5_context context, krb5_pac pac, krb5_ui_4 type, const krb5_data *data); -/** Free the storage assigned to a PAC. +/** + * Free a PAC handle. * - * @param context Context structure + * @param [in] context Library context * @param [in] pac PAC to be freed * - * This function zeros out and frees the content of a @a pac and then - * releases @a pac itself. + * This function frees the contents of @a pac and the structure itself. */ void KRB5_CALLCONV krb5_pac_free(krb5_context context, krb5_pac pac); -/** Find a buffer in a PAC and copy data into output buffer. +/** + * Retrieve a buffer value from a PAC. * - * @param [in] context Context structure - * @param [in] pac PAC handle - * @param [in] type Type of the buffer to be copied - * @param [out] data Copy of a buffer to be filled in + * @param [in] context Library context + * @param [in] pac PAC handle + * @param [in] type Type of buffer to retrieve + * @param [out] data Buffer value * * Use krb5_free_data_contents() to free @a data when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_pac_get_buffer(krb5_context context, krb5_pac pac, krb5_ui_4 type, krb5_data *data); -/** Return an array of the types of data in the PAC. - * - * @param [in] context Context structure - * @param [in,out] pac PAC handle - * @param [out] len Number of entries in the @a types array. - * @param [out] types If non-null, contains an array of types +/** + * Return an array of buffer types in a PAC handle. * - * Free @a types when it is no linger needed. + * @param [in] context Library context + * @param [in] pac PAC handle + * @param [out] len Number of entries in @a types + * @param [out] types Array of buffer types * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_pac_get_types(krb5_context context, krb5_pac pac, size_t *len, krb5_ui_4 **types); -/** Create and initialize Privilege Attribute Certificate (PAC). +/** + * Create an empty Privilege Attribute Certificate (PAC) handle. * - * @param [in] context Context structure - * @param [out] pac PAC handle + * @param [in] context Library context + * @param [out] pac New PAC handle * * Use krb5_pac_free() to free @a pac when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_pac_init(krb5_context context, krb5_pac *pac); -/** Parse the supplied data into the newly allocated PAC. +/** + * Unparse an encoded PAC into a new handle. * - * @param [in] context Context structure + * @param [in] context Library context * @param [in] ptr PAC buffer - * @param [in] len Size of @a ptr + * @param [in] len Length of @a ptr * @param [out] pac PAC handle * * Use krb5_pac_free() to free @a pac when it is no longer needed. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_pac_parse(krb5_context context, const void *ptr, size_t len, krb5_pac *pac); -/** Verify a PAC. +/** + * Verify a PAC. * - * @param [in] context Context structure - * @param [in] pac PAC handle - * @param [in] authtime Timestamp to be compared with one in @a pac - * @param [in] principal If non-null, use it to validate PAC's client name - * and ticket information. - * @param [in] server Compare it with PAC'c server checksum. - * Must not be NULL. - * @param [in] privsvr If non-null, compare it with PAC'c KDC checksum + * @param [in] context Library context + * @param [in] pac PAC handle + * @param [in] authtime Expected timestamp + * @param [in] principal Expected principal name (or NULL) + * @param [in] server Key to validate server checksum + * @param [in] privsvr Key to validate KDC checksum (or NULL) * * This function validates @a pac against the supplied @a server, @a privsvr, - * @a principal and @a authtime and then, if successful, sets @a pac->verified - * to TRUE. + * @a principal and @a authtime. If @a principal is NULL, the principal and + * authtime are not verified. If @a privsvr is NULL, the KDC checksum is not + * verified. + * + * If successful, @a pac is marked as verified. * * @note A checksum mismatch can occur if the PAC was copied from a cross-realm - * TGT by an ignorant KDC; also Apple Mac OS X Server Open Directory (as of 10.6) - * generates PACs with no server checksum at all. One should consider not failing - * the whole authentication because of this reason, but, instead, marking PAC - * as not verified. + * TGT by an ignorant KDC; also Apple Mac OS X Server Open Directory (as of + * 10.6) generates PACs with no server checksum at all. One should consider + * not failing the whole authentication because of this reason, but, instead, + * treating the ticket as if it did not contain a PAC or marking the PAC + * information as non-verified. * - * @retval 0 Success; Otherwise - Kerberos error codes + * @retval 0 Success; otherwise - Kerberos error codes */ krb5_error_code KRB5_CALLCONV krb5_pac_verify(krb5_context context, const krb5_pac pac, krb5_timestamp authtime, krb5_const_principal principal, const krb5_keyblock *server, const krb5_keyblock *privsvr); -/** Allow the appplication to override the profile's allow_weak_crypto setting. +/** + * Allow the appplication to override the profile's allow_weak_crypto setting. * - * @param [in,out] context Context structure - * @param [in] enable Boolean flag + * @param [in] context Library context + * @param [in] enable Boolean flag * - * This function sets @a allow_weak_crypto field in @a context to @a enable. - * It is primarily for use by aklog. + * This function allows an application to override the allow_weak_crypto + * setting. It is primarily for use by aklog. * * @retval 0 (always) */ @@ -6790,18 +6914,19 @@ typedef void const struct krb5_trace_info *info, void *cb_data); -/** Specify a callback function for trace events. +/** + * 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 + * @param [in] context Library context + * @param [in] fn Callback function + * @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 * krb5_trace_info as the second argument. If the trace callback is reset via * this function or @a context is destroyed, @a fn will be invoked with a NULL - * second argument to allow cleanup of @a cb_data. Supply a NULL value for @a + * second argument so it can clean up @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 @@ -6811,15 +6936,16 @@ 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. +/** + * Specify a file name for directing trace events. * - * @param [in,out] context Context structure - * @param [in] filename File name + * @param [in] context Library context + * @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. * - * @return KRB5_TRACE_NOSUPP if tracing is not supported in the library. + * @retval KRB5_TRACE_NOSUPP Tracing is not supported in the library. */ krb5_error_code KRB5_CALLCONV krb5_set_trace_filename(krb5_context context, const char *filename);