diff options
Diffstat (limited to 'lib/krb5/krb5-protos.h')
| -rw-r--r-- | lib/krb5/krb5-protos.h | 4824 |
1 files changed, 4793 insertions, 31 deletions
diff --git a/lib/krb5/krb5-protos.h b/lib/krb5/krb5-protos.h index c72e796afe20..a312e070fefb 100644 --- a/lib/krb5/krb5-protos.h +++ b/lib/krb5/krb5-protos.h @@ -1,6 +1,7 @@ /* This is a generated file */ #ifndef __krb5_protos_h__ #define __krb5_protos_h__ +#ifndef DOXY #include <stdarg.h> @@ -9,12 +10,22 @@ #endif #ifndef KRB5_DEPRECATED_FUNCTION -#if defined(__GNUC__) && ((__GNUC__ > 3) || ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 1 ))) +#ifndef __has_extension +#define __has_extension(x) 0 +#define KRB5_DEPRECATED_FUNCTIONhas_extension 1 +#endif +#if __has_extension(attribute_deprecated_with_message) +#define KRB5_DEPRECATED_FUNCTION(x) __attribute__((__deprecated__(x))) +#elif defined(__GNUC__) && ((__GNUC__ > 3) || ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 1 ))) #define KRB5_DEPRECATED_FUNCTION(X) __attribute__((__deprecated__)) #else #define KRB5_DEPRECATED_FUNCTION(X) #endif +#ifdef KRB5_DEPRECATED_FUNCTIONhas_extension +#undef __has_extension +#undef KRB5_DEPRECATED_FUNCTIONhas_extension #endif +#endif /* KRB5_DEPRECATED_FUNCTION */ #ifdef __cplusplus @@ -34,6 +45,22 @@ extern "C" { #endif #endif #endif +/** + * Convert the v5 credentials in in_cred to v4-dito in v4creds. This + * is done by sending them to the 524 function in the KDC. If + * `in_cred' doesn't contain a DES session key, then a new one is + * gotten from the KDC and stored in the cred cache `ccache'. + * + * @param context Kerberos 5 context. + * @param in_cred the credential to convert + * @param v4creds the converted credential + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5_v4compat + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb524_convert_creds_kdc ( krb5_context /*context*/, @@ -41,6 +68,21 @@ krb524_convert_creds_kdc ( struct credentials */*v4creds*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Convert the v5 credentials in in_cred to v4-dito in v4creds, + * check the credential cache ccache before checking with the KDC. + * + * @param context Kerberos 5 context. + * @param ccache credential cache used to check for des-ticket. + * @param in_cred the credential to convert + * @param v4creds the converted credential + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5_v4compat + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb524_convert_creds_kdc_ccache ( krb5_context /*context*/, @@ -49,20 +91,58 @@ krb524_convert_creds_kdc_ccache ( struct credentials */*v4creds*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Log a warning to the log, default stderr, include the error from + * the last failure and then abort. + * + * @param context A Kerberos 5 context + * @param code error code of the last error + * @param fmt message to print + * @param ... arguments for format string + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_abort ( krb5_context /*context*/, krb5_error_code /*code*/, const char */*fmt*/, ...) - __attribute__ ((noreturn, format (printf, 3, 4))); + __attribute__ ((__noreturn__, __format__ (__printf__, 3, 4))); + +/** + * Log a warning to the log, default stderr, and then abort. + * + * @param context A Kerberos 5 context + * @param fmt printf format string of message to print + * @param ... arguments for format string + * + * @ingroup krb5_error + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_abortx ( krb5_context /*context*/, const char */*fmt*/, ...) - __attribute__ ((noreturn, format (printf, 2, 3))); + __attribute__ ((__noreturn__, __format__ (__printf__, 2, 3))); + +/** + * krb5_acl_match_file matches ACL format against each line in a file + * using krb5_acl_match_string(). Lines starting with # are treated + * like comments and ignored. + * + * @param context Kerberos 5 context. + * @param file file with acl listed in the file. + * @param format format to match. + * @param ... parameter to format string. + * + * @return Return an error code or 0. + * + * @sa krb5_acl_match_string + * @ingroup krb5_support + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_acl_match_file ( @@ -71,6 +151,52 @@ krb5_acl_match_file ( const char */*format*/, ...); +/** + * krb5_acl_match_string matches ACL format against a string. + * + * The ACL format has three format specifiers: s, f, and r. Each + * specifier will retrieve one argument from the variable arguments + * for either matching or storing data. The input string is split up + * using " " (space) and "\t" (tab) as a delimiter; multiple and "\t" + * in a row are considered to be the same. + * + * List of format specifiers: + * - s Matches a string using strcmp(3) (case sensitive). + * - f Matches the string with fnmatch(3). Theflags + * argument (the last argument) passed to the fnmatch function is 0. + * - r Returns a copy of the string in the char ** passed in; the copy + * must be freed with free(3). There is no need to free(3) the + * string on error: the function will clean up and set the pointer + * to NULL. + * + * @param context Kerberos 5 context + * @param string string to match with + * @param format format to match + * @param ... parameter to format string + * + * @return Return an error code or 0. + * + * + * @code + * char *s; + * + * ret = krb5_acl_match_string(context, "foo", "s", "foo"); + * if (ret) + * krb5_errx(context, 1, "acl didn't match"); + * ret = krb5_acl_match_string(context, "foo foo baz/kaka", + * "ss", "foo", &s, "foo/\\*"); + * if (ret) { + * // no need to free(s) on error + * assert(s == NULL); + * krb5_errx(context, 1, "acl didn't match"); + * } + * free(s); + * @endcode + * + * @sa krb5_acl_match_file + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_acl_match_string ( krb5_context /*context*/, @@ -78,16 +204,56 @@ krb5_acl_match_string ( const char */*format*/, ...); +/** + * Add a specified list of error messages to the et list in context. + * Call func (probably a comerr-generated function) with a pointer to + * the current et_list. + * + * @param context A kerberos context. + * @param func The generated com_err et function. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_add_et_list ( krb5_context /*context*/, void (*/*func*/)(struct et_list **)); +/** + * Add extra address to the address list that the library will add to + * the client's address list when communicating with the KDC. + * + * @param context Kerberos 5 context. + * @param addresses addreses to add + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_add_extra_addresses ( krb5_context /*context*/, krb5_addresses */*addresses*/); +/** + * Add extra addresses to ignore when fetching addresses from the + * underlaying operating system. + * + * @param context Kerberos 5 context. + * @param addresses addreses to ignore + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_add_ignore_addresses ( krb5_context /*context*/, @@ -109,6 +275,27 @@ krb5_addlog_func ( krb5_log_close_func_t /*close_func*/, void */*data*/); +/** + * krb5_addr2sockaddr sets the "struct sockaddr sockaddr" from addr + * and port. The argument sa_size should initially contain the size of + * the sa and after the call, it will contain the actual length of the + * address. In case of the sa is too small to fit the whole address, + * the up to *sa_size will be stored, and then *sa_size will be set to + * the required length. + * + * @param context a Keberos context + * @param addr the address to copy the from + * @param sa the struct sockaddr that will be filled in + * @param sa_size pointer to length of sa, and after the call, it will + * contain the actual length of the address. + * @param port set port in sa. + * + * @return Return an error code or 0. Will return + * KRB5_PROG_ATYPE_NOSUPP in case address type is not supported. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_addr2sockaddr ( krb5_context /*context*/, @@ -117,18 +304,61 @@ krb5_addr2sockaddr ( krb5_socklen_t */*sa_size*/, int /*port*/); +/** + * krb5_address_compare compares the addresses addr1 and addr2. + * Returns TRUE if the two addresses are the same. + * + * @param context a Keberos context + * @param addr1 address to compare + * @param addr2 address to compare + * + * @return Return an TRUE is the address are the same FALSE if not + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_address_compare ( krb5_context /*context*/, const krb5_address */*addr1*/, const krb5_address */*addr2*/); +/** + * krb5_address_order compares the addresses addr1 and addr2 so that + * it can be used for sorting addresses. If the addresses are the same + * address krb5_address_order will return 0. Behavies like memcmp(2). + * + * @param context a Keberos context + * @param addr1 krb5_address to compare + * @param addr2 krb5_address to compare + * + * @return < 0 if address addr1 in "less" then addr2. 0 if addr1 and + * addr2 is the same address, > 0 if addr2 is "less" then addr1. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_address_order ( krb5_context /*context*/, const krb5_address */*addr1*/, const krb5_address */*addr2*/); +/** + * Calculate the boundary addresses of `inaddr'/`prefixlen' and store + * them in `low' and `high'. + * + * @param context a Keberos context + * @param inaddr address in prefixlen that the bondery searched + * @param prefixlen width of boundery + * @param low lowest address + * @param high highest address + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_address_prefixlen_boundary ( krb5_context /*context*/, @@ -137,17 +367,57 @@ krb5_address_prefixlen_boundary ( krb5_address */*low*/, krb5_address */*high*/); +/** + * krb5_address_search checks if the address addr is a member of the + * address set list addrlist . + * + * @param context a Keberos context. + * @param addr address to search for. + * @param addrlist list of addresses to look in for addr. + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_address_search ( krb5_context /*context*/, const krb5_address */*addr*/, const krb5_addresses */*addrlist*/); +/** + * Enable or disable all weak encryption types + * + * @param context Kerberos 5 context + * @param enable true to enable, false to disable + * + * @return Return an error code or 0. + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_allow_weak_crypto ( krb5_context /*context*/, krb5_boolean /*enable*/); +/** + * Map a principal name to a local username. + * + * Returns 0 on success, KRB5_NO_LOCALNAME if no mapping was found, or + * some Kerberos or system error. + * + * Inputs: + * + * @param context A krb5_context + * @param aname A principal name + * @param lnsize The size of the buffer into which the username will be written + * @param lname The buffer into which the username will be written + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_aname_to_localname ( krb5_context /*context*/, @@ -155,6 +425,23 @@ krb5_aname_to_localname ( size_t /*lnsize*/, char */*lname*/); +/** + * krb5_anyaddr fills in a "struct sockaddr sa" that can be used to + * bind(2) to. The argument sa_size should initially contain the size + * of the sa, and after the call, it will contain the actual length + * of the address. + * + * @param context a Keberos context + * @param af address family + * @param sa sockaddr + * @param sa_size lenght of sa. + * @param port for to fill into sa. + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_anyaddr ( krb5_context /*context*/, @@ -190,6 +477,19 @@ krb5_appdefault_time ( time_t /*def_val*/, time_t */*ret_val*/); +/** + * krb5_append_addresses adds the set of addresses in source to + * dest. While copying the addresses, duplicates are also sorted out. + * + * @param context a Keberos context + * @param dest destination of copy operation + * @param source adresses that are going to be added to dest + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_append_addresses ( krb5_context /*context*/, @@ -197,17 +497,41 @@ krb5_append_addresses ( const krb5_addresses */*source*/); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_auth_con_add_AuthorizationData ( + krb5_context /*context*/, + krb5_auth_context /*auth_context*/, + int /*type*/, + krb5_data */*data*/); + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_auth_con_addflags ( krb5_context /*context*/, krb5_auth_context /*auth_context*/, int32_t /*addflags*/, int32_t */*flags*/); +/** + * Deallocate an authentication context previously initialized with + * krb5_auth_con_init(). + * + * @param context A kerberos context. + * @param auth_context The authentication context to be deallocated. + * + * @return An krb5 error code, see krb5_get_error_message(). + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_auth_con_free ( krb5_context /*context*/, krb5_auth_context /*auth_context*/); +/** + * Update the authentication context \a auth_context with the local + * and remote addresses from socket \a fd, according to \a flags. + * + * @return An krb5 error code, see krb5_get_error_message(). + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_auth_con_genaddrs ( krb5_context /*context*/, @@ -300,6 +624,17 @@ krb5_auth_con_getsendsubkey ( krb5_auth_context /*auth_context*/, krb5_keyblock **/*keyblock*/); +/** + * Allocate and initialize an autentication context. + * + * @param context A kerberos context. + * @param auth_context The authentication context to be initialized. + * + * Use krb5_auth_con_free() to release the memory when done using the context. + * + * @return An krb5 error code, see krb5_get_error_message(). + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_auth_con_init ( krb5_context /*context*/, @@ -397,6 +732,12 @@ krb5_auth_con_setuserkey ( krb5_auth_context /*auth_context*/, krb5_keyblock */*keyblock*/); +/** + * Deprecated: use krb5_auth_con_getremoteseqnumber() + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_auth_getremoteseqnumber ( krb5_context /*context*/, @@ -413,6 +754,20 @@ krb5_build_ap_req ( krb5_data /*authenticator*/, krb5_data */*retdata*/); +/** + * Build a principal using vararg style building + * + * @param context A Kerberos context. + * @param principal returned principal + * @param rlen length of realm + * @param realm realm name + * @param ... a list of components ended with NULL. + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_build_principal ( krb5_context /*context*/, @@ -482,6 +837,12 @@ krb5_c_encrypt_length ( size_t /*inputlen*/, size_t */*length*/); +/** + * Deprecated: keytypes doesn't exists, they are really enctypes. + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_c_enctype_compare ( krb5_context /*context*/, @@ -565,49 +926,140 @@ krb5_c_verify_checksum ( const krb5_checksum */*cksum*/, krb5_boolean */*valid*/); +/** + * Destroy the cursor `cursor'. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_cache_end_seq_get ( krb5_context /*context*/, krb5_cc_cache_cursor /*cursor*/); +/** + * Start iterating over all caches of specified type. See also + * krb5_cccol_cursor_new(). + + * @param context A Kerberos 5 context + * @param type optional type to iterate over, if NULL, the default cache is used. + * @param cursor cursor should be freed with krb5_cc_cache_end_seq_get(). + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_cache_get_first ( krb5_context /*context*/, const char */*type*/, krb5_cc_cache_cursor */*cursor*/); +/** + * Search for a matching credential cache that have the + * `principal' as the default principal. On success, `id' needs to be + * freed with krb5_cc_close() or krb5_cc_destroy(). + * + * @param context A Kerberos 5 context + * @param client The principal to search for + * @param id the returned credential cache + * + * @return On failure, error code is returned and `id' is set to NULL. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_cache_match ( krb5_context /*context*/, krb5_principal /*client*/, krb5_ccache */*id*/); +/** + * Retrieve the next cache pointed to by (`cursor') in `id' + * and advance `cursor'. + * + * @param context A Kerberos 5 context + * @param cursor the iterator cursor, returned by krb5_cc_cache_get_first() + * @param id next ccache + * + * @return Return 0 or an error code. Returns KRB5_CC_END when the end + * of caches is reached, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_cache_next ( krb5_context /*context*/, krb5_cc_cache_cursor /*cursor*/, krb5_ccache */*id*/); +/** + * Clear `mcreds' so it can be used with krb5_cc_retrieve_cred + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_cc_clear_mcred (krb5_creds */*mcred*/); +/** + * Stop using the ccache `id' and free the related resources. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_close ( krb5_context /*context*/, krb5_ccache /*id*/); +/** + * Just like krb5_cc_copy_match_f(), but copy everything. + * + * @ingroup @krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_copy_cache ( krb5_context /*context*/, const krb5_ccache /*from*/, krb5_ccache /*to*/); +/** + * MIT compat glue + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_copy_creds ( krb5_context /*context*/, const krb5_ccache /*from*/, krb5_ccache /*to*/); +/** + * Copy the contents of `from' to `to' if the given match function + * return true. + * + * @param context A Kerberos 5 context. + * @param from the cache to copy data from. + * @param to the cache to copy data to. + * @param match a match function that should return TRUE if cred argument should be copied, if NULL, all credentials are copied. + * @param matchctx context passed to match function. + * @param matched set to true if there was a credential that matched, may be NULL. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_copy_match_f ( krb5_context /*context*/, @@ -617,25 +1069,66 @@ krb5_cc_copy_match_f ( void */*matchctx*/, unsigned int */*matched*/); +/** + * Open the default ccache in `id'. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_default ( krb5_context /*context*/, krb5_ccache */*id*/); +/** + * Return a pointer to a context static string containing the default + * ccache name. + * + * @return String to the default credential cache name. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_cc_default_name (krb5_context /*context*/); +/** + * Remove the ccache `id'. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_destroy ( krb5_context /*context*/, krb5_ccache /*id*/); +/** + * Destroy the cursor `cursor'. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_end_seq_get ( krb5_context /*context*/, const krb5_ccache /*id*/, krb5_cc_cursor */*cursor*/); +/** + * Generate a new ccache of type `ops' in `id'. + * + * Deprecated: use krb5_cc_new_unique() instead. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_gen_new ( krb5_context /*context*/, @@ -643,6 +1136,19 @@ krb5_cc_gen_new ( krb5_ccache */*id*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Get some configuration for the credential cache in the cache. + * + * @param context a Keberos context + * @param id the credential cache to store the data for + * @param principal configuration for a specific principal, if + * NULL, global for the whole cache. + * @param name name under which the configuraion is stored. + * @param data data to fetched, free with krb5_data_free() + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_config ( krb5_context /*context*/, @@ -651,85 +1157,230 @@ krb5_cc_get_config ( const char */*name*/, krb5_data */*data*/); +/** + * Get the flags of `id', store them in `flags'. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_flags ( krb5_context /*context*/, krb5_ccache /*id*/, krb5_flags */*flags*/); +/** + * Return a friendly name on credential cache. Free the result with krb5_xfree(). + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_friendly_name ( krb5_context /*context*/, krb5_ccache /*id*/, char **/*name*/); +/** + * Return the complete resolvable name the cache + + * @param context a Keberos context + * @param id return pointer to a found credential cache + * @param str the returned name of a credential cache, free with krb5_xfree() + * + * @return Returns 0 or an error (and then *str is set to NULL). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_full_name ( krb5_context /*context*/, krb5_ccache /*id*/, char **/*str*/); +/** + * Get the time offset betwen the client and the KDC + * + * If the backend doesn't support KDC offset, use the context global setting. + * + * @param context A Kerberos 5 context. + * @param id a credential cache + * @param offset the offset in seconds + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_kdc_offset ( krb5_context /*context*/, krb5_ccache /*id*/, krb5_deltat */*offset*/); +/** + * Get the lifetime of the initial ticket in the cache + * + * Get the lifetime of the initial ticket in the cache, if the initial + * ticket was not found, the error code KRB5_CC_END is returned. + * + * @param context A Kerberos 5 context. + * @param id a credential cache + * @param t the relative lifetime of the initial ticket + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_lifetime ( krb5_context /*context*/, krb5_ccache /*id*/, time_t */*t*/); +/** + * Return the name of the ccache `id' + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_cc_get_name ( krb5_context /*context*/, krb5_ccache /*id*/); +/** + * Return krb5_cc_ops of a the ccache `id'. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION const krb5_cc_ops * KRB5_LIB_CALL krb5_cc_get_ops ( krb5_context /*context*/, krb5_ccache /*id*/); +/** + * Get the cc ops that is registered in `context' to handle the + * prefix. prefix can be a complete credential cache name or a + * prefix, the function will only use part up to the first colon (:) + * if there is one. If prefix the argument is NULL, the default ccache + * implemtation is returned. + * + * @return Returns NULL if ops not found. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION const krb5_cc_ops * KRB5_LIB_CALL krb5_cc_get_prefix_ops ( krb5_context /*context*/, const char */*prefix*/); +/** + * Return the principal of `id' in `principal'. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_principal ( krb5_context /*context*/, krb5_ccache /*id*/, krb5_principal */*principal*/); +/** + * Return the type of the ccache `id'. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_cc_get_type ( krb5_context /*context*/, krb5_ccache /*id*/); +/** + * Return the version of `id'. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_version ( krb5_context /*context*/, const krb5_ccache /*id*/); +/** + * Create a new ccache in `id' for `primary_principal'. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_initialize ( krb5_context /*context*/, krb5_ccache /*id*/, krb5_principal /*primary_principal*/); +/** + * Return the last time the credential cache was modified. + * + * @param context A Kerberos 5 context + * @param id The credential cache to probe + * @param mtime the last modification time, set to 0 on error. + + * @return Return 0 or and error. See krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_last_change_time ( krb5_context /*context*/, krb5_ccache /*id*/, krb5_timestamp */*mtime*/); +/** + * Move the content from one credential cache to another. The + * operation is an atomic switch. + * + * @param context a Keberos context + * @param from the credential cache to move the content from + * @param to the credential cache to move the content to + + * @return On sucess, from is freed. On failure, error code is + * returned and from and to are both still allocated, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_move ( krb5_context /*context*/, krb5_ccache /*from*/, krb5_ccache /*to*/); +/** + * Generates a new unique ccache of `type` in `id'. If `type' is NULL, + * the library chooses the default credential cache type. The supplied + * `hint' (that can be NULL) is a string that the credential cache + * type can use to base the name of the credential on, this is to make + * it easier for the user to differentiate the credentials. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_new_unique ( krb5_context /*context*/, @@ -737,6 +1388,15 @@ krb5_cc_new_unique ( const char */*hint*/, krb5_ccache */*id*/); +/** + * Retrieve the next cred pointed to by (`id', `cursor') in `creds' + * and advance `cursor'. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_next_cred ( krb5_context /*context*/, @@ -744,12 +1404,32 @@ krb5_cc_next_cred ( krb5_cc_cursor */*cursor*/, krb5_creds */*creds*/); +/** + * Add a new ccache type with operations `ops', overwriting any + * existing one if `override'. + * + * @param context a Keberos context + * @param ops type of plugin symbol + * @param override flag to select if the registration is to overide + * an existing ops with the same name. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_register ( krb5_context /*context*/, const krb5_cc_ops */*ops*/, krb5_boolean /*override*/); +/** + * Remove the credential identified by `cred', `which' from `id'. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_remove_cred ( krb5_context /*context*/, @@ -757,12 +1437,43 @@ krb5_cc_remove_cred ( krb5_flags /*which*/, krb5_creds */*cred*/); +/** + * Find and allocate a ccache in `id' from the specification in `residual'. + * If the ccache name doesn't contain any colon, interpret it as a file name. + * + * @param context a Keberos context. + * @param name string name of a credential cache. + * @param id return pointer to a found credential cache. + * + * @return Return 0 or an error code. In case of an error, id is set + * to NULL, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_resolve ( krb5_context /*context*/, const char */*name*/, krb5_ccache */*id*/); +/** + * Retrieve the credential identified by `mcreds' (and `whichfields') + * from `id' in `creds'. 'creds' must be free by the caller using + * krb5_free_cred_contents. + * + * @param context A Kerberos 5 context + * @param id a Kerberos 5 credential cache + * @param whichfields what fields to use for matching credentials, same + * flags as whichfields in krb5_compare_creds() + * @param mcreds template credential to use for comparing + * @param creds returned credential, free with krb5_free_cred_contents() + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_retrieve_cred ( krb5_context /*context*/, @@ -771,6 +1482,20 @@ krb5_cc_retrieve_cred ( const krb5_creds */*mcreds*/, krb5_creds */*creds*/); +/** + * Store some configuration for the credential cache in the cache. + * Existing configuration under the same name is over-written. + * + * @param context a Keberos context + * @param id the credential cache to store the data for + * @param principal configuration for a specific principal, if + * NULL, global for the whole cache. + * @param name name under which the configuraion is stored. + * @param data data to store, if NULL, configure is removed. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_set_config ( krb5_context /*context*/, @@ -779,73 +1504,209 @@ krb5_cc_set_config ( const char */*name*/, krb5_data */*data*/); +/** + * Set the default cc name for `context' to `name'. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_set_default_name ( krb5_context /*context*/, const char */*name*/); +/** + * Set the flags of `id' to `flags'. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_set_flags ( krb5_context /*context*/, krb5_ccache /*id*/, krb5_flags /*flags*/); +/** + * Set the friendly name on credential cache. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_set_friendly_name ( krb5_context /*context*/, krb5_ccache /*id*/, const char */*name*/); +/** + * Set the time offset betwen the client and the KDC + * + * If the backend doesn't support KDC offset, use the context global setting. + * + * @param context A Kerberos 5 context. + * @param id a credential cache + * @param offset the offset in seconds + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_set_kdc_offset ( krb5_context /*context*/, krb5_ccache /*id*/, krb5_deltat /*offset*/); +/** + * Start iterating over `id', `cursor' is initialized to the + * beginning. Caller must free the cursor with krb5_cc_end_seq_get(). + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_start_seq_get ( krb5_context /*context*/, const krb5_ccache /*id*/, krb5_cc_cursor */*cursor*/); +/** + * Store `creds' in the ccache `id'. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_store_cred ( krb5_context /*context*/, krb5_ccache /*id*/, krb5_creds */*creds*/); +/** + * Return true if the default credential cache support switch + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_cc_support_switch ( krb5_context /*context*/, const char */*type*/); +/** + * Switch the default default credential cache for a specific + * credcache type (and name for some implementations). + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_switch ( krb5_context /*context*/, krb5_ccache /*id*/); +/** + * End an iteration and free all resources, can be done before end is reached. + * + * @param context A Kerberos 5 context + * @param cursor the iteration cursor to be freed. + * + * @return Return 0 or and error, KRB5_CC_END is returned at the end + * of iteration. See krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cccol_cursor_free ( krb5_context /*context*/, krb5_cccol_cursor */*cursor*/); +/** + * Get a new cache interation cursor that will interate over all + * credentials caches independent of type. + * + * @param context a Keberos context + * @param cursor passed into krb5_cccol_cursor_next() and free with krb5_cccol_cursor_free(). + * + * @return Returns 0 or and error code, see krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cccol_cursor_new ( krb5_context /*context*/, krb5_cccol_cursor */*cursor*/); +/** + * Get next credential cache from the iteration. + * + * @param context A Kerberos 5 context + * @param cursor the iteration cursor + * @param cache the returned cursor, pointer is set to NULL on failure + * and a cache on success. The returned cache needs to be freed + * with krb5_cc_close() or destroyed with krb5_cc_destroy(). + * MIT Kerberos behavies slightly diffrent and sets cache to NULL + * when all caches are iterated over and return 0. + * + * @return Return 0 or and error, KRB5_CC_END is returned at the end + * of iteration. See krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cccol_cursor_next ( krb5_context /*context*/, krb5_cccol_cursor /*cursor*/, krb5_ccache */*cache*/); +/** + * Return the last modfication time for a cache collection. The query + * can be limited to a specific cache type. If the function return 0 + * and mtime is 0, there was no credentials in the caches. + * + * @param context A Kerberos 5 context + * @param type The credential cache to probe, if NULL, all type are traversed. + * @param mtime the last modification time, set to 0 on error. + + * @return Return 0 or and error. See krb5_get_error_message(). + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cccol_last_change_time ( krb5_context /*context*/, const char */*type*/, krb5_timestamp */*mtime*/); +/** + * Deprecated: krb5_change_password() is deprecated, use krb5_set_password(). + * + * @param context a Keberos context + * @param creds + * @param newpw + * @param result_code + * @param result_code_string + * @param result_string + * + * @return On sucess password is changed. + + * @ingroup @krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_change_password ( krb5_context /*context*/, @@ -898,6 +1759,18 @@ krb5_checksumsize ( krb5_cksumtype /*type*/, size_t */*size*/); +/** + * Return the coresponding encryption type for a checksum type. + * + * @param context Kerberos context + * @param ctype The checksum type to get the result enctype for + * @param etype The returned encryption, when the matching etype is + * not found, etype is set to ETYPE_NULL. + * + * @return Return an error code for an failure or 0 on success. + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cksumtype_to_enctype ( krb5_context /*context*/, @@ -909,9 +1782,27 @@ krb5_cksumtype_valid ( krb5_context /*context*/, krb5_cksumtype /*ctype*/); +/** + * Clears the error message from the Kerberos 5 context. + * + * @param context The Kerberos 5 context to clear + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_clear_error_message (krb5_context /*context*/); +/** + * Clear the error message returned by krb5_get_error_string(). + * + * Deprecated: use krb5_clear_error_message() + * + * @param context Kerberos context + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_clear_error_string (krb5_context /*context*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); @@ -921,6 +1812,32 @@ krb5_closelog ( krb5_context /*context*/, krb5_log_facility */*fac*/); +/** + * Return TRUE if `mcreds' and `creds' are equal (`whichfields' + * determines what equal means). + * + * + * The following flags, set in whichfields affects the comparison: + * - KRB5_TC_MATCH_SRV_NAMEONLY Consider all realms equal when comparing the service principal. + * - KRB5_TC_MATCH_KEYTYPE Compare enctypes. + * - KRB5_TC_MATCH_FLAGS_EXACT Make sure that the ticket flags are identical. + * - KRB5_TC_MATCH_FLAGS Make sure that all ticket flags set in mcreds are also present in creds . + * - KRB5_TC_MATCH_TIMES_EXACT Compares the ticket times exactly. + * - KRB5_TC_MATCH_TIMES Compares only the expiration times of the creds. + * - KRB5_TC_MATCH_AUTHDATA Compares the authdata fields. + * - KRB5_TC_MATCH_2ND_TKT Compares the second tickets (used by user-to-user authentication). + * - KRB5_TC_MATCH_IS_SKEY Compares the existance of the second ticket. + * + * @param context Kerberos 5 context. + * @param whichfields which fields to compare. + * @param mcreds cred to compare with. + * @param creds cred to compare with. + * + * @return return TRUE if mcred and creds are equal, FALSE if not. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_compare_creds ( krb5_context /*context*/, @@ -928,20 +1845,74 @@ krb5_compare_creds ( const krb5_creds * /*mcreds*/, const krb5_creds * /*creds*/); +/** + * Free configuration file section, the result of + * krb5_config_parse_file() and krb5_config_parse_file_multi(). + * + * @param context A Kerberos 5 context + * @param s the configuration section to free + * + * @return returns 0 on successes, otherwise an error code, see + * krb5_get_error_message() + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_config_file_free ( krb5_context /*context*/, krb5_config_section */*s*/); +/** + * Free the resulting strings from krb5_config-get_strings() and + * krb5_config_vget_strings(). + * + * @param strings strings to free + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_config_free_strings (char **/*strings*/); +/** + * Like krb5_config_get_bool() but with a va_list list of + * configuration selection. + * + * Configuration value to a boolean value, where yes/true and any + * non-zero number means TRUE and other value is FALSE. + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param ... a list of names, terminated with NULL. + * + * @return TRUE or FALSE + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_config_get_bool ( krb5_context /*context*/, const krb5_config_section */*c*/, ...); +/** + * krb5_config_get_bool_default() will convert the configuration + * option value to a boolean value, where yes/true and any non-zero + * number means TRUE and other value is FALSE. + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param def_value the default value to return if no configuration + * found in the database. + * @param ... a list of names, terminated with NULL. + * + * @return TRUE or FALSE + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_config_get_bool_default ( krb5_context /*context*/, @@ -962,18 +1933,60 @@ krb5_config_get_int_default ( int /*def_value*/, ...); +/** + * Get a list of configuration binding list for more processing + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param ... a list of names, terminated with NULL. + * + * @return NULL if configuration list is not found, a list otherwise + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION const krb5_config_binding * KRB5_LIB_CALL krb5_config_get_list ( krb5_context /*context*/, const krb5_config_section */*c*/, ...); +/** + * Returns a "const char *" to a string in the configuration database. + * The string may not be valid after a reload of the configuration + * database so a caller should make a local copy if it needs to keep + * the string. + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param ... a list of names, terminated with NULL. + * + * @return NULL if configuration string not found, a string otherwise + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_config_get_string ( krb5_context /*context*/, const krb5_config_section */*c*/, ...); +/** + * Like krb5_config_get_string(), but instead of returning NULL, + * instead return a default value. + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param def_value the default value to return if no configuration + * found in the database. + * @param ... a list of names, terminated with NULL. + * + * @return a configuration string + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_config_get_string_default ( krb5_context /*context*/, @@ -981,18 +1994,57 @@ krb5_config_get_string_default ( const char */*def_value*/, ...); +/** + * Get a list of configuration strings, free the result with + * krb5_config_free_strings(). + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param ... a list of names, terminated with NULL. + * + * @return TRUE or FALSE + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION char** KRB5_LIB_CALL krb5_config_get_strings ( krb5_context /*context*/, const krb5_config_section */*c*/, ...); +/** + * Get the time from the configuration file using a relative time, for example: 1h30s + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param ... a list of names, terminated with NULL. + * + * @return parsed the time or -1 on error + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_config_get_time ( krb5_context /*context*/, const krb5_config_section */*c*/, ...); +/** + * Get the time from the configuration file using a relative time, for example: 1h30s + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param def_value the default value to return if no configuration + * found in the database. + * @param ... a list of names, terminated with NULL. + * + * @return parsed the time (or def_value on parse error) + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_config_get_time_default ( krb5_context /*context*/, @@ -1000,18 +2052,43 @@ krb5_config_get_time_default ( int /*def_value*/, ...); +/** + * If the fname starts with "~/" parse configuration file in the + * current users home directory. The behavior can be disabled and + * enabled by calling krb5_set_home_dir_access(). + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_config_parse_file ( krb5_context /*context*/, const char */*fname*/, krb5_config_section **/*res*/); +/** + * Parse a configuration file and add the result into res. This + * interface can be used to parse several configuration files into one + * resulting krb5_config_section by calling it repeatably. + * + * @param context a Kerberos 5 context. + * @param fname a file name to a Kerberos configuration file + * @param res the returned result, must be free with krb5_free_config_files(). + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_config_parse_file_multi ( krb5_context /*context*/, const char */*fname*/, krb5_config_section **/*res*/); +/** + * Deprecated: configuration files are not strings + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_config_parse_string_multi ( krb5_context /*context*/, @@ -1019,12 +2096,44 @@ krb5_config_parse_string_multi ( krb5_config_section **/*res*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * krb5_config_get_bool() will convert the configuration + * option value to a boolean value, where yes/true and any non-zero + * number means TRUE and other value is FALSE. + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param args a va_list of arguments + * + * @return TRUE or FALSE + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_config_vget_bool ( krb5_context /*context*/, const krb5_config_section */*c*/, va_list /*args*/); +/** + * Like krb5_config_get_bool_default() but with a va_list list of + * configuration selection. + * + * Configuration value to a boolean value, where yes/true and any + * non-zero number means TRUE and other value is FALSE. + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param def_value the default value to return if no configuration + * found in the database. + * @param args a va_list of arguments + * + * @return TRUE or FALSE + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_config_vget_bool_default ( krb5_context /*context*/, @@ -1045,18 +2154,57 @@ krb5_config_vget_int_default ( int /*def_value*/, va_list /*args*/); +/** + * Get a list of configuration binding list for more processing + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param args a va_list of arguments + * + * @return NULL if configuration list is not found, a list otherwise + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION const krb5_config_binding * KRB5_LIB_CALL krb5_config_vget_list ( krb5_context /*context*/, const krb5_config_section */*c*/, va_list /*args*/); +/** + * Like krb5_config_get_string(), but uses a va_list instead of ... + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param args a va_list of arguments + * + * @return NULL if configuration string not found, a string otherwise + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_config_vget_string ( krb5_context /*context*/, const krb5_config_section */*c*/, va_list /*args*/); +/** + * Like krb5_config_vget_string(), but instead of returning NULL, + * instead return a default value. + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param def_value the default value to return if no configuration + * found in the database. + * @param args a va_list of arguments + * + * @return a configuration string + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_config_vget_string_default ( krb5_context /*context*/, @@ -1064,18 +2212,60 @@ krb5_config_vget_string_default ( const char */*def_value*/, va_list /*args*/); +/** + * Get a list of configuration strings, free the result with + * krb5_config_free_strings(). + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param args a va_list of arguments + * + * @return TRUE or FALSE + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION char ** KRB5_LIB_CALL krb5_config_vget_strings ( krb5_context /*context*/, const krb5_config_section */*c*/, va_list /*args*/); +/** + * Get the time from the configuration file using a relative time, for example: 1h30s + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param args a va_list of arguments + * + * @return parsed the time or -1 on error + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_config_vget_time ( krb5_context /*context*/, const krb5_config_section */*c*/, va_list /*args*/); +/** + * Get the time from the configuration file using a relative time. + * + * Like krb5_config_get_time_default() but with a va_list list of + * configuration selection. + * + * @param context A Kerberos 5 context. + * @param c a configuration section, or NULL to use the section from context + * @param def_value the default value to return if no configuration + * found in the database. + * @param args a va_list of arguments + * + * @return parsed the time (or def_value on parse error) + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_config_vget_time_default ( krb5_context /*context*/, @@ -1083,12 +2273,38 @@ krb5_config_vget_time_default ( int /*def_value*/, va_list /*args*/); +/** + * krb5_copy_address copies the content of address + * inaddr to outaddr. + * + * @param context a Keberos context + * @param inaddr pointer to source address + * @param outaddr pointer to destination address + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_address ( krb5_context /*context*/, const krb5_address */*inaddr*/, krb5_address */*outaddr*/); +/** + * krb5_copy_addresses copies the content of addresses + * inaddr to outaddr. + * + * @param context a Keberos context + * @param inaddr pointer to source addresses + * @param outaddr pointer to destination addresses + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_addresses ( krb5_context /*context*/, @@ -1101,53 +2317,169 @@ krb5_copy_checksum ( const krb5_checksum */*old*/, krb5_checksum **/*new*/); +/** + * Make a copy for the Kerberos 5 context, the new krb5_context shoud + * be freed with krb5_free_context(). + * + * @param context the Kerberos context to copy + * @param out the copy of the Kerberos, set to NULL error. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_context ( krb5_context /*context*/, krb5_context */*out*/); +/** + * Copy krb5_creds. + * + * @param context Kerberos 5 context. + * @param incred source credential + * @param outcred destination credential, free with krb5_free_creds(). + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_creds ( krb5_context /*context*/, const krb5_creds */*incred*/, krb5_creds **/*outcred*/); +/** + * Copy content of krb5_creds. + * + * @param context Kerberos 5 context. + * @param incred source credential + * @param c destination credential, free with krb5_free_cred_contents(). + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_creds_contents ( krb5_context /*context*/, const krb5_creds */*incred*/, krb5_creds */*c*/); +/** + * Copy the data into a newly allocated krb5_data. + * + * @param context Kerberos 5 context. + * @param indata the krb5_data data to copy + * @param outdata new krb5_date to copy too. Free with krb5_free_data(). + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_data ( krb5_context /*context*/, const krb5_data */*indata*/, krb5_data **/*outdata*/); +/** + * Copy the list of realms from `from' to `to'. + * + * @param context Kerberos 5 context. + * @param from list of realms to copy from. + * @param to list of realms to copy to, free list of krb5_free_host_realm(). + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_host_realm ( krb5_context /*context*/, const krb5_realm */*from*/, krb5_realm **/*to*/); +/** + * Copy a keyblock, free the output keyblock with + * krb5_free_keyblock(). + * + * @param context a Kerberos 5 context + * @param inblock the key to copy + * @param to the output key. + * + * @return 0 on success or a Kerberos 5 error code + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_keyblock ( krb5_context /*context*/, const krb5_keyblock */*inblock*/, krb5_keyblock **/*to*/); +/** + * Copy a keyblock, free the output keyblock with + * krb5_free_keyblock_contents(). + * + * @param context a Kerberos 5 context + * @param inblock the key to copy + * @param to the output key. + * + * @return 0 on success or a Kerberos 5 error code + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_keyblock_contents ( krb5_context /*context*/, const krb5_keyblock */*inblock*/, krb5_keyblock */*to*/); +/** + * Copy a principal + * + * @param context A Kerberos context. + * @param inprinc principal to copy + * @param outprinc copied principal, free with krb5_free_principal() + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_principal ( krb5_context /*context*/, krb5_const_principal /*inprinc*/, krb5_principal */*outprinc*/); +/** + * Copy ticket and content + * + * @param context a Kerberos 5 context + * @param from ticket to copy + * @param to new copy of ticket, free with krb5_free_ticket() + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_ticket ( krb5_context /*context*/, @@ -1164,6 +2496,20 @@ krb5_create_checksum ( size_t /*len*/, Checksum */*result*/); +/** + * Create a Kerberos message checksum. + * + * @param context Kerberos context + * @param crypto Kerberos crypto context + * @param usage Key usage for this buffer + * @param data array of buffers to process + * @param num_data length of array + * @param type output data + * + * @return Return an error code or 0. + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_create_checksum_iov ( krb5_context /*context*/, @@ -1173,14 +2519,52 @@ krb5_create_checksum_iov ( unsigned int /*num_data*/, krb5_cksumtype */*type*/); +/** + * Returns the ticket flags for the credentials in creds. + * See also krb5_ticket_get_flags(). + * + * @param creds credential to get ticket flags from + * + * @return ticket flags + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION unsigned long KRB5_LIB_CALL krb5_creds_get_ticket_flags (krb5_creds */*creds*/); +/** + * Free a crypto context created by krb5_crypto_init(). + * + * @param context Kerberos context + * @param crypto crypto context to free + * + * @return Return an error code or 0. + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_destroy ( krb5_context /*context*/, krb5_crypto /*crypto*/); +/** + * The FX-CF2 key derivation function, used in FAST and preauth framework. + * + * @param context Kerberos 5 context + * @param crypto1 first key to combine + * @param crypto2 second key to combine + * @param pepper1 factor to combine with first key to garante uniqueness + * @param pepper2 factor to combine with second key to garante uniqueness + * @param enctype the encryption type of the resulting key + * @param res allocated key, free with krb5_free_keyblock_contents() + * + * @return Return an error code or 0. + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_fx_cf2 ( krb5_context /*context*/, @@ -1197,30 +2581,96 @@ krb5_crypto_get_checksum_type ( krb5_crypto /*crypto*/, krb5_cksumtype */*type*/); +/** + * Return the blocksize used algorithm referenced by the crypto context + * + * @param context Kerberos context + * @param crypto crypto context to query + * @param blocksize the resulting blocksize + * + * @return Return an error code or 0. + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_getblocksize ( krb5_context /*context*/, krb5_crypto /*crypto*/, size_t */*blocksize*/); +/** + * Return the confounder size used by the crypto context + * + * @param context Kerberos context + * @param crypto crypto context to query + * @param confoundersize the returned confounder size + * + * @return Return an error code or 0. + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_getconfoundersize ( krb5_context /*context*/, krb5_crypto /*crypto*/, size_t */*confoundersize*/); +/** + * Return the encryption type used by the crypto context + * + * @param context Kerberos context + * @param crypto crypto context to query + * @param enctype the resulting encryption type + * + * @return Return an error code or 0. + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_getenctype ( krb5_context /*context*/, krb5_crypto /*crypto*/, krb5_enctype */*enctype*/); +/** + * Return the padding size used by the crypto context + * + * @param context Kerberos context + * @param crypto crypto context to query + * @param padsize the return padding size + * + * @return Return an error code or 0. + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_getpadsize ( krb5_context /*context*/, krb5_crypto /*crypto*/, size_t */*padsize*/); +/** + * Create a crypto context used for all encryption and signature + * operation. The encryption type to use is taken from the key, but + * can be overridden with the enctype parameter. This can be useful + * for encryptions types which is compatiable (DES for example). + * + * To free the crypto context, use krb5_crypto_destroy(). + * + * @param context Kerberos context + * @param key the key block information with all key data + * @param etype the encryption type + * @param crypto the resulting crypto context + * + * @return Return an error code or 0. + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_init ( krb5_context /*context*/, @@ -1260,35 +2710,113 @@ krb5_crypto_prf_length ( krb5_enctype /*type*/, size_t */*length*/); +/** + * Allocate data of and krb5_data. + * + * @param p krb5_data to allocate. + * @param len size to allocate. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_data_alloc ( krb5_data */*p*/, int /*len*/); +/** + * Compare to data. + * + * @param data1 krb5_data to compare + * @param data2 krb5_data to compare + * + * @return return the same way as memcmp(), useful when sorting. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_data_cmp ( const krb5_data */*data1*/, const krb5_data */*data2*/); +/** + * Copy the data of len into the krb5_data. + * + * @param p krb5_data to copy into. + * @param data data to copy.. + * @param len new size. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_data_copy ( krb5_data */*p*/, const void */*data*/, size_t /*len*/); +/** + * Compare to data not exposing timing information from the checksum data + * + * @param data1 krb5_data to compare + * @param data2 krb5_data to compare + * + * @return returns zero for same data, otherwise non zero. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_data_ct_cmp ( const krb5_data */*data1*/, const krb5_data */*data2*/); +/** + * Free the content of krb5_data structure, its ok to free a zeroed + * structure (with memset() or krb5_data_zero()). When done, the + * structure will be zeroed. The same function is called + * krb5_free_data_contents() in MIT Kerberos. + * + * @param p krb5_data to free. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_data_free (krb5_data */*p*/); +/** + * Grow (or shrink) the content of krb5_data to a new size. + * + * @param p krb5_data to free. + * @param len new size. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_data_realloc ( krb5_data */*p*/, int /*len*/); +/** + * Reset the (potentially uninitalized) krb5_data structure. + * + * @param p krb5_data to reset. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_data_zero (krb5_data */*p*/); @@ -1387,6 +2915,27 @@ krb5_decrypt_EncryptedData ( const EncryptedData */*e*/, krb5_data */*result*/); +/** + * Inline decrypt a Kerberos message. + * + * @param context Kerberos context + * @param crypto Kerberos crypto context + * @param usage Key usage for this buffer + * @param data array of buffers to process + * @param num_data length of array + * @param ivec initial cbc/cts vector + * + * @return Return an error code or 0. + * @ingroup krb5_crypto + * + * 1. KRB5_CRYPTO_TYPE_HEADER + * 2. one KRB5_CRYPTO_TYPE_DATA and array [0,...] of KRB5_CRYPTO_TYPE_SIGN_ONLY in + * any order, however the receiver have to aware of the + * order. KRB5_CRYPTO_TYPE_SIGN_ONLY is commonly used unencrypoted + * protocol headers and trailers. The output data will be of same + * size as the input data or shorter. + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_decrypt_iov_ivec ( krb5_context /*context*/, @@ -1477,6 +3026,19 @@ krb5_digest_init_request ( krb5_realm /*realm*/, krb5_ccache /*ccache*/); +/** + * Get the supported/allowed mechanism for this principal. + * + * @param context A Keberos context. + * @param realm The realm of the KDC. + * @param ccache The credential cache to use when talking to the KDC. + * @param flags The supported mechanism. + * + * @return Return an error code or 0. + * + * @ingroup krb5_digest + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_digest_probe ( krb5_context /*context*/, @@ -1614,6 +3176,17 @@ krb5_domain_x500_encode ( unsigned int /*num_realms*/, krb5_data */*encoding*/); +/** + * Convert the getaddrinfo() error code to a Kerberos et error code. + * + * @param eai_errno contains the error code from getaddrinfo(). + * @param system_error should have the value of errno after the failed getaddrinfo(). + * + * @return Kerberos error code representing the EAI errors. + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_eai_to_heim_errno ( int /*eai_errno*/, @@ -1710,6 +3283,30 @@ krb5_encrypt_EncryptedData ( int /*kvno*/, EncryptedData */*result*/); +/** + * Inline encrypt a kerberos message + * + * @param context Kerberos context + * @param crypto Kerberos crypto context + * @param usage Key usage for this buffer + * @param data array of buffers to process + * @param num_data length of array + * @param ivec initial cbc/cts vector + * + * @return Return an error code or 0. + * @ingroup krb5_crypto + * + * Kerberos encrypted data look like this: + * + * 1. KRB5_CRYPTO_TYPE_HEADER + * 2. array [1,...] KRB5_CRYPTO_TYPE_DATA and array [0,...] + * KRB5_CRYPTO_TYPE_SIGN_ONLY in any order, however the receiver + * have to aware of the order. KRB5_CRYPTO_TYPE_SIGN_ONLY is + * commonly used headers and trailers. + * 3. KRB5_CRYPTO_TYPE_PADDING, at least on padsize long if padsize > 1 + * 4. KRB5_CRYPTO_TYPE_TRAILER + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_encrypt_iov_ivec ( krb5_context /*context*/, @@ -1729,11 +3326,33 @@ krb5_encrypt_ivec ( krb5_data */*result*/, void */*ivec*/); +/** + * Disable encryption type + * + * @param context Kerberos 5 context + * @param enctype encryption type to disable + * + * @return Return an error code or 0. + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_enctype_disable ( krb5_context /*context*/, krb5_enctype /*enctype*/); +/** + * Enable encryption type + * + * @param context Kerberos 5 context + * @param enctype encryption type to enable + * + * @return Return an error code or 0. + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_enctype_enable ( krb5_context /*context*/, @@ -1763,11 +3382,27 @@ krb5_enctype_to_string ( krb5_enctype /*etype*/, char **/*string*/); +/** + * Check if a enctype is valid, return 0 if it is. + * + * @param context Kerberos context + * @param etype enctype to check if its valid or not + * + * @return Return an error code for an failure or 0 on success (enctype valid). + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_enctype_valid ( krb5_context /*context*/, krb5_enctype /*etype*/); +/** + * Deprecated: keytypes doesn't exists, they are really enctypes. + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_enctypes_compatible_keys ( krb5_context /*context*/, @@ -1778,6 +3413,18 @@ krb5_enctypes_compatible_keys ( krb5_error_code krb5_enomem (krb5_context /*context*/); +/** + * Log a warning to the log, default stderr, include bthe error from + * the last failure and then exit. + * + * @param context A Kerberos 5 context + * @param eval the exit code to exit with + * @param code error code of the last error + * @param fmt message to print + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_err ( krb5_context /*context*/, @@ -1785,7 +3432,7 @@ krb5_err ( krb5_error_code /*code*/, const char */*fmt*/, ...) - __attribute__ ((noreturn, format (printf, 4, 5))); + __attribute__ ((__noreturn__, __format__ (__printf__, 4, 5))); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_error_from_rd_error ( @@ -1793,13 +3440,38 @@ krb5_error_from_rd_error ( const krb5_error */*error*/, const krb5_creds */*creds*/); +/** + * Log a warning to the log, default stderr, and then exit. + * + * @param context A Kerberos 5 context + * @param eval the exit code to exit with + * @param fmt message to print + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_errx ( krb5_context /*context*/, int /*eval*/, const char */*fmt*/, ...) - __attribute__ ((noreturn, format (printf, 3, 4))); + __attribute__ ((__noreturn__, __format__ (__printf__, 3, 4))); + +/** + * krb5_expand_hostname() tries to make orig_hostname into a more + * canonical one in the newly allocated space returned in + * new_hostname. + + * @param context a Keberos context + * @param orig_hostname hostname to canonicalise. + * @param new_hostname output hostname, caller must free hostname with + * krb5_xfree(). + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_support + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_expand_hostname ( @@ -1807,6 +3479,24 @@ krb5_expand_hostname ( const char */*orig_hostname*/, char **/*new_hostname*/); +/** + * krb5_expand_hostname_realms() expands orig_hostname to a name we + * believe to be a hostname in newly allocated space in new_hostname + * and return the realms new_hostname is believed to belong to in + * realms. + * + * @param context a Keberos context + * @param orig_hostname hostname to canonicalise. + * @param new_hostname output hostname, caller must free hostname with + * krb5_xfree(). + * @param realms output possible realms, is an array that is terminated + * with NULL. Caller must free with krb5_free_host_realm(). + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_expand_hostname_realms ( krb5_context /*context*/, @@ -1829,11 +3519,35 @@ krb5_format_time ( size_t /*len*/, krb5_boolean /*include_time*/); +/** + * krb5_free_address frees the data stored in the address that is + * alloced with any of the krb5_address functions. + * + * @param context a Keberos context + * @param address addresss to be freed. + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_address ( krb5_context /*context*/, krb5_address */*address*/); +/** + * krb5_free_addresses frees the data stored in the address that is + * alloced with any of the krb5_address functions. + * + * @param context a Keberos context + * @param addresses addressses to be freed. + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_addresses ( krb5_context /*context*/, @@ -1859,33 +3573,103 @@ krb5_free_checksum_contents ( krb5_context /*context*/, krb5_checksum */*cksum*/); +/** + * Free a list of configuration files. + * + * @param filenames list, terminated with a NULL pointer, to be + * freed. NULL is an valid argument. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_config_files (char **/*filenames*/); +/** + * Frees the krb5_context allocated by krb5_init_context(). + * + * @param context context to be freed. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_context (krb5_context /*context*/); +/** + * Free content of krb5_creds. + * + * @param context Kerberos 5 context. + * @param c krb5_creds to free. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_cred_contents ( krb5_context /*context*/, krb5_creds */*c*/); +/** + * Free krb5_creds. + * + * @param context Kerberos 5 context. + * @param c krb5_creds to free. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_creds ( krb5_context /*context*/, krb5_creds */*c*/); +/** + * Deprecated: use krb5_free_cred_contents() + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_creds_contents ( krb5_context /*context*/, krb5_creds */*c*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Free krb5_data (and its content). + * + * @param context Kerberos 5 context. + * @param p krb5_data to free. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_data ( krb5_context /*context*/, krb5_data */*p*/); +/** + * Same as krb5_data_free(). MIT compat. + * + * Deprecated: use krb5_data_free(). + * + * @param context Kerberos 5 context. + * @param data krb5_data to free. + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_data_contents ( krb5_context /*context*/, @@ -1907,32 +3691,89 @@ krb5_free_error_contents ( krb5_context /*context*/, krb5_error */*error*/); +/** + * Free the error message returned by krb5_get_error_message(). + * + * @param context Kerberos context + * @param msg error message to free, returned byg + * krb5_get_error_message(). + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_error_message ( krb5_context /*context*/, const char */*msg*/); +/** + * Free the error message returned by krb5_get_error_string(). + * + * Deprecated: use krb5_free_error_message() + * + * @param context Kerberos context + * @param str error message to free + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_error_string ( krb5_context /*context*/, char */*str*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Free all memory allocated by `realmlist' + * + * @param context A Kerberos 5 context. + * @param realmlist realmlist to free, NULL is ok + * + * @return a Kerberos error code, always 0. + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_host_realm ( krb5_context /*context*/, krb5_realm */*realmlist*/); +/** + * Variable containing the FILE based credential cache implemention. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_kdc_rep ( krb5_context /*context*/, krb5_kdc_rep */*rep*/); +/** + * Free a keyblock, also zero out the content of the keyblock, uses + * krb5_free_keyblock_contents() to free the content. + * + * @param context a Kerberos 5 context + * @param keyblock keyblock to free, NULL is valid argument + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_keyblock ( krb5_context /*context*/, krb5_keyblock */*keyblock*/); +/** + * Free a keyblock's content, also zero out the content of the keyblock. + * + * @param context a Kerberos 5 context + * @param keyblock keyblock content to free, NULL is valid argument + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_keyblock_contents ( krb5_context /*context*/, @@ -1943,6 +3784,28 @@ krb5_free_krbhst ( krb5_context /*context*/, char **/*hostlist*/); +/** + * Free a name canonicalization rule iterator. + */ + +KRB5_LIB_FUNCTION void KRB5_LIB_CALL +krb5_free_name_canon_iterator ( + krb5_context /*context*/, + krb5_name_canon_iterator /*iter*/); + +/** + * Frees a Kerberos principal allocated by the library with + * krb5_parse_name(), krb5_make_principal() or any other related + * principal functions. + * + * @param context A Kerberos context. + * @param p a principal to free. + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_principal ( krb5_context /*context*/, @@ -1953,17 +3816,54 @@ krb5_free_salt ( krb5_context /*context*/, krb5_salt /*salt*/); +/** + * Free ticket and content + * + * @param context a Kerberos 5 context + * @param ticket ticket to free + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_ticket ( krb5_context /*context*/, krb5_ticket */*ticket*/); +/** + * Deprecated: use krb5_xfree(). + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_unparsed_name ( krb5_context /*context*/, char */*str*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Forward credentials for client to host hostname , making them + * forwardable if forwardable, and returning the blob of data to sent + * in out_data. If hostname == NULL, pick it from server. + * + * @param context A kerberos 5 context. + * @param auth_context the auth context with the key to encrypt the out_data. + * @param hostname the host to forward the tickets too. + * @param client the client to delegate from. + * @param server the server to delegate the credential too. + * @param ccache credential cache to use. + * @param forwardable make the forwarded ticket forwabledable. + * @param out_data the resulting credential. + * + * @return Return an error code or 0. + * + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_fwd_tgt_creds ( krb5_context /*context*/, @@ -1975,6 +3875,46 @@ krb5_fwd_tgt_creds ( int /*forwardable*/, krb5_data */*out_data*/); +/** + * Fill buffer buf with len bytes of PRNG randomness that is ok to use + * for key generation, padding and public diclosing the randomness w/o + * disclosing the randomness source. + * + * This function can fail, and callers must check the return value. + * + * @param buf a buffer to fill with randomness + * @param len length of memory that buf points to. + * + * @return return 0 on success or HEIM_ERR_RANDOM_OFFLINE if the + * funcation failed to initialize the randomness source. + * + * @ingroup krb5_crypto + */ + +HEIMDAL_WARN_UNUSED_RESULT_ATTRIBUTE KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_generate_random ( + void */*buf*/, + size_t /*len*/); + +/** + * Fill buffer buf with len bytes of PRNG randomness that is ok to use + * for key generation, padding and public diclosing the randomness w/o + * disclosing the randomness source. + * + * This function can NOT fail, instead it will abort() and program will crash. + * + * If this function is called after a successful krb5_init_context(), + * the chance of it failing is low due to that krb5_init_context() + * pulls out some random, and quite commonly the randomness sources + * will not fail once it have started to produce good output, + * /dev/urandom behavies that way. + * + * @param buf a buffer to fill with randomness + * @param len length of memory that buf points to. + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_generate_random_block ( void */*buf*/, @@ -1992,6 +3932,12 @@ krb5_generate_seq_number ( const krb5_keyblock */*key*/, uint32_t */*seqno*/); +/** + * Deprecated: use krb5_generate_subkey_extended() + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_generate_subkey ( krb5_context /*context*/, @@ -1999,6 +3945,19 @@ krb5_generate_subkey ( krb5_keyblock **/*subkey*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Generate subkey, from keyblock + * + * @param context kerberos context + * @param key session key + * @param etype encryption type of subkey, if ETYPE_NULL, use key's enctype + * @param subkey returned new, free with krb5_free_keyblock(). + * + * @return 0 on success or a Kerberos 5 error code + * +* @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_generate_subkey_extended ( krb5_context /*context*/, @@ -2016,6 +3975,12 @@ krb5_get_all_server_addrs ( krb5_context /*context*/, krb5_addresses */*res*/); +/** + * Deprecated: use krb5_get_credentials_with_flags(). + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_cred_from_kdc ( krb5_context /*context*/, @@ -2025,6 +3990,12 @@ krb5_get_cred_from_kdc ( krb5_creds ***/*ret_tgts*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Deprecated: use krb5_get_credentials_with_flags(). + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_cred_from_kdc_opt ( krb5_context /*context*/, @@ -2100,9 +4071,35 @@ krb5_get_creds_opt_set_ticket ( krb5_get_creds_opt /*opt*/, const Ticket */*ticket*/); +/** + * Get the global configuration list. + * + * @param pfilenames return array of filenames, should be freed with krb5_free_config_files(). + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_default_config_files (char ***/*pfilenames*/); +/** + * Get the default encryption types that will be use in communcation + * with the KDC, clients and servers. + * + * @param context Kerberos 5 context. + * @param pdu_type request type (AS, TGS or none) + * @param etypes Encryption types, array terminated with + * ETYPE_NULL(0), caller should free array with krb5_xfree(): + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_default_in_tkt_etypes ( krb5_context /*context*/, @@ -2124,33 +4121,135 @@ krb5_get_default_realms ( krb5_context /*context*/, krb5_realm **/*realms*/); +/** + * Get if the library uses DNS to canonicalize hostnames. + * + * @param context Kerberos 5 context. + * + * @return return non zero if the library uses DNS to canonicalize hostnames. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_get_dns_canonicalize_hostname (krb5_context /*context*/); +/** + * Return the error string for the error code. The caller must not + * free the string. + * + * This function is deprecated since its not threadsafe. + * + * @param context Kerberos 5 context. + * @param code Kerberos error code. + * + * @return the error message matching code + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_get_err_text ( krb5_context /*context*/, krb5_error_code /*code*/) - KRB5_DEPRECATED_FUNCTION("Use X instead"); + KRB5_DEPRECATED_FUNCTION("Use krb5_get_error_message instead"); + +/** + * Return the error message for `code' in context. On memory + * allocation error the function returns NULL. + * + * @param context Kerberos 5 context + * @param code Error code related to the error + * + * @return an error string, needs to be freed with + * krb5_free_error_message(). The functions return NULL on error. + * + * @ingroup krb5_error + */ KRB5_LIB_FUNCTION const char * KRB5_LIB_CALL krb5_get_error_message ( krb5_context /*context*/, krb5_error_code /*code*/); +/** + * Return the error message in context. On error or no error string, + * the function returns NULL. + * + * @param context Kerberos 5 context + * + * @return an error string, needs to be freed with + * krb5_free_error_message(). The functions return NULL on error. + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION char * KRB5_LIB_CALL -krb5_get_error_string (krb5_context /*context*/); +krb5_get_error_string (krb5_context /*context*/) + KRB5_DEPRECATED_FUNCTION("Use krb5_get_error_message instead"); + +/** + * Get extra address to the address list that the library will add to + * the client's address list when communicating with the KDC. + * + * @param context Kerberos 5 context. + * @param addresses addreses to set + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_extra_addresses ( krb5_context /*context*/, krb5_addresses */*addresses*/); +/** + * Get version of fcache that the library should use. + * + * @param context Kerberos 5 context. + * @param version version number. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_fcache_version ( krb5_context /*context*/, int */*version*/); +/** + * Gets tickets forwarded to hostname. If the tickets that are + * forwarded are address-less, the forwarded tickets will also be + * address-less. + * + * If the ticket have any address, hostname will be used for figure + * out the address to forward the ticket too. This since this might + * use DNS, its insecure and also doesn't represent configured all + * addresses of the host. For example, the host might have two + * adresses, one IPv4 and one IPv6 address where the later is not + * published in DNS. This IPv6 address might be used communications + * and thus the resulting ticket useless. + * + * @param context A kerberos 5 context. + * @param auth_context the auth context with the key to encrypt the out_data. + * @param ccache credential cache to use + * @param flags the flags to control the resulting ticket flags + * @param hostname the host to forward the tickets too. + * @param in_creds the in client and server ticket names. The client + * and server components forwarded to the remote host. + * @param out_data the resulting credential. + * + * @return Return an error code or 0. + * + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_forwarded_creds ( krb5_context /*context*/, @@ -2167,6 +4266,19 @@ krb5_get_host_realm ( const char */*targethost*/, krb5_realm **/*realms*/); +/** + * Get extra addresses to ignore when fetching addresses from the + * underlaying operating system. + * + * @param context Kerberos 5 context. + * @param addresses list addreses ignored + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_ignore_addresses ( krb5_context /*context*/, @@ -2204,6 +4316,12 @@ krb5_get_in_tkt ( krb5_kdc_rep */*ret_as_reply*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Deprecated: use krb5_get_init_creds() and friends. + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_in_tkt_with_keytab ( krb5_context /*context*/, @@ -2217,6 +4335,12 @@ krb5_get_in_tkt_with_keytab ( krb5_kdc_rep */*ret_as_reply*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Deprecated: use krb5_get_init_creds() and friends. + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_in_tkt_with_password ( krb5_context /*context*/, @@ -2230,6 +4354,12 @@ krb5_get_in_tkt_with_password ( krb5_kdc_rep */*ret_as_reply*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Deprecated: use krb5_get_init_creds() and friends. + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_in_tkt_with_skey ( krb5_context /*context*/, @@ -2243,6 +4373,12 @@ krb5_get_in_tkt_with_skey ( krb5_kdc_rep */*ret_as_reply*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Get new credentials using keyblock. + * + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_keyblock ( krb5_context /*context*/, @@ -2253,6 +4389,12 @@ krb5_get_init_creds_keyblock ( const char */*in_tkt_service*/, krb5_get_init_creds_opt */*options*/); +/** + * Get new credentials using keytab. + * + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_keytab ( krb5_context /*context*/, @@ -2263,16 +4405,36 @@ krb5_get_init_creds_keytab ( const char */*in_tkt_service*/, krb5_get_init_creds_opt */*options*/); +/** + * Allocate a new krb5_get_init_creds_opt structure, free with + * krb5_get_init_creds_opt_free(). + * + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_opt_alloc ( krb5_context /*context*/, krb5_get_init_creds_opt **/*opt*/); +/** + * Free krb5_get_init_creds_opt structure. + * + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_get_init_creds_opt_free ( krb5_context /*context*/, krb5_get_init_creds_opt */*opt*/); +/** + * Deprecated: use the new krb5_init_creds_init() and + * krb5_init_creds_get_error(). + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_opt_get_error ( krb5_context /*context*/, @@ -2280,6 +4442,16 @@ krb5_get_init_creds_opt_get_error ( KRB_ERROR **/*error*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Deprecated: use krb5_get_init_creds_opt_alloc(). + * + * The reason krb5_get_init_creds_opt_init() is deprecated is that + * krb5_get_init_creds_opt is a static structure and for ABI reason it + * can't grow, ie can't add new functionality. + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_get_init_creds_opt_init (krb5_get_init_creds_opt */*opt*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); @@ -2307,6 +4479,11 @@ krb5_get_init_creds_opt_set_canonicalize ( krb5_boolean /*req*/); KRB5_LIB_FUNCTION void KRB5_LIB_CALL +krb5_get_init_creds_opt_set_change_password_prompt ( + krb5_get_init_creds_opt */*opt*/, + int /*change_password_prompt*/); + +KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_get_init_creds_opt_set_default_flags ( krb5_context /*context*/, const char */*appname*/, @@ -2396,6 +4573,12 @@ krb5_get_init_creds_opt_set_win2k ( krb5_get_init_creds_opt */*opt*/, krb5_boolean /*req*/); +/** + * Get new credentials using password. + * + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_password ( krb5_context /*context*/, @@ -2418,6 +4601,18 @@ krb5_get_kdc_cred ( krb5_creds */*in_creds*/, krb5_creds **out_creds ); +/** + * Get current offset in time to the KDC. + * + * @param context Kerberos 5 context. + * @param sec seconds part of offset. + * @param usec micro seconds part of offset. + * + * @return returns zero + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_kdc_sec_offset ( krb5_context /*context*/, @@ -2448,9 +4643,29 @@ krb5_get_krbhst ( const krb5_realm */*realm*/, char ***/*hostlist*/); +/** + * Get max time skew allowed. + * + * @param context Kerberos 5 context. + * + * @return timeskew in seconds. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION time_t KRB5_LIB_CALL krb5_get_max_time_skew (krb5_context /*context*/); +/** + * krb5_init_context() will get one random byte to make sure our + * random is alive. Assumption is that once the non blocking + * source allows us to pull bytes, its all seeded and allows us to + * pull more bytes. + * + * Most Kerberos users calls krb5_init_context(), so this is + * useful point where we can do the checking. + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_permitted_enctypes ( krb5_context /*context*/, @@ -2476,9 +4691,33 @@ krb5_get_server_rcache ( const krb5_data */*piece*/, krb5_rcache */*id*/); +/** + * Make the kerberos library default to the admin KDC. + * + * @param context Kerberos 5 context. + * + * @return boolean flag to telling the context will use admin KDC as the default KDC. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_get_use_admin_kdc (krb5_context /*context*/); +/** + * Validate the newly fetch credential, see also krb5_verify_init_creds(). + * + * @param context a Kerberos 5 context + * @param creds the credentials to verify + * @param client the client name to match up + * @param ccache the credential cache to use + * @param service a service name to use, used with + * krb5_sname_to_principal() to build a hostname to use to + * verify. + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_validated_creds ( krb5_context /*context*/, @@ -2487,6 +4726,14 @@ krb5_get_validated_creds ( krb5_ccache /*ccache*/, char */*service*/); +/** + * Get the default logging facility. + * + * @param context A Kerberos 5 context + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION krb5_log_facility * KRB5_LIB_CALL krb5_get_warn_dest (krb5_context /*context*/); @@ -2503,6 +4750,20 @@ krb5_getportbyname ( const char */*proto*/, int /*default_port*/); +/** + * krb5_h_addr2addr works like krb5_h_addr2sockaddr with the exception + * that it operates on a krb5_address instead of a struct sockaddr. + * + * @param context a Keberos context + * @param af address family + * @param haddr host address from struct hostent. + * @param addr returned krb5_address. + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_h_addr2addr ( krb5_context /*context*/, @@ -2510,6 +4771,25 @@ krb5_h_addr2addr ( const char */*haddr*/, krb5_address */*addr*/); +/** + * krb5_h_addr2sockaddr initializes a "struct sockaddr sa" from af and + * the "struct hostent" (see gethostbyname(3) ) h_addr_list + * component. The argument sa_size should initially contain the size + * of the sa, and after the call, it will contain the actual length of + * the address. + * + * @param context a Keberos context + * @param af addresses + * @param addr address + * @param sa returned struct sockaddr + * @param sa_size size of sa + * @param port port to set in sa. + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_h_addr2sockaddr ( krb5_context /*context*/, @@ -2519,11 +4799,23 @@ krb5_h_addr2sockaddr ( krb5_socklen_t */*sa_size*/, int /*port*/); +/** + * Convert the gethostname() error code (h_error) to a Kerberos et + * error code. + * + * @param eai_errno contains the error code from gethostname(). + * + * @return Kerberos error code representing the gethostname errors. + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_h_errno_to_heim_errno (int /*eai_errno*/); KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL -krb5_have_error_string (krb5_context /*context*/); +krb5_have_error_string (krb5_context /*context*/) + KRB5_DEPRECATED_FUNCTION("Use krb5_get_error_message instead"); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_hmac ( @@ -2535,31 +4827,102 @@ krb5_hmac ( krb5_keyblock */*key*/, Checksum */*result*/); +/** + * Initializes the context structure and reads the configuration file + * /etc/krb5.conf. The structure should be freed by calling + * krb5_free_context() when it is no longer being used. + * + * @param context pointer to returned context + * + * @return Returns 0 to indicate success. Otherwise an errno code is + * returned. Failure means either that something bad happened during + * initialization (typically ENOMEM) or that Kerberos should not be + * used ENXIO. If the function returns HEIM_ERR_RANDOM_OFFLINE, the + * random source is not available and later Kerberos calls might fail. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_context (krb5_context */*context*/); +/** + * Free the krb5_init_creds_context allocated by krb5_init_creds_init(). + * + * @param context A Kerberos 5 context. + * @param ctx The krb5_init_creds_context to free. + * + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_init_creds_free ( krb5_context /*context*/, krb5_init_creds_context /*ctx*/); +/** + * Get new credentials as setup by the krb5_init_creds_context. + * + * @param context A Kerberos 5 context. + * @param ctx The krb5_init_creds_context to process. + * + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_get ( krb5_context /*context*/, krb5_init_creds_context /*ctx*/); +/** + * Extract the newly acquired credentials from krb5_init_creds_context + * context. + * + * @param context A Kerberos 5 context. + * @param ctx + * @param cred credentials, free with krb5_free_cred_contents(). + * + * @return 0 for sucess or An Kerberos error code, see krb5_get_error_message(). + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_get_creds ( krb5_context /*context*/, krb5_init_creds_context /*ctx*/, krb5_creds */*cred*/); +/** + * Get the last error from the transaction. + * + * @return Returns 0 or an error code + * + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_get_error ( krb5_context /*context*/, krb5_init_creds_context /*ctx*/, KRB_ERROR */*error*/); +/** + * Start a new context to get a new initial credential. + * + * @param context A Kerberos 5 context. + * @param client The Kerberos principal to get the credential for, if + * NULL is given, the default principal is used as determined by + * krb5_get_default_principal(). + * @param prompter + * @param prompter_data + * @param start_time the time the ticket should start to be valid or 0 for now. + * @param options a options structure, can be NULL for default options. + * @param rctx A new allocated free with krb5_init_creds_free(). + * + * @return 0 for success or an Kerberos 5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_init ( krb5_context /*context*/, @@ -2571,29 +4934,98 @@ krb5_init_creds_init ( krb5_init_creds_context */*rctx*/); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_init_creds_set_fast_ap_armor_service ( + krb5_context /*context*/, + krb5_init_creds_context /*ctx*/, + krb5_const_principal /*armor_service*/); + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_init_creds_set_fast_ccache ( + krb5_context /*context*/, + krb5_init_creds_context /*ctx*/, + krb5_ccache /*fast_ccache*/); + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_set_keyblock ( krb5_context /*context*/, krb5_init_creds_context /*ctx*/, krb5_keyblock */*keyblock*/); +/** + * Set the keytab to use for authentication. + * + * @param context a Kerberos 5 context. + * @param ctx ctx krb5_init_creds_context context. + * @param keytab the keytab to read the key from. + * + * @return 0 for success, or an Kerberos 5 error code, see krb5_get_error_message(). + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_set_keytab ( krb5_context /*context*/, krb5_init_creds_context /*ctx*/, krb5_keytab /*keytab*/); +/** + * Sets the password that will use for the request. + * + * @param context a Kerberos 5 context. + * @param ctx ctx krb5_init_creds_context context. + * @param password the password to use. + * + * @return 0 for success, or an Kerberos 5 error code, see krb5_get_error_message(). + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_set_password ( krb5_context /*context*/, krb5_init_creds_context /*ctx*/, const char */*password*/); +/** + * Sets the service that the is requested. This call is only neede for + * special initial tickets, by default the a krbtgt is fetched in the default realm. + * + * @param context a Kerberos 5 context. + * @param ctx a krb5_init_creds_context context. + * @param service the service given as a string, for example + * "kadmind/admin". If NULL, the default krbtgt in the clients + * realm is set. + * + * @return 0 for success, or an Kerberos 5 error code, see krb5_get_error_message(). + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_set_service ( krb5_context /*context*/, krb5_init_creds_context /*ctx*/, const char */*service*/); +/** + * The core loop if krb5_get_init_creds() function family. Create the + * packets and have the caller send them off to the KDC. + * + * If the caller want all work been done for them, use + * krb5_init_creds_get() instead. + * + * @param context a Kerberos 5 context. + * @param ctx ctx krb5_init_creds_context context. + * @param in input data from KDC, first round it should be reset by krb5_data_zer(). + * @param out reply to KDC. + * @param hostinfo KDC address info, first round it can be NULL. + * @param flags status of the round, if + * KRB5_INIT_CREDS_STEP_FLAG_CONTINUE is set, continue one more round. + * + * @return 0 for success, or an Kerberos 5 error code, see + * krb5_get_error_message(). + * + * @ingroup krb5_credential + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_step ( krb5_context /*context*/, @@ -2603,20 +5035,115 @@ krb5_init_creds_step ( krb5_krbhst_info */*hostinfo*/, unsigned int */*flags*/); +/** + * + * @ingroup krb5_credential + */ + +krb5_error_code +krb5_init_creds_store ( + krb5_context /*context*/, + krb5_init_creds_context /*ctx*/, + krb5_ccache /*id*/); + +/** + * Init the built-in ets in the Kerberos library. + * + * @param context kerberos context to add the ets too + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_init_ets (krb5_context /*context*/); +/** + @struct krb5plugin_kuserok_ftable_desc * + * @brief Description of the krb5_kuserok(3) plugin facility. + * + * The krb5_kuserok(3) function is pluggable. The plugin is named + * KRB5_PLUGIN_KUSEROK ("krb5_plugin_kuserok"), with a single minor + * version, KRB5_PLUGIN_KUSEROK_VERSION_0 (0). + * + * The plugin for krb5_kuserok(3) consists of a data symbol referencing + * a structure of type krb5plugin_kuserok_ftable, with four fields: + * + * @param init Plugin initialization function (see krb5-plugin(7)) + * + * @param minor_version The plugin minor version number (0) + * + * @param fini Plugin finalization function + * + * @param kuserok Plugin kuserok function + * + * The kuserok field is the plugin entry point that performs the + * traditional kuserok operation however the plugin desires. It is + * invoked in no particular order relative to other kuserok plugins, but + * it has a 'rule' argument that indicates which plugin is intended to + * act on the rule. The plugin kuserok function must return + * KRB5_PLUGIN_NO_HANDLE if the rule is not applicable to it. + * + * The plugin kuserok function has the following arguments, in this + * order: + * + * -# plug_ctx, the context value output by the plugin's init function + * -# context, a krb5_context + * -# rule, the kuserok rule being evaluated (from krb5.conf(5)) + * -# flags + * -# k5login_dir, configured location of k5login per-user files if any + * -# luser, name of the local user account to which principal is attempting to access. + * -# principal, the krb5_principal trying to access the luser account + * -# result, a krb5_boolean pointer where the plugin will output its result + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_initlog ( krb5_context /*context*/, const char */*program*/, krb5_log_facility **/*fac*/); +/** + * Return TRUE (non zero) if the principal is a configuration + * principal (generated part of krb5_cc_set_config()). Returns FALSE + * (zero) if not a configuration principal. + * + * @param context a Keberos context + * @param principal principal to check if it a configuration principal + * + * @ingroup krb5_ccache + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_is_config_principal ( krb5_context /*context*/, krb5_const_principal /*principal*/); +/** + * Returns is the encryption is strong or weak + * + * @param context Kerberos 5 context + * @param enctype encryption type to probe + * + * @return Returns true if encryption type is weak or is not supported. + * + * @ingroup krb5_crypto + */ + +KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL +krb5_is_enctype_weak ( + krb5_context /*context*/, + krb5_enctype /*enctype*/); + +/** + * Runtime check if the Kerberos library was complied with thread support. + * + * @return TRUE if the library was compiled with thread support, FALSE if not. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_is_thread_safe (void); @@ -2633,12 +5160,40 @@ krb5_kcm_storage_request ( uint16_t /*opcode*/, krb5_storage **/*storage_p*/); +/** + * Returns the list of Kerberos encryption types sorted in order of + * most preferred to least preferred encryption type. Note that some + * encryption types might be disabled, so you need to check with + * krb5_enctype_valid() before using the encryption type. + * + * @return list of enctypes, terminated with ETYPE_NULL. Its a static + * array completed into the Kerberos library so the content doesn't + * need to be freed. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION const krb5_enctype * KRB5_LIB_CALL krb5_kerberos_enctypes (krb5_context /*context*/); +/** + * Get encryption type of a keyblock. + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_enctype KRB5_LIB_CALL krb5_keyblock_get_enctype (const krb5_keyblock */*block*/); +/** + * Fill in `key' with key data of type `enctype' from `data' of length + * `size'. Key should be freed using krb5_free_keyblock_contents(). + * + * @return 0 on success or a Kerberos 5 error code + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_keyblock_init ( krb5_context /*context*/, @@ -2655,9 +5210,23 @@ krb5_keyblock_key_proc ( krb5_const_pointer /*keyseed*/, krb5_keyblock **/*key*/); +/** + * Zero out a keyblock + * + * @param keyblock keyblock to zero out + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_keyblock_zero (krb5_keyblock */*keyblock*/); +/** + * Deprecated: use krb5_get_init_creds() and friends. + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_CALLCONV krb5_keytab_key_proc ( krb5_context /*context*/, @@ -2667,6 +5236,12 @@ krb5_keytab_key_proc ( krb5_keyblock **/*key*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Deprecated: keytypes doesn't exists, they are really enctypes. + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_keytype_to_enctypes ( krb5_context /*context*/, @@ -2675,6 +5250,12 @@ krb5_keytype_to_enctypes ( krb5_enctype **/*val*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Deprecated: keytypes doesn't exists, they are really enctypes. + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_keytype_to_enctypes_default ( krb5_context /*context*/, @@ -2683,6 +5264,13 @@ krb5_keytype_to_enctypes_default ( krb5_enctype **/*val*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Deprecated: keytypes doesn't exists, they are really enctypes in + * most cases, use krb5_enctype_to_string(). + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_keytype_to_string ( krb5_context /*context*/, @@ -2702,6 +5290,16 @@ krb5_krbhst_free ( krb5_context /*context*/, krb5_krbhst_handle /*handle*/); +/** + * Return an `struct addrinfo *' for a KDC host. + * + * Returns an the struct addrinfo in in that corresponds to the + * information in `host'. free:ing is handled by krb5_krbhst_free, so + * the returned ai must not be released. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_krbhst_get_addrinfo ( krb5_context /*context*/, @@ -2742,16 +5340,62 @@ krb5_krbhst_reset ( krb5_krbhst_handle /*handle*/); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_krbhst_set_hostname ( + krb5_context /*context*/, + krb5_krbhst_handle /*handle*/, + const char */*hostname*/); + +/** + * Add the entry in `entry' to the keytab `id'. + * + * @param context a Keberos context. + * @param id a keytab. + * @param entry the entry to add + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_add_entry ( krb5_context /*context*/, krb5_keytab /*id*/, krb5_keytab_entry */*entry*/); +/** + * Finish using the keytab in `id'. All resources will be released, + * even on errors. + * + * @param context a Keberos context. + * @param id keytab to close. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_close ( krb5_context /*context*/, krb5_keytab /*id*/); +/** + * Compare `entry' against `principal, vno, enctype'. + * Any of `principal, vno, enctype' might be 0 which acts as a wildcard. + * Return TRUE if they compare the same, FALSE otherwise. + * + * @param context a Keberos context. + * @param entry an entry to match with. + * @param principal principal to match, NULL matches all principals. + * @param vno key version to match, 0 matches all key version numbers. + * @param enctype encryption type to match, 0 matches all encryption types. + * + * @return Return TRUE or match, FALSE if not matched. + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_kt_compare ( krb5_context /*context*/, @@ -2760,45 +5404,143 @@ krb5_kt_compare ( krb5_kvno /*vno*/, krb5_enctype /*enctype*/); +/** + * Copy the contents of `in' into `out'. + * + * @param context a Keberos context. + * @param in the keytab entry to copy. + * @param out the copy of the keytab entry, free with krb5_kt_free_entry(). + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_copy_entry_contents ( krb5_context /*context*/, const krb5_keytab_entry */*in*/, krb5_keytab_entry */*out*/); +/** + * Set `id' to the default keytab. + * + * @param context a Keberos context. + * @param id the new default keytab. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_default ( krb5_context /*context*/, krb5_keytab */*id*/); +/** + * Copy the name of the default modify keytab into `name'. + * + * @param context a Keberos context. + * @param name buffer where the name will be written + * @param namesize length of name + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_default_modify_name ( krb5_context /*context*/, char */*name*/, size_t /*namesize*/); +/** + * copy the name of the default keytab into `name'. + * + * @param context a Keberos context. + * @param name buffer where the name will be written + * @param namesize length of name + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_default_name ( krb5_context /*context*/, char */*name*/, size_t /*namesize*/); +/** + * Destroy (remove) the keytab in `id'. All resources will be released, + * even on errors, does the equvalment of krb5_kt_close() on the resources. + * + * @param context a Keberos context. + * @param id keytab to destroy. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_destroy ( krb5_context /*context*/, krb5_keytab /*id*/); +/** + * Release all resources associated with `cursor'. + * + * @param context a Keberos context. + * @param id a keytab. + * @param cursor the cursor to free. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_end_seq_get ( krb5_context /*context*/, krb5_keytab /*id*/, krb5_kt_cursor */*cursor*/); +/** + * Free the contents of `entry'. + * + * @param context a Keberos context. + * @param entry the entry to free + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_free_entry ( krb5_context /*context*/, krb5_keytab_entry */*entry*/); +/** + * Retrieve the keytab entry for `principal, kvno, enctype' into `entry' + * from the keytab `id'. Matching is done like krb5_kt_compare(). + * + * @param context a Keberos context. + * @param id a keytab. + * @param principal principal to match, NULL matches all principals. + * @param kvno key version to match, 0 matches all key version numbers. + * @param enctype encryption type to match, 0 matches all encryption types. + * @param entry the returned entry, free with krb5_kt_free_entry(). + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_get_entry ( krb5_context /*context*/, @@ -2808,12 +5550,39 @@ krb5_kt_get_entry ( krb5_enctype /*enctype*/, krb5_keytab_entry */*entry*/); +/** + * Retrieve the full name of the keytab `keytab' and store the name in + * `str'. + * + * @param context a Keberos context. + * @param keytab keytab to get name for. + * @param str the name of the keytab name, usee krb5_xfree() to free + * the string. On error, *str is set to NULL. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_get_full_name ( krb5_context /*context*/, krb5_keytab /*keytab*/, char **/*str*/); +/** + * Retrieve the name of the keytab `keytab' into `name', `namesize' + * + * @param context a Keberos context. + * @param keytab the keytab to get the name for. + * @param name name buffer. + * @param namesize size of name buffer. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_get_name ( krb5_context /*context*/, @@ -2821,6 +5590,20 @@ krb5_kt_get_name ( char */*name*/, size_t /*namesize*/); +/** + * Return the type of the `keytab' in the string `prefix of length + * `prefixsize'. + * + * @param context a Keberos context. + * @param keytab the keytab to get the prefix for + * @param prefix prefix buffer + * @param prefixsize length of prefix buffer + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_get_type ( krb5_context /*context*/, @@ -2828,11 +5611,36 @@ krb5_kt_get_type ( char */*prefix*/, size_t /*prefixsize*/); -KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL +/** + * Return true if the keytab exists and have entries + * + * @param context a Keberos context. + * @param id a keytab. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_have_content ( krb5_context /*context*/, krb5_keytab /*id*/); +/** + * Get the next entry from keytab, advance the cursor. On last entry + * the function will return KRB5_KT_END. + * + * @param context a Keberos context. + * @param id a keytab. + * @param entry the returned entry, free with krb5_kt_free_entry(). + * @param cursor the cursor of the iteration. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_next_entry ( krb5_context /*context*/, @@ -2840,6 +5648,22 @@ krb5_kt_next_entry ( krb5_keytab_entry */*entry*/, krb5_kt_cursor */*cursor*/); +/** + * Read the key identified by `(principal, vno, enctype)' from the + * keytab in `keyprocarg' (the default if == NULL) into `*key'. + * + * @param context a Keberos context. + * @param keyprocarg + * @param principal + * @param vno + * @param enctype + * @param key + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_read_service_key ( krb5_context /*context*/, @@ -2849,29 +5673,113 @@ krb5_kt_read_service_key ( krb5_enctype /*enctype*/, krb5_keyblock **/*key*/); +/** + * Register a new keytab backend. + * + * @param context a Keberos context. + * @param ops a backend to register. + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_register ( krb5_context /*context*/, const krb5_kt_ops */*ops*/); +/** + * Remove an entry from the keytab, matching is done using + * krb5_kt_compare(). + + * @param context a Keberos context. + * @param id a keytab. + * @param entry the entry to remove + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_remove_entry ( krb5_context /*context*/, krb5_keytab /*id*/, krb5_keytab_entry */*entry*/); +/** + * Resolve the keytab name (of the form `type:residual') in `name' + * into a keytab in `id'. + * + * @param context a Keberos context. + * @param name name to resolve + * @param id resulting keytab, free with krb5_kt_close(). + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_resolve ( krb5_context /*context*/, const char */*name*/, krb5_keytab */*id*/); +/** + * Set `cursor' to point at the beginning of `id'. + * + * @param context a Keberos context. + * @param id a keytab. + * @param cursor a newly allocated cursor, free with krb5_kt_end_seq_get(). + * + * @return Return an error code or 0, see krb5_get_error_message(). + * + * @ingroup krb5_keytab + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_start_seq_get ( krb5_context /*context*/, krb5_keytab /*id*/, krb5_kt_cursor */*cursor*/); +/** + * This function takes the name of a local user and checks if + * principal is allowed to log in as that user. + * + * The user may have a ~/.k5login file listing principals that are + * allowed to login as that user. If that file does not exist, all + * principals with a only one component that is identical to the + * username, and a realm considered local, are allowed access. + * + * The .k5login file must contain one principal per line, be owned by + * user and not be writable by group or other (but must be readable by + * anyone). + * + * Note that if the file exists, no implicit access rights are given + * to user@@LOCALREALM. + * + * Optionally, a set of files may be put in ~/.k5login.d (a + * directory), in which case they will all be checked in the same + * manner as .k5login. The files may be called anything, but files + * starting with a hash (#) , or ending with a tilde (~) are + * ignored. Subdirectories are not traversed. Note that this directory + * may not be checked by other Kerberos implementations. + * + * If no configuration file exists, match user against local domains, + * ie luser@@LOCAL-REALMS-IN-CONFIGURATION-FILES. + * + * @param context Kerberos 5 context. + * @param principal principal to check if allowed to login + * @param luser local user id + * + * @return returns TRUE if access should be granted, FALSE otherwise. + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_kuserok ( krb5_context /*context*/, @@ -2885,7 +5793,7 @@ krb5_log ( int /*level*/, const char */*fmt*/, ...) - __attribute__((format (printf, 4, 5))); + __attribute__ ((__format__ (__printf__, 4, 5))); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_log_msg ( @@ -2895,7 +5803,20 @@ krb5_log_msg ( char **/*reply*/, const char */*fmt*/, ...) - __attribute__((format (printf, 5, 6))); + __attribute__ ((__format__ (__printf__, 5, 6))); + +/** + * Create an address of type KRB5_ADDRESS_ADDRPORT from (addr, port) + * + * @param context a Keberos context + * @param res built address from addr/port + * @param addr address to use + * @param port port to use + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_make_addrport ( @@ -2904,6 +5825,19 @@ krb5_make_addrport ( const krb5_address */*addr*/, int16_t /*port*/); +/** + * Build a principal using vararg style building + * + * @param context A Kerberos context. + * @param principal returned principal + * @param realm realm name + * @param ... a list of components ended with NULL. + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_make_principal ( krb5_context /*context*/, @@ -2911,6 +5845,15 @@ krb5_make_principal ( krb5_const_realm /*realm*/, ...); +/** + * krb5_max_sockaddr_size returns the max size of the .Li struct + * sockaddr that the Kerberos library will return. + * + * @return Return an size_t of the maximum struct sockaddr. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION size_t KRB5_LIB_CALL krb5_max_sockaddr_size (void); @@ -2927,6 +5870,19 @@ krb5_mk_error ( krb5_data */*reply*/); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_mk_error_ext ( + krb5_context /*context*/, + krb5_error_code /*error_code*/, + const char */*e_text*/, + const krb5_data */*e_data*/, + const krb5_principal /*server*/, + const PrincipalName */*client_name*/, + const Realm */*client_realm*/, + time_t */*client_time*/, + int */*client_usec*/, + krb5_data */*reply*/); + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_mk_priv ( krb5_context /*context*/, krb5_auth_context /*auth_context*/, @@ -2978,6 +5934,49 @@ krb5_mk_safe ( krb5_data */*outbuf*/, krb5_replay_data */*outdata*/); +/** + * Iteratively apply name canon rules, outputing a principal and rule + * options each time. Iteration completes when the @iter is NULL on + * return or when an error is returned. Callers must free the iterator + * if they abandon it mid-way. + * + * @param context Kerberos context + * @param iter name canon rule iterator (input/output) + * @param try_princ output principal name + * @param rule_opts output rule options + */ + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_name_canon_iterate ( + krb5_context /*context*/, + krb5_name_canon_iterator */*iter*/, + krb5_const_principal */*try_princ*/, + krb5_name_canon_rule_options */*rule_opts*/); + +/** + * Initialize name canonicalization iterator. + * + * @param context Kerberos context + * @param in_princ principal name to be canonicalized OR + * @param iter output iterator object + */ + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_name_canon_iterator_start ( + krb5_context /*context*/, + krb5_const_principal /*in_princ*/, + krb5_name_canon_iterator */*iter*/); + +/** + * Read \a len bytes from socket \a p_fd into buffer \a buf. + * Block until \a len bytes are read or until an error. + * + * @return If successful, the number of bytes read: \a len. + * On end-of-file, 0. + * On error, less than 0 (if single-threaded, the error can be found + * in the errno global variable). + */ + KRB5_LIB_FUNCTION krb5_ssize_t KRB5_LIB_CALL krb5_net_read ( krb5_context /*context*/, @@ -3011,10 +6010,10 @@ krb5_ntlm_free ( krb5_ntlm /*ntlm*/); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL -krb5_ntlm_init_get_challange ( +krb5_ntlm_init_get_challenge ( krb5_context /*context*/, krb5_ntlm /*ntlm*/, - krb5_data */*challange*/); + krb5_data */*challenge*/); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ntlm_init_get_flags ( @@ -3131,6 +6130,20 @@ krb5_pac_free ( krb5_context /*context*/, krb5_pac /*pac*/); +/** + * Get the PAC buffer of specific type from the pac. + * + * @param context Kerberos 5 context. + * @param p the pac structure returned by krb5_pac_parse(). + * @param type type of buffer to get + * @param data return data, free with krb5_data_free(). + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5_pac + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_pac_get_buffer ( krb5_context /*context*/, @@ -3157,6 +6170,22 @@ krb5_pac_parse ( size_t /*len*/, krb5_pac */*pac*/); +/** + * Verify the PAC. + * + * @param context Kerberos 5 context. + * @param pac the pac structure returned by krb5_pac_parse(). + * @param authtime The time of the ticket the PAC belongs to. + * @param principal the principal to verify. + * @param server The service key, most always be given. + * @param privsvr The KDC key, may be given. + + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5_pac + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_pac_verify ( krb5_context /*context*/, @@ -3174,18 +6203,56 @@ krb5_padata_add ( void */*buf*/, size_t /*len*/); +/** + * krb5_parse_address returns the resolved hostname in string to the + * krb5_addresses addresses . + * + * @param context a Keberos context + * @param string + * @param addresses + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_address ( krb5_context /*context*/, const char */*string*/, krb5_addresses */*addresses*/); +/** + * Parse a name into a krb5_principal structure + * + * @param context Kerberos 5 context + * @param name name to parse into a Kerberos principal + * @param principal returned principal, free with krb5_free_principal(). + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_name ( krb5_context /*context*/, const char */*name*/, krb5_principal */*principal*/); +/** + * Parse a name into a krb5_principal structure, flags controls the behavior. + * + * @param context Kerberos 5 context + * @param name name to parse into a Kerberos principal + * @param flags flags to control the behavior + * @param principal returned principal, free with krb5_free_principal(). + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_name_flags ( krb5_context /*context*/, @@ -3193,6 +6260,12 @@ krb5_parse_name_flags ( int /*flags*/, krb5_principal */*principal*/); +/** + * Parse nametype string and return a nametype integer + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_nametype ( krb5_context /*context*/, @@ -3204,6 +6277,12 @@ krb5_passwd_result_to_string ( krb5_context /*context*/, int /*result*/); +/** + * Deprecated: use krb5_get_init_creds() and friends. + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_CALLCONV krb5_password_key_proc ( krb5_context /*context*/, @@ -3221,6 +6300,18 @@ krb5_pk_enterprise_cert ( krb5_principal */*principal*/, struct hx509_certs_data **/*res*/); +/** + * Register a plugin symbol name of specific type. + * @param context a Keberos context + * @param type type of plugin symbol + * @param name name of plugin symbol + * @param symbol a pointer to the named symbol + * @return In case of error a non zero error com_err error is returned + * and the Kerberos error string is set. + * + * @ingroup krb5_support + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_plugin_register ( krb5_context /*context*/, @@ -3234,18 +6325,50 @@ krb5_prepend_config_files ( char **/*pq*/, char ***/*ret_pp*/); +/** + * Prepend the filename to the global configuration list. + * + * @param filelist a filename to add to the default list of filename + * @param pfilenames return array of filenames, should be freed with krb5_free_config_files(). + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_prepend_config_files_default ( const char */*filelist*/, char ***/*pfilenames*/); +/** + * Prepend the context full error string for a specific error code. + * The error that is stored should be internationalized. + * + * The if context is NULL, no error string is stored. + * + * @param context Kerberos 5 context + * @param ret The error code + * @param fmt Error string for the error code + * @param ... printf(3) style parameters. + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_prepend_error_message ( krb5_context /*context*/, krb5_error_code /*ret*/, const char */*fmt*/, ...) - __attribute__ ((format (printf, 3, 4))); + __attribute__ ((__format__ (__printf__, 3, 4))); + +/** + * Deprecated: use krb5_principal_get_realm() + * + * @ingroup krb5_deprecated + */ KRB5_LIB_FUNCTION krb5_realm * KRB5_LIB_CALL krb5_princ_realm ( @@ -3253,6 +6376,12 @@ krb5_princ_realm ( krb5_principal /*principal*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Deprecated: use krb5_principal_set_realm() + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_princ_set_realm ( krb5_context /*context*/, @@ -3260,12 +6389,39 @@ krb5_princ_set_realm ( krb5_realm */*realm*/) KRB5_DEPRECATED_FUNCTION("Use X instead"); +/** + * Compares the two principals, including realm of the principals and returns + * TRUE if they are the same and FALSE if not. + * + * @param context Kerberos 5 context + * @param princ1 first principal to compare + * @param princ2 second principal to compare + * + * @ingroup krb5_principal + * @see krb5_principal_compare_any_realm() + * @see krb5_realm_compare() + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_compare ( krb5_context /*context*/, krb5_const_principal /*princ1*/, krb5_const_principal /*princ2*/); +/** + * Return TRUE iff princ1 == princ2 (without considering the realm) + * + * @param context Kerberos 5 context + * @param princ1 first principal to compare + * @param princ2 second principal to compare + * + * @return non zero if equal, 0 if not + * + * @ingroup krb5_principal + * @see krb5_principal_compare() + * @see krb5_realm_compare() + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_compare_any_realm ( krb5_context /*context*/, @@ -3278,26 +6434,126 @@ krb5_principal_get_comp_string ( krb5_const_principal /*principal*/, unsigned int /*component*/); +/** + * Get number of component is principal. + * + * @param context Kerberos 5 context + * @param principal principal to query + * + * @return number of components in string + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION unsigned int KRB5_LIB_CALL krb5_principal_get_num_comp ( krb5_context /*context*/, krb5_const_principal /*principal*/); +/** + * Get the realm of the principal + * + * @param context A Kerberos context. + * @param principal principal to get the realm for + * + * @return realm of the principal, don't free or use after krb5_principal is freed + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_principal_get_realm ( krb5_context /*context*/, krb5_const_principal /*principal*/); +/** + * Get the type of the principal + * + * @param context A Kerberos context. + * @param principal principal to get the type for + * + * @return the type of principal + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_principal_get_type ( krb5_context /*context*/, krb5_const_principal /*principal*/); +/** + * Returns true iff name is an WELLKNOWN:ORG.H5L.HOSTBASED-SERVICE + * + * @ingroup krb5_principal + */ + +krb5_boolean KRB5_LIB_FUNCTION +krb5_principal_is_gss_hostbased_service ( + krb5_context /*context*/, + krb5_const_principal /*principal*/); + +/** + * Check if the cname part of the principal is a krbtgt principal + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_is_krbtgt ( krb5_context /*context*/, krb5_const_principal /*p*/); +/** + * Returns true if name is Kerberos an LKDC realm + * + * @ingroup krb5_principal + */ + +krb5_boolean KRB5_LIB_FUNCTION +krb5_principal_is_lkdc ( + krb5_context /*context*/, + krb5_const_principal /*principal*/); + +/** + * Returns true if name is Kerberos NULL name + * + * @ingroup krb5_principal + */ + +krb5_boolean KRB5_LIB_FUNCTION +krb5_principal_is_null ( + krb5_context /*context*/, + krb5_const_principal /*principal*/); + +/** + * Returns true if name is Kerberos an LKDC realm + * + * @ingroup krb5_principal + */ + +krb5_boolean KRB5_LIB_FUNCTION +krb5_principal_is_pku2u ( + krb5_context /*context*/, + krb5_const_principal /*principal*/); + +/** + * Check if the cname part of the principal is a initial or renewed krbtgt principal + * + * @ingroup krb5_principal + */ + +krb5_boolean KRB5_LIB_FUNCTION +krb5_principal_is_root_krbtgt ( + krb5_context /*context*/, + krb5_const_principal /*p*/); + +/** + * return TRUE iff princ matches pattern + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_match ( krb5_context /*context*/, @@ -3305,17 +6561,65 @@ krb5_principal_match ( krb5_const_principal /*pattern*/); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_principal_set_comp_string ( + krb5_context /*context*/, + krb5_principal /*principal*/, + unsigned int /*k*/, + const char */*component*/); + +/** + * Set a new realm for a principal, and as a side-effect free the + * previous realm. + * + * @param context A Kerberos context. + * @param principal principal set the realm for + * @param realm the new realm to set + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_principal_set_realm ( krb5_context /*context*/, krb5_principal /*principal*/, krb5_const_realm /*realm*/); +/** + * Set the type of the principal + * + * @param context A Kerberos context. + * @param principal principal to set the type for + * @param type the new type + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_principal_set_type ( krb5_context /*context*/, krb5_principal /*principal*/, int /*type*/); +/** + * krb5_print_address prints the address in addr to the string string + * that have the length len. If ret_len is not NULL, it will be filled + * with the length of the string if size were unlimited (not including + * the final NUL) . + * + * @param addr address to be printed + * @param str pointer string to print the address into + * @param len length that will fit into area pointed to by "str". + * @param ret_len return length the str. + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_print_address ( const krb5_address */*addr*/, @@ -3323,6 +6627,12 @@ krb5_print_address ( size_t /*len*/, size_t */*ret_len*/); +krb5_error_code +krb5_process_last_request ( + krb5_context /*context*/, + krb5_get_init_creds_opt */*options*/, + krb5_init_creds_context /*ctx*/); + KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_program_setup ( krb5_context */*context*/, @@ -3341,6 +6651,23 @@ krb5_prompter_posix ( int /*num_prompts*/, krb5_prompt prompts[]); +/** + * Converts the random bytestring to a protocol key according to + * Kerberos crypto frame work. It may be assumed that all the bits of + * the input string are equally random, even though the entropy + * present in the random source may be limited. + * + * @param context Kerberos 5 context + * @param type the enctype resulting key will be of + * @param data input random data to convert to a key + * @param size size of input random data, at least krb5_enctype_keysize() long + * @param key key, output key, free with krb5_free_keyblock_contents() + * + * @return Return an error code or 0. + * + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_random_to_key ( krb5_context /*context*/, @@ -3462,6 +6789,23 @@ krb5_rd_rep ( const krb5_data */*inbuf*/, krb5_ap_rep_enc_part **/*repl*/); +/** + * Process an AP_REQ message. + * + * @param context Kerberos 5 context. + * @param auth_context authentication context of the peer. + * @param inbuf the AP_REQ message, obtained for example with krb5_read_message(). + * @param server server principal. + * @param keytab server keytab. + * @param ap_req_options set to the AP_REQ options. See the AP_OPTS_* defines. + * @param ticket on success, set to the authenticated client credentials. + * Must be deallocated with krb5_free_ticket(). If not + * interested, pass a NULL value. + * + * @return 0 to indicate success. Otherwise a Kerberos error code is + * returned, see krb5_get_error_message(). + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_rd_req ( krb5_context /*context*/, @@ -3472,6 +6816,30 @@ krb5_rd_req ( krb5_flags */*ap_req_options*/, krb5_ticket **/*ticket*/); +/** + * The core server function that verify application authentication + * requests from clients. + * + * @param context Keberos 5 context. + * @param auth_context the authentication context, can be NULL, then + * default values for the authentication context will used. + * @param inbuf the (AP-REQ) authentication buffer + * + * @param server the server to authenticate to. If NULL the function + * will try to find any available credential in the keytab + * that will verify the reply. The function will prefer the + * server specified in the AP-REQ, but if + * there is no mach, it will try all keytab entries for a + * match. This has serious performance issues for large keytabs. + * + * @param inctx control the behavior of the function, if NULL, the + * default behavior is used. + * @param outctx the return outctx, free with krb5_rd_req_out_ctx_free(). + * @return Kerberos 5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_auth + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_rd_req_ctx ( krb5_context /*context*/, @@ -3481,6 +6849,19 @@ krb5_rd_req_ctx ( krb5_rd_req_in_ctx /*inctx*/, krb5_rd_req_out_ctx */*outctx*/); +/** + * Allocate a krb5_rd_req_in_ctx as an input parameter to + * krb5_rd_req_ctx(). The caller should free the context with + * krb5_rd_req_in_ctx_free() when done with the context. + * + * @param context Keberos 5 context. + * @param ctx in ctx to krb5_rd_req_ctx(). + * + * @return Kerberos 5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_auth + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_rd_req_in_ctx_alloc ( krb5_context /*context*/, @@ -3497,18 +6878,53 @@ krb5_rd_req_in_set_keyblock ( krb5_rd_req_in_ctx /*in*/, krb5_keyblock */*keyblock*/); +/** + * Set the keytab that krb5_rd_req_ctx() will use. + * + * @param context Keberos 5 context. + * @param in in ctx to krb5_rd_req_ctx(). + * @param keytab keytab that krb5_rd_req_ctx() will use, only copy the + * pointer, so the caller must free they keytab after + * krb5_rd_req_in_ctx_free() is called. + * + * @return Kerberos 5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_auth + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_rd_req_in_set_keytab ( krb5_context /*context*/, krb5_rd_req_in_ctx /*in*/, krb5_keytab /*keytab*/); +/** + * Set if krb5_rq_red() is going to check the Windows PAC or not + * + * @param context Keberos 5 context. + * @param in krb5_rd_req_in_ctx to check the option on. + * @param flag flag to select if to check the pac (TRUE) or not (FALSE). + * + * @return Kerberos 5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_auth + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_rd_req_in_set_pac_check ( krb5_context /*context*/, krb5_rd_req_in_ctx /*in*/, krb5_boolean /*flag*/); +/** + * Free the krb5_rd_req_out_ctx. + * + * @param context Keberos 5 context. + * @param ctx krb5_rd_req_out_ctx context to free. + * + * @ingroup krb5_auth + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_rd_req_out_ctx_free ( krb5_context /*context*/, @@ -3526,6 +6942,18 @@ krb5_rd_req_out_get_keyblock ( krb5_rd_req_out_ctx /*out*/, krb5_keyblock **/*keyblock*/); +/** + * Get the principal that was used in the request from the + * client. Might not match whats in the ticket if krb5_rd_req_ctx() + * searched in the keytab for a matching key. + * + * @param context a Kerberos 5 context. + * @param out a krb5_rd_req_out_ctx from krb5_rd_req_ctx(). + * @param principal return principal, free with krb5_free_principal(). + * + * @ingroup krb5_auth + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_rd_req_out_get_server ( krb5_context /*context*/, @@ -3576,12 +7004,52 @@ krb5_read_safe_message ( krb5_pointer /*p_fd*/, krb5_data */*data*/); +/** + * return TRUE iff realm(princ1) == realm(princ2) + * + * @param context Kerberos 5 context + * @param princ1 first principal to compare + * @param princ2 second principal to compare + * + * @ingroup krb5_principal + * @see krb5_principal_compare_any_realm() + * @see krb5_principal_compare() + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_realm_compare ( krb5_context /*context*/, krb5_const_principal /*princ1*/, krb5_const_principal /*princ2*/); +/** + * Returns true if name is Kerberos an LKDC realm + * + * @ingroup krb5_principal + */ + +krb5_boolean KRB5_LIB_FUNCTION +krb5_realm_is_lkdc (const char */*realm*/); + +/** + * Perform the server side of the sendauth protocol. + * + * @param context Kerberos 5 context. + * @param auth_context authentication context of the peer. + * @param p_fd socket associated to the connection. + * @param appl_version server-specific string. + * @param server server principal. + * @param flags if KRB5_RECVAUTH_IGNORE_VERSION is set, skip the sendauth version + * part of the protocol. + * @param keytab server keytab. + * @param ticket on success, set to the authenticated client credentials. + * Must be deallocated with krb5_free_ticket(). If not + * interested, pass a NULL value. + * + * @return 0 to indicate success. Otherwise a Kerberos error code is + * returned, see krb5_get_error_message(). + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_recvauth ( krb5_context /*context*/, @@ -3593,6 +7061,12 @@ krb5_recvauth ( krb5_keytab /*keytab*/, krb5_ticket **/*ticket*/); +/** + * Perform the server side of the sendauth protocol like krb5_recvauth(), but support + * a user-specified callback, \a match_appl_version, to perform the match of the application + * version \a match_data. + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_recvauth_match_version ( krb5_context /*context*/, @@ -3605,61 +7079,212 @@ krb5_recvauth_match_version ( krb5_keytab /*keytab*/, krb5_ticket **/*ticket*/); +/** + * Read a address block from the storage. + * + * @param sp the storage buffer to write to + * @param adr the address block read from storage + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_address ( krb5_storage */*sp*/, krb5_address */*adr*/); +/** + * Read a addresses block from the storage. + * + * @param sp the storage buffer to write to + * @param adr the addresses block read from storage + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_addrs ( krb5_storage */*sp*/, krb5_addresses */*adr*/); +/** + * Read a auth data from the storage. + * + * @param sp the storage buffer to write to + * @param auth the auth data block read from storage + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_authdata ( krb5_storage */*sp*/, krb5_authdata */*auth*/); +/** + * Read a credentials block from the storage. + * + * @param sp the storage buffer to write to + * @param creds the credentials block read from storage + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_creds ( krb5_storage */*sp*/, krb5_creds */*creds*/); +/** + * Read a tagged credentials block from the storage. + * + * @param sp the storage buffer to write to + * @param creds the credentials block read from storage + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_creds_tag ( krb5_storage */*sp*/, krb5_creds */*creds*/); +/** + * Parse a data from the storage. + * + * @param sp the storage buffer to read from + * @param data the parsed data + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_data ( krb5_storage */*sp*/, krb5_data */*data*/); +/** + * Read a int16 from storage, byte order is controlled by the settings + * on the storage, see krb5_storage_set_byteorder(). + * + * @param sp the storage to write too + * @param value the value read from the buffer + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_int16 ( krb5_storage */*sp*/, int16_t */*value*/); +/** + * Read a int32 from storage, byte order is controlled by the settings + * on the storage, see krb5_storage_set_byteorder(). + * + * @param sp the storage to write too + * @param value the value read from the buffer + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_int32 ( krb5_storage */*sp*/, int32_t */*value*/); +/** + * Read a int64 from storage, byte order is controlled by the settings + * on the storage, see krb5_storage_set_byteorder(). + * + * @param sp the storage to write too + * @param value the value read from the buffer + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_ret_int64 ( + krb5_storage */*sp*/, + int64_t */*value*/); + +/** + * Read a int8 from storage + * + * @param sp the storage to write too + * @param value the value read from the buffer + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_int8 ( krb5_storage */*sp*/, int8_t */*value*/); +/** + * Read a keyblock from the storage. + * + * @param sp the storage buffer to write to + * @param p the keyblock read from storage, free using krb5_free_keyblock() + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_keyblock ( krb5_storage */*sp*/, krb5_keyblock */*p*/); +/** + * Parse principal from the storage. + * + * @param sp the storage buffer to read from + * @param princ the parsed principal + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_principal ( krb5_storage */*sp*/, krb5_principal */*princ*/); +/** + * Parse a string from the storage. + * + * @param sp the storage buffer to read from + * @param string the parsed string + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_string ( krb5_storage */*sp*/, @@ -3670,26 +7295,100 @@ krb5_ret_stringnl ( krb5_storage */*sp*/, char **/*string*/); +/** + * Parse zero terminated string from the storage. + * + * @param sp the storage buffer to read from + * @param string the parsed string + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_stringz ( krb5_storage */*sp*/, char **/*string*/); +/** + * Read a times block from the storage. + * + * @param sp the storage buffer to write to + * @param times the times block read from storage + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_times ( krb5_storage */*sp*/, krb5_times */*times*/); +/** + * Read a int16 from storage, byte order is controlled by the settings + * on the storage, see krb5_storage_set_byteorder(). + * + * @param sp the storage to write too + * @param value the value read from the buffer + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_uint16 ( krb5_storage */*sp*/, uint16_t */*value*/); +/** + * Read a uint32 from storage, byte order is controlled by the settings + * on the storage, see krb5_storage_set_byteorder(). + * + * @param sp the storage to write too + * @param value the value read from the buffer + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_uint32 ( krb5_storage */*sp*/, uint32_t */*value*/); +/** + * Read a uint64 from storage, byte order is controlled by the settings + * on the storage, see krb5_storage_set_byteorder(). + * + * @param sp the storage to write too + * @param value the value read from the buffer + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_ret_uint64 ( + krb5_storage */*sp*/, + uint64_t */*value*/); + +/** + * Read a uint8 from storage + * + * @param sp the storage to write too + * @param value the value read from the buffer + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_uint8 ( krb5_storage */*sp*/, @@ -3702,6 +7401,30 @@ krb5_salttype_to_string ( krb5_salttype /*stype*/, char **/*string*/); +/** + * Perform the client side of the sendauth protocol. + * + * @param context Kerberos 5 context. + * @param auth_context Authentication context of the peer. + * @param p_fd Socket associated to the connection. + * @param appl_version Server-specific string. + * @param client Client principal. If NULL, use the credentials in \a ccache. + * @param server Server principal. + * @param ap_req_options Options for the AP_REQ message. See the AP_OPTS_* defines in krb5.h. + * @param in_data FIXME + * @param in_creds FIXME + * @param ccache Credentials cache. If NULL, use the default credentials cache. + * @param ret_error If not NULL, will be set to the error reported by server, if any. + * Must be deallocated with krb5_free_error_contents(). + * @param rep_result If not NULL, will be set to the EncApRepPart of the AP_REP message. + * Must be deallocated with krb5_free_ap_rep_enc_part(). + * @param out_creds FIXME If not NULL, will be set to FIXME. Must be deallocated with + * krb5_free_creds(). + * + * @return 0 to indicate success. Otherwise a Kerberos error code is + * returned, see krb5_get_error_message(). + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_sendauth ( krb5_context /*context*/, @@ -3730,7 +7453,7 @@ krb5_sendto_context ( krb5_context /*context*/, krb5_sendto_ctx /*ctx*/, const krb5_data */*send_data*/, - const krb5_realm /*realm*/, + krb5_const_realm /*realm*/, krb5_data */*receive*/); KRB5_LIB_FUNCTION void KRB5_LIB_CALL @@ -3738,6 +7461,23 @@ krb5_sendto_ctx_add_flags ( krb5_sendto_ctx /*ctx*/, int /*flags*/); +/** + * @section send_to_kdc Locating and sending packets to the KDC + * + * The send to kdc code is responsible to request the list of KDC from + * the locate-kdc subsystem and then send requests to each of them. + * + * - Each second a new hostname is tried. + * - If the hostname have several addresses, the first will be tried + * directly then in turn the other will be tried every 3 seconds + * (host_timeout). + * - UDP requests are tried 3 times, and it tried with a individual timeout of kdc_timeout / 3. + * - TCP and HTTP requests are tried 1 time. + * + * Total wait time shorter then (number of addresses * 3) + kdc_timeout seconds. + * + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_sendto_ctx_alloc ( krb5_context /*context*/, @@ -3778,11 +7518,50 @@ krb5_sendto_kdc_flags ( int /*flags*/); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_sendto_set_hostname ( + krb5_context /*context*/, + krb5_sendto_ctx /*ctx*/, + const char */*hostname*/); + +/** + * Reinit the context from a new set of filenames. + * + * @param context context to add configuration too. + * @param filenames array of filenames, end of list is indicated with a NULL filename. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_config_files ( krb5_context /*context*/, char **/*filenames*/); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_set_debug_dest ( + krb5_context /*context*/, + const char */*program*/, + const char */*log_spec*/); + +/** + * Set the default encryption types that will be use in communcation + * with the KDC, clients and servers. + * + * @param context Kerberos 5 context. + * @param etypes Encryption types, array terminated with ETYPE_NULL (0). + * A value of NULL resets the encryption types to the defaults set in the + * configuration file. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_default_in_tkt_etypes ( krb5_context /*context*/, const krb5_enctype */*etypes*/); @@ -3792,57 +7571,186 @@ krb5_set_default_realm ( krb5_context /*context*/, const char */*realm*/); +/** + * Set if the library should use DNS to canonicalize hostnames. + * + * @param context Kerberos 5 context. + * @param flag if its dns canonicalizion is used or not. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_set_dns_canonicalize_hostname ( krb5_context /*context*/, krb5_boolean /*flag*/); +/** + * Set the context full error string for a specific error code. + * The error that is stored should be internationalized. + * + * The if context is NULL, no error string is stored. + * + * @param context Kerberos 5 context + * @param ret The error code + * @param fmt Error string for the error code + * @param ... printf(3) style parameters. + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_set_error_message ( krb5_context /*context*/, krb5_error_code /*ret*/, const char */*fmt*/, ...) - __attribute__ ((format (printf, 3, 4))); + __attribute__ ((__format__ (__printf__, 3, 4))); + +/** + * Set the error message returned by krb5_get_error_string(). + * + * Deprecated: use krb5_get_error_message() + * + * @param context Kerberos context + * @param fmt error message to free + * + * @return Return an error code or 0. + * + * @ingroup krb5_deprecated + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_error_string ( krb5_context /*context*/, const char */*fmt*/, ...) - __attribute__((format (printf, 2, 3))) KRB5_DEPRECATED_FUNCTION("Use X instead"); + __attribute__ ((__format__ (__printf__, 2, 3))) KRB5_DEPRECATED_FUNCTION("Use X instead"); + +/** + * Set extra address to the address list that the library will add to + * the client's address list when communicating with the KDC. + * + * @param context Kerberos 5 context. + * @param addresses addreses to set + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_extra_addresses ( krb5_context /*context*/, const krb5_addresses */*addresses*/); +/** + * Set version of fcache that the library should use. + * + * @param context Kerberos 5 context. + * @param version version number. + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_fcache_version ( krb5_context /*context*/, int /*version*/); +/** + * Enable and disable home directory access on either the global state + * or the krb5_context state. By calling krb5_set_home_dir_access() + * with context set to NULL, the global state is configured otherwise + * the state for the krb5_context is modified. + * + * For home directory access to be allowed, both the global state and + * the krb5_context state have to be allowed. + * + * @param context a Kerberos 5 context or NULL + * @param allow allow if TRUE home directory + * @return the old value + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_set_home_dir_access ( krb5_context /*context*/, krb5_boolean /*allow*/); +/** + * Set extra addresses to ignore when fetching addresses from the + * underlaying operating system. + * + * @param context Kerberos 5 context. + * @param addresses addreses to ignore + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_ignore_addresses ( krb5_context /*context*/, const krb5_addresses */*addresses*/); +/** + * Set current offset in time to the KDC. + * + * @param context Kerberos 5 context. + * @param sec seconds part of offset. + * @param usec micro seconds part of offset. + * + * @return returns zero + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_kdc_sec_offset ( krb5_context /*context*/, int32_t /*sec*/, int32_t /*usec*/); +/** + * Set max time skew allowed. + * + * @param context Kerberos 5 context. + * @param t timeskew in seconds. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_set_max_time_skew ( krb5_context /*context*/, time_t /*t*/); +/** + * Change password using creds. + * + * @param context a Keberos context + * @param creds The initial kadmin/passwd for the principal or an admin principal + * @param newpw The new password to set + * @param targprinc if unset, the default principal is used. + * @param result_code Result code, KRB5_KPASSWD_SUCCESS is when password is changed. + * @param result_code_string binary message from the server, contains + * at least the result_code. + * @param result_string A message from the kpasswd service or the + * library in human printable form. The string is NUL terminated. + * + * @return On sucess and *result_code is KRB5_KPASSWD_SUCCESS, the password is changed. + + * @ingroup @krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_password ( krb5_context /*context*/, @@ -3863,6 +7771,20 @@ krb5_set_password_using_ccache ( krb5_data */*result_code_string*/, krb5_data */*result_string*/); +/** + * Set the absolute time that the caller knows the kdc has so the + * kerberos library can calculate the relative diffrence beteen the + * KDC time and local system time. + * + * @param context Keberos 5 context. + * @param sec The applications new of "now" in seconds + * @param usec The applications new of "now" in micro seconds + + * @return Kerberos 5 error code, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_real_time ( krb5_context /*context*/, @@ -3875,16 +7797,57 @@ krb5_set_send_to_kdc_func ( krb5_send_to_kdc_func /*func*/, void */*data*/); +/** + * Make the kerberos library default to the admin KDC. + * + * @param context Kerberos 5 context. + * @param flag boolean flag to select if the use the admin KDC or not. + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_set_use_admin_kdc ( krb5_context /*context*/, krb5_boolean /*flag*/); +/** + * Set the default logging facility. + * + * @param context A Kerberos 5 context + * @param fac Facility to use for logging. + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_warn_dest ( krb5_context /*context*/, krb5_log_facility */*fac*/); +/** + * Create a principal for the given service running on the given + * hostname. If KRB5_NT_SRV_HST is used, the hostname is canonicalized + * according the configured name canonicalization rules, with + * canonicalization delayed in some cases. One rule involves DNS, which + * is insecure unless DNSSEC is used, but we don't use DNSSEC-capable + * resolver APIs here, so that if DNSSEC is used we wouldn't know it. + * + * Canonicalization is immediate (not delayed) only when there is only + * one canonicalization rule and that rule indicates that we should do a + * host lookup by name (i.e., DNS). + * + * @param context A Kerberos context. + * @param hostname hostname to use + * @param sname Service name to use + * @param type name type of principal, use KRB5_NT_SRV_HST or KRB5_NT_UNKNOWN. + * @param ret_princ return principal, free with krb5_free_principal(). + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_sname_to_principal ( krb5_context /*context*/, @@ -3901,12 +7864,39 @@ krb5_sock_to_principal ( int32_t /*type*/, krb5_principal */*ret_princ*/); +/** + * krb5_sockaddr2address stores a address a "struct sockaddr" sa in + * the krb5_address addr. + * + * @param context a Keberos context + * @param sa a struct sockaddr to extract the address from + * @param addr an Kerberos 5 address to store the address in. + * + * @return Return an error code or 0. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_sockaddr2address ( krb5_context /*context*/, const struct sockaddr */*sa*/, krb5_address */*addr*/); +/** + * krb5_sockaddr2port extracts a port (if possible) from a "struct + * sockaddr. + * + * @param context a Keberos context + * @param sa a struct sockaddr to extract the port from + * @param port a pointer to an int16_t store the port in. + * + * @return Return an error code or 0. Will return + * KRB5_PROG_ATYPE_NOSUPP in case address type is not supported. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_sockaddr2port ( krb5_context /*context*/, @@ -3916,6 +7906,18 @@ krb5_sockaddr2port ( KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_sockaddr_is_loopback (const struct sockaddr */*sa*/); +/** + * krb5_sockaddr_uninteresting returns TRUE for all .Fa sa that the + * kerberos library thinks are uninteresting. One example are link + * local addresses. + * + * @param sa pointer to struct sockaddr that might be interesting. + * + * @return Return a non zero for uninteresting addresses. + * + * @ingroup krb5_address + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_sockaddr_uninteresting (const struct sockaddr */*sa*/); @@ -3925,147 +7927,546 @@ krb5_std_usage ( struct getargs */*args*/, int /*num_args*/); +/** + * Clear the flags on a storage buffer + * + * @param sp the storage buffer to clear the flags on + * @param flags the flags to clear + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_storage_clear_flags ( krb5_storage */*sp*/, krb5_flags /*flags*/); +/** + * Create a elastic (allocating) memory storage backend. Memory is + * allocated on demand. Free returned krb5_storage with + * krb5_storage_free(). + * + * @return A krb5_storage on success, or NULL on out of memory error. + * + * @ingroup krb5_storage + * + * @sa krb5_storage_from_mem() + * @sa krb5_storage_from_readonly_mem() + * @sa krb5_storage_from_fd() + * @sa krb5_storage_from_data() + * @sa krb5_storage_from_socket() + */ + KRB5_LIB_FUNCTION krb5_storage * KRB5_LIB_CALL krb5_storage_emem (void); +/** + * Free a krb5 storage. + * + * @param sp the storage to free. + * + * @return An Kerberos 5 error code. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_storage_free (krb5_storage */*sp*/); +/** + * Create a fixed size memory storage block + * + * @return A krb5_storage on success, or NULL on out of memory error. + * + * @ingroup krb5_storage + * + * @sa krb5_storage_mem() + * @sa krb5_storage_from_mem() + * @sa krb5_storage_from_readonly_mem() + * @sa krb5_storage_from_fd() + */ + KRB5_LIB_FUNCTION krb5_storage * KRB5_LIB_CALL krb5_storage_from_data (krb5_data */*data*/); +/** + * + * + * @return A krb5_storage on success, or NULL on out of memory error. + * + * @ingroup krb5_storage + * + * @sa krb5_storage_emem() + * @sa krb5_storage_from_mem() + * @sa krb5_storage_from_readonly_mem() + * @sa krb5_storage_from_data() + * @sa krb5_storage_from_socket() + */ + KRB5_LIB_FUNCTION krb5_storage * KRB5_LIB_CALL -krb5_storage_from_fd (krb5_socket_t /*fd_in*/); +krb5_storage_from_fd (int /*fd_in*/); + +/** + * Create a fixed size memory storage block + * + * @return A krb5_storage on success, or NULL on out of memory error. + * + * @ingroup krb5_storage + * + * @sa krb5_storage_mem() + * @sa krb5_storage_from_readonly_mem() + * @sa krb5_storage_from_data() + * @sa krb5_storage_from_fd() + * @sa krb5_storage_from_socket() + */ KRB5_LIB_FUNCTION krb5_storage * KRB5_LIB_CALL krb5_storage_from_mem ( void */*buf*/, size_t /*len*/); +/** + * Create a fixed size memory storage block that is read only + * + * @return A krb5_storage on success, or NULL on out of memory error. + * + * @ingroup krb5_storage + * + * @sa krb5_storage_mem() + * @sa krb5_storage_from_mem() + * @sa krb5_storage_from_data() + * @sa krb5_storage_from_fd() + */ + KRB5_LIB_FUNCTION krb5_storage * KRB5_LIB_CALL krb5_storage_from_readonly_mem ( const void */*buf*/, size_t /*len*/); +/** + * + * + * @return A krb5_storage on success, or NULL on out of memory error. + * + * @ingroup krb5_storage + * + * @sa krb5_storage_emem() + * @sa krb5_storage_from_mem() + * @sa krb5_storage_from_readonly_mem() + * @sa krb5_storage_from_data() + * @sa krb5_storage_from_fd() + */ + +KRB5_LIB_FUNCTION krb5_storage * KRB5_LIB_CALL +krb5_storage_from_socket (krb5_socket_t /*sock_in*/); + +/** + * Sync the storage buffer to its backing store. If there is no + * backing store this function will return success. + * + * @param sp the storage buffer to sync + * + * @return A Kerberos 5 error code + * + * @ingroup krb5_storage + */ + +KRB5_LIB_FUNCTION int KRB5_LIB_CALL +krb5_storage_fsync (krb5_storage */*sp*/); + +/** + * Return the current byteorder for the buffer. See krb5_storage_set_byteorder() for the list or byte order contants. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_flags KRB5_LIB_CALL krb5_storage_get_byteorder (krb5_storage */*sp*/); +/** + * Get the return code that will be used when end of storage is reached. + * + * @param sp the storage + * + * @return storage error code + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_storage_get_eof_code (krb5_storage */*sp*/); +/** + * Return true or false depending on if the storage flags is set or + * not. NB testing for the flag 0 always return true. + * + * @param sp the storage buffer to check flags on + * @param flags The flags to test for + * + * @return true if all the flags are set, false if not. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_storage_is_flags ( krb5_storage */*sp*/, krb5_flags /*flags*/); +/** + * Read to the storage buffer. + * + * @param sp the storage buffer to read from + * @param buf the buffer to store the data in + * @param len the length to read + * + * @return The length of data read (can be shorter then len), or negative on error. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_ssize_t KRB5_LIB_CALL krb5_storage_read ( krb5_storage */*sp*/, void */*buf*/, size_t /*len*/); +/** + * Seek to a new offset. + * + * @param sp the storage buffer to seek in. + * @param offset the offset to seek + * @param whence relateive searching, SEEK_CUR from the current + * position, SEEK_END from the end, SEEK_SET absolute from the start. + * + * @return The new current offset + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION off_t KRB5_LIB_CALL krb5_storage_seek ( krb5_storage */*sp*/, off_t /*offset*/, int /*whence*/); +/** + * Set the new byte order of the storage buffer. + * + * @param sp the storage buffer to set the byte order for. + * @param byteorder the new byte order. + * + * The byte order are: KRB5_STORAGE_BYTEORDER_BE, + * KRB5_STORAGE_BYTEORDER_LE and KRB5_STORAGE_BYTEORDER_HOST. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_storage_set_byteorder ( krb5_storage */*sp*/, krb5_flags /*byteorder*/); +/** + * Set the return code that will be used when end of storage is reached. + * + * @param sp the storage + * @param code the error code to return on end of storage + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_storage_set_eof_code ( krb5_storage */*sp*/, int /*code*/); +/** + * Add the flags on a storage buffer by or-ing in the flags to the buffer. + * + * @param sp the storage buffer to set the flags on + * @param flags the flags to set + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_storage_set_flags ( krb5_storage */*sp*/, krb5_flags /*flags*/); +/** + * Set the max alloc value + * + * @param sp the storage buffer set the max allow for + * @param size maximum size to allocate, use 0 to remove limit + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_storage_set_max_alloc ( krb5_storage */*sp*/, size_t /*size*/); +/** + * Copy the contnent of storage + * + * @param sp the storage to copy to a data + * @param data the copied data, free with krb5_data_free() + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_storage_to_data ( krb5_storage */*sp*/, krb5_data */*data*/); +/** + * Truncate the storage buffer in sp to offset. + * + * @param sp the storage buffer to truncate. + * @param offset the offset to truncate too. + * + * @return An Kerberos 5 error code. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_storage_truncate ( krb5_storage */*sp*/, off_t /*offset*/); +/** + * Write to the storage buffer. + * + * @param sp the storage buffer to write to + * @param buf the buffer to write to the storage buffer + * @param len the length to write + * + * @return The length of data written (can be shorter then len), or negative on error. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_ssize_t KRB5_LIB_CALL krb5_storage_write ( krb5_storage */*sp*/, const void */*buf*/, size_t /*len*/); +/** + * Write a address block to storage. + * + * @param sp the storage buffer to write to + * @param p the address block to write. + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_address ( krb5_storage */*sp*/, krb5_address /*p*/); +/** + * Write a addresses block to storage. + * + * @param sp the storage buffer to write to + * @param p the addresses block to write. + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_addrs ( krb5_storage */*sp*/, krb5_addresses /*p*/); +/** + * Write a auth data block to storage. + * + * @param sp the storage buffer to write to + * @param auth the auth data block to write. + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_authdata ( krb5_storage */*sp*/, krb5_authdata /*auth*/); +/** + * Write a credentials block to storage. + * + * @param sp the storage buffer to write to + * @param creds the creds block to write. + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_creds ( krb5_storage */*sp*/, krb5_creds */*creds*/); +/** + * Write a tagged credentials block to storage. + * + * @param sp the storage buffer to write to + * @param creds the creds block to write. + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_creds_tag ( krb5_storage */*sp*/, krb5_creds */*creds*/); +/** + * Store a data to the storage. The data is stored with an int32 as + * lenght plus the data (not padded). + * + * @param sp the storage buffer to write to + * @param data the buffer to store. + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_data ( krb5_storage */*sp*/, krb5_data /*data*/); +/** + * Store a int16 to storage, byte order is controlled by the settings + * on the storage, see krb5_storage_set_byteorder(). + * + * @param sp the storage to write too + * @param value the value to store + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_int16 ( krb5_storage */*sp*/, int16_t /*value*/); +/** + * Store a int32 to storage, byte order is controlled by the settings + * on the storage, see krb5_storage_set_byteorder(). + * + * @param sp the storage to write too + * @param value the value to store + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_int32 ( krb5_storage */*sp*/, int32_t /*value*/); +/** + * Store a int64 to storage, byte order is controlled by the settings + * on the storage, see krb5_storage_set_byteorder(). + * + * @param sp the storage to write too + * @param value the value to store + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_store_int64 ( + krb5_storage */*sp*/, + int64_t /*value*/); + +/** + * Store a int8 to storage. + * + * @param sp the storage to write too + * @param value the value to store + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_int8 ( krb5_storage */*sp*/, int8_t /*value*/); +/** + * Store a keyblock to the storage. + * + * @param sp the storage buffer to write to + * @param p the keyblock to write + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_keyblock ( krb5_storage */*sp*/, krb5_keyblock /*p*/); +/** + * Write a principal block to storage. + * + * @param sp the storage buffer to write to + * @param p the principal block to write. + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_principal ( krb5_storage */*sp*/, krb5_const_principal /*p*/); +/** + * Store a string to the buffer. The data is formated as an len:uint32 + * plus the string itself (not padded). + * + * @param sp the storage buffer to write to + * @param s the string to store. + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_string ( krb5_storage */*sp*/, @@ -4076,26 +8477,101 @@ krb5_store_stringnl ( krb5_storage */*sp*/, const char */*s*/); +/** + * Store a zero terminated string to the buffer. The data is stored + * one character at a time until a NUL is stored. + * + * @param sp the storage buffer to write to + * @param s the string to store. + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_stringz ( krb5_storage */*sp*/, const char */*s*/); +/** + * Write a times block to storage. + * + * @param sp the storage buffer to write to + * @param times the times block to write. + * + * @return 0 on success, a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_times ( krb5_storage */*sp*/, krb5_times /*times*/); +/** + * Store a uint16 to storage, byte order is controlled by the settings + * on the storage, see krb5_storage_set_byteorder(). + * + * @param sp the storage to write too + * @param value the value to store + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_uint16 ( krb5_storage */*sp*/, uint16_t /*value*/); +/** + * Store a uint32 to storage, byte order is controlled by the settings + * on the storage, see krb5_storage_set_byteorder(). + * + * @param sp the storage to write too + * @param value the value to store + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_uint32 ( krb5_storage */*sp*/, uint32_t /*value*/); +/** + * Store a uint64 to storage, byte order is controlled by the settings + * on the storage, see krb5_storage_set_byteorder(). + * + * @param sp the storage to write too + * @param value the value to store + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + +KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL +krb5_store_uint64 ( + krb5_storage */*sp*/, + uint64_t /*value*/); + +/** + * Store a uint8 to storage. + * + * @param sp the storage to write too + * @param value the value to store + * + * @return 0 for success, or a Kerberos 5 error code on failure. + * + * @ingroup krb5_storage + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_uint8 ( krb5_storage */*sp*/, @@ -4170,6 +8646,13 @@ krb5_string_to_key_salt_opaque ( krb5_data /*opaque*/, krb5_keyblock */*key*/); +/** + * Deprecated: keytypes doesn't exists, they are really enctypes in + * most cases, use krb5_string_to_enctype(). + * + * @ingroup krb5_deprecated + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_string_to_keytype ( krb5_context /*context*/, @@ -4184,6 +8667,19 @@ krb5_string_to_salttype ( const char */*string*/, krb5_salttype */*salttype*/); +/** + * Extract the authorization data type of type from the ticket. Store + * the field in data. This function is to use for kerberos + * applications. + * + * @param context a Kerberos 5 context + * @param ticket Kerberos ticket + * @param type type to fetch + * @param data returned data, free with krb5_data_free() + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ticket_get_authorization_data_type ( krb5_context /*context*/, @@ -4191,39 +8687,117 @@ krb5_ticket_get_authorization_data_type ( int /*type*/, krb5_data */*data*/); +/** + * Return client principal in ticket + * + * @param context a Kerberos 5 context + * @param ticket ticket to copy + * @param client client principal, free with krb5_free_principal() + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ticket_get_client ( krb5_context /*context*/, const krb5_ticket */*ticket*/, krb5_principal */*client*/); +/** + * Return end time of ticket + * + * @param context a Kerberos 5 context + * @param ticket ticket to copy + * + * @return end time of ticket + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION time_t KRB5_LIB_CALL krb5_ticket_get_endtime ( krb5_context /*context*/, const krb5_ticket */*ticket*/); +/** + * Get the flags from the Kerberos ticket + * + * @param context Kerberos context + * @param ticket Kerberos ticket + * + * @return ticket flags + * + * @ingroup krb5_ticket + */ + KRB5_LIB_FUNCTION unsigned long KRB5_LIB_CALL krb5_ticket_get_flags ( krb5_context /*context*/, const krb5_ticket */*ticket*/); +/** + * Return server principal in ticket + * + * @param context a Kerberos 5 context + * @param ticket ticket to copy + * @param server server principal, free with krb5_free_principal() + * + * @return Returns 0 to indicate success. Otherwise an kerberos et + * error code is returned, see krb5_get_error_message(). + * + * @ingroup krb5 + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ticket_get_server ( krb5_context /*context*/, const krb5_ticket */*ticket*/, krb5_principal */*server*/); +/** + * If the caller passes in a negative usec, its assumed to be + * unknown and the function will use the current time usec. + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_timeofday ( krb5_context /*context*/, krb5_timestamp */*timeret*/); +/** + * Unparse the Kerberos name into a string + * + * @param context Kerberos 5 context + * @param principal principal to query + * @param name resulting string, free with krb5_xfree() + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name ( krb5_context /*context*/, krb5_const_principal /*principal*/, char **/*name*/); +/** + * Unparse the principal name to a fixed buffer + * + * @param context A Kerberos context. + * @param principal principal to unparse + * @param name buffer to write name to + * @param len length of buffer + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed ( krb5_context /*context*/, @@ -4231,6 +8805,20 @@ krb5_unparse_name_fixed ( char */*name*/, size_t /*len*/); +/** + * Unparse the principal name with unparse flags to a fixed buffer. + * + * @param context A Kerberos context. + * @param principal principal to unparse + * @param flags unparse flags + * @param name buffer to write name to + * @param len length of buffer + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed_flags ( krb5_context /*context*/, @@ -4239,6 +8827,20 @@ krb5_unparse_name_fixed_flags ( char */*name*/, size_t /*len*/); +/** + * Unparse the principal name to a fixed buffer. The realm is skipped + * if its a default realm. + * + * @param context A Kerberos context. + * @param principal principal to unparse + * @param name buffer to write name to + * @param len length of buffer + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed_short ( krb5_context /*context*/, @@ -4246,6 +8848,19 @@ krb5_unparse_name_fixed_short ( char */*name*/, size_t /*len*/); +/** + * Unparse the Kerberos name into a string + * + * @param context Kerberos 5 context + * @param principal principal to query + * @param flags flag to determine the behavior + * @param name resulting string, free with krb5_xfree() + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_flags ( krb5_context /*context*/, @@ -4253,6 +8868,19 @@ krb5_unparse_name_flags ( int /*flags*/, char **/*name*/); +/** + * Unparse the principal name to a allocated buffer. The realm is + * skipped if its a default realm. + * + * @param context A Kerberos context. + * @param principal principal to unparse + * @param name returned buffer, free with krb5_xfree() + * + * @return An krb5 error code, see krb5_get_error_message(). + * + * @ingroup krb5_principal + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_short ( krb5_context /*context*/, @@ -4265,20 +8893,32 @@ krb5_us_timeofday ( krb5_timestamp */*sec*/, int32_t */*usec*/); +/** + * Log a warning to the log, default stderr, include bthe error from + * the last failure and then abort. + * + * @param context A Kerberos 5 context + * @param code error code of the last error + * @param fmt message to print + * @param ap arguments + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_vabort ( krb5_context /*context*/, krb5_error_code /*code*/, const char */*fmt*/, va_list /*ap*/) - __attribute__ ((noreturn, format (printf, 3, 0))); + __attribute__ ((__noreturn__, __format__ (__printf__, 3, 0))); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_vabortx ( krb5_context /*context*/, const char */*fmt*/, va_list /*ap*/) - __attribute__ ((noreturn, format (printf, 2, 0))); + __attribute__ ((__noreturn__, __format__ (__printf__, 2, 0))); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_verify_ap_req ( @@ -4319,6 +8959,20 @@ krb5_verify_checksum ( size_t /*len*/, Checksum */*cksum*/); +/** + * Verify a Kerberos message checksum. + * + * @param context Kerberos context + * @param crypto Kerberos crypto context + * @param usage Key usage for this buffer + * @param data array of buffers to process + * @param num_data length of array + * @param type return checksum type if not NULL + * + * @return Return an error code or 0. + * @ingroup krb5_crypto + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_verify_checksum_iov ( krb5_context /*context*/, @@ -4406,6 +9060,19 @@ krb5_verify_user_opt ( const char */*password*/, krb5_verify_opt */*opt*/); +/** + * Log a warning to the log, default stderr, include bthe error from + * the last failure and then exit. + * + * @param context A Kerberos 5 context + * @param eval the exit code to exit with + * @param code error code of the last error + * @param fmt message to print + * @param ap arguments + * + * @ingroup krb5_error + */ + KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_verr ( krb5_context /*context*/, @@ -4413,7 +9080,18 @@ krb5_verr ( krb5_error_code /*code*/, const char */*fmt*/, va_list /*ap*/) - __attribute__ ((noreturn, format (printf, 4, 0))); + __attribute__ ((__noreturn__, __format__ (__printf__, 4, 0))); + +/** + * Log a warning to the log, default stderr, and then exit. + * + * @param context A Kerberos 5 context + * @param eval the exit code to exit with + * @param fmt message to print + * @param ap arguments + * + * @ingroup krb5_error + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_verrx ( @@ -4421,7 +9099,7 @@ krb5_verrx ( int /*eval*/, const char */*fmt*/, va_list /*ap*/) - __attribute__ ((noreturn, format (printf, 3, 0))); + __attribute__ ((__noreturn__, __format__ (__printf__, 3, 0))); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_vlog ( @@ -4430,7 +9108,7 @@ krb5_vlog ( int /*level*/, const char */*fmt*/, va_list /*ap*/) - __attribute__((format (printf, 4, 0))); + __attribute__ ((__format__ (__printf__, 4, 0))); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_vlog_msg ( @@ -4440,7 +9118,20 @@ krb5_vlog_msg ( int /*level*/, const char */*fmt*/, va_list /*ap*/) - __attribute__((format (printf, 5, 0))); + __attribute__ ((__format__ (__printf__, 5, 0))); + +/** + * Prepend the contexts's full error string for a specific error code. + * + * The if context is NULL, no error string is stored. + * + * @param context Kerberos 5 context + * @param ret The error code + * @param fmt Error string for the error code + * @param args printf(3) style parameters. + * + * @ingroup krb5_error + */ KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_vprepend_error_message ( @@ -4448,7 +9139,20 @@ krb5_vprepend_error_message ( krb5_error_code /*ret*/, const char */*fmt*/, va_list /*args*/) - __attribute__ ((format (printf, 3, 0))); + __attribute__ ((__format__ (__printf__, 3, 0))); + +/** + * Set the context full error string for a specific error code. + * + * The if context is NULL, no error string is stored. + * + * @param context Kerberos 5 context + * @param ret The error code + * @param fmt Error string for the error code + * @param args printf(3) style parameters. + * + * @ingroup krb5_error + */ KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_vset_error_message ( @@ -4456,14 +9160,41 @@ krb5_vset_error_message ( krb5_error_code /*ret*/, const char */*fmt*/, va_list /*args*/) - __attribute__ ((format (printf, 3, 0))); + __attribute__ ((__format__ (__printf__, 3, 0))); + +/** + * Set the error message returned by krb5_get_error_string(), + * deprecated, use krb5_set_error_message(). + * + * Deprecated: use krb5_vset_error_message() + * + * @param context Kerberos context + * @param fmt error message to free + * @param args variable argument list vector + * + * @return Return an error code or 0. + * + * @ingroup krb5_deprecated + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_vset_error_string ( krb5_context /*context*/, const char */*fmt*/, va_list /*args*/) - __attribute__ ((format (printf, 2, 0))) KRB5_DEPRECATED_FUNCTION("Use X instead"); + __attribute__ ((__format__ (__printf__, 2, 0))) KRB5_DEPRECATED_FUNCTION("Use X instead"); + +/** + * Log a warning to the log, default stderr, include the error from + * the last failure. + * + * @param context A Kerberos 5 context. + * @param code error code of the last error + * @param fmt message to print + * @param ap arguments + * + * @ingroup krb5_error + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_vwarn ( @@ -4471,14 +9202,35 @@ krb5_vwarn ( krb5_error_code /*code*/, const char */*fmt*/, va_list /*ap*/) - __attribute__ ((format (printf, 3, 0))); + __attribute__ ((__format__ (__printf__, 3, 0))); + +/** + * Log a warning to the log, default stderr. + * + * @param context A Kerberos 5 context. + * @param fmt message to print + * @param ap arguments + * + * @ingroup krb5_error + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_vwarnx ( krb5_context /*context*/, const char */*fmt*/, va_list /*ap*/) - __attribute__ ((format (printf, 2, 0))); + __attribute__ ((__format__ (__printf__, 2, 0))); + +/** + * Log a warning to the log, default stderr, include the error from + * the last failure. + * + * @param context A Kerberos 5 context. + * @param code error code of the last error + * @param fmt message to print + * + * @ingroup krb5_error + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_warn ( @@ -4486,14 +9238,23 @@ krb5_warn ( krb5_error_code /*code*/, const char */*fmt*/, ...) - __attribute__ ((format (printf, 3, 4))); + __attribute__ ((__format__ (__printf__, 3, 4))); + +/** + * Log a warning to the log, default stderr. + * + * @param context A Kerberos 5 context. + * @param fmt message to print + * + * @ingroup krb5_error + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_warnx ( krb5_context /*context*/, const char */*fmt*/, ...) - __attribute__ ((format (printf, 2, 3))); + __attribute__ ((__format__ (__printf__, 2, 3))); KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_write_message ( @@ -4524,4 +9285,5 @@ krb5_xfree (void */*ptr*/); #undef KRB5_DEPRECATED_FUNCTION +#endif /* DOXY */ #endif /* __krb5_protos_h__ */ |