2 * Portability wrapper around krb5.h.
4 * This header includes krb5.h and then adjusts for various portability
5 * issues, primarily between MIT Kerberos and Heimdal, so that code can be
6 * written to a consistent API.
8 * Unfortunately, due to the nature of the differences between MIT Kerberos
9 * and Heimdal, it's not possible to write code to either one of the APIs and
10 * adjust for the other one. In general, this header tries to make available
11 * the Heimdal API and fix it for MIT Kerberos, but there are places where MIT
12 * Kerberos requires a more specific call. For those cases, it provides the
13 * most specific interface.
15 * For example, MIT Kerberos has krb5_free_unparsed_name() whereas Heimdal
16 * prefers the generic krb5_xfree(). In this case, this header provides
17 * krb5_free_unparsed_name() for both APIs since it's the most specific call.
19 * The canonical version of this file is maintained in the rra-c-util package,
20 * which can be found at <https://www.eyrie.org/~eagle/software/rra-c-util/>.
22 * Written by Russ Allbery <eagle@eyrie.org>
23 * Copyright 2015, 2017, 2020 Russ Allbery <eagle@eyrie.org>
25 * The Board of Trustees of the Leland Stanford Junior University
27 * Copying and distribution of this file, with or without modification, are
28 * permitted in any medium without royalty provided the copyright notice and
29 * this notice are preserved. This file is offered as-is, without any
32 * SPDX-License-Identifier: FSFAP
35 #ifndef PORTABLE_KRB5_H
36 #define PORTABLE_KRB5_H 1
39 * Allow inclusion of config.h to be skipped, since sometimes we have to use a
40 * stripped-down version of config.h with a different name.
42 #ifndef CONFIG_H_INCLUDED
45 #include <portable/macros.h>
47 #if defined(HAVE_KRB5_H)
49 #elif defined(HAVE_KERBEROSV5_KRB5_H)
50 # include <kerberosv5/krb5.h>
52 # include <krb5/krb5.h>
58 /* Default to a hidden visibility for all portability functions. */
59 #pragma GCC visibility push(hidden)
62 * AIX included Kerberos includes the profile library but not the
63 * krb5_appdefault functions, so we provide replacements that we have to
66 #ifndef HAVE_KRB5_APPDEFAULT_STRING
67 void krb5_appdefault_boolean(krb5_context, const char *, const krb5_data *,
68 const char *, int, int *);
69 void krb5_appdefault_string(krb5_context, const char *, const krb5_data *,
70 const char *, const char *, char **);
74 * MIT-specific. The Heimdal documentation says to use free(), but that
75 * doesn't actually make sense since the memory is allocated inside the
76 * Kerberos library. Use krb5_xfree instead.
78 #ifndef HAVE_KRB5_FREE_DEFAULT_REALM
79 # define krb5_free_default_realm(c, r) krb5_xfree(r)
83 * Heimdal: krb5_xfree, MIT: krb5_free_string, older MIT uses free(). Note
84 * that we can incorrectly allocate in the library and call free() if
85 * krb5_free_string is not available but something we use that API for is
86 * available, such as krb5_appdefaults_*, but there isn't anything we can
89 #ifndef HAVE_KRB5_FREE_STRING
90 # ifdef HAVE_KRB5_XFREE
91 # define krb5_free_string(c, s) krb5_xfree(s)
93 # define krb5_free_string(c, s) free(s)
97 /* Heimdal: krb5_xfree, MIT: krb5_free_unparsed_name. */
98 #ifdef HAVE_KRB5_XFREE
99 # define krb5_free_unparsed_name(c, p) krb5_xfree(p)
103 * krb5_{get,free}_error_message are the preferred APIs for both current MIT
104 * and current Heimdal, but there are tons of older APIs we may have to fall
105 * back on for earlier versions.
107 * This function should be called immediately after the corresponding error
108 * without any intervening Kerberos calls. Otherwise, the correct error
109 * message and supporting information may not be returned.
111 #ifndef HAVE_KRB5_GET_ERROR_MESSAGE
112 const char *krb5_get_error_message(krb5_context, krb5_error_code);
114 #ifndef HAVE_KRB5_FREE_ERROR_MESSAGE
115 void krb5_free_error_message(krb5_context, const char *);
119 * Both current MIT and current Heimdal prefer _opt_alloc and _opt_free, but
120 * older versions of both require allocating your own struct and calling
123 #ifndef HAVE_KRB5_GET_INIT_CREDS_OPT_ALLOC
124 krb5_error_code krb5_get_init_creds_opt_alloc(krb5_context,
125 krb5_get_init_creds_opt **);
127 #ifdef HAVE_KRB5_GET_INIT_CREDS_OPT_FREE
128 # ifndef HAVE_KRB5_GET_INIT_CREDS_OPT_FREE_2_ARGS
129 # define krb5_get_init_creds_opt_free(c, o) \
130 krb5_get_init_creds_opt_free(o)
133 # define krb5_get_init_creds_opt_free(c, o) free(o)
136 /* Heimdal-specific. */
137 #ifndef HAVE_KRB5_GET_INIT_CREDS_OPT_SET_DEFAULT_FLAGS
138 # define krb5_get_init_creds_opt_set_default_flags(c, p, r, o) /* empty */
142 * Heimdal: krb5_kt_free_entry, MIT: krb5_free_keytab_entry_contents. We
143 * check for the declaration rather than the function since the function is
144 * present in older MIT Kerberos libraries but not prototyped.
146 #if !HAVE_DECL_KRB5_KT_FREE_ENTRY
147 # define krb5_kt_free_entry(c, e) krb5_free_keytab_entry_contents((c), (e))
151 * Heimdal provides a nice function that just returns a const char *. On MIT,
152 * there's an accessor macro that returns the krb5_data pointer, which
153 * requires more work to get at the underlying char *.
155 #ifndef HAVE_KRB5_PRINCIPAL_GET_REALM
156 const char *krb5_principal_get_realm(krb5_context, krb5_const_principal);
159 /* Undo default visibility change. */
160 #pragma GCC visibility pop
164 #endif /* !PORTABLE_KRB5_H */