portable/krb5.h

   1 /*
   2  * Portability wrapper around krb5.h.
   3  *
   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.
   7  *
   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.
  14  *
  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.
  18  *
  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/>.
  21  *
  22  * Written by Russ Allbery <eagle@eyrie.org>
  23  * Copyright 2015, 2017, 2020 Russ Allbery <eagle@eyrie.org>
  24  * Copyright 2010-2014
  25  *     The Board of Trustees of the Leland Stanford Junior University
  26  *
  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
  30  * warranty.
  31  *
  32  * SPDX-License-Identifier: FSFAP
  33  */
  34
  35 #ifndef PORTABLE_KRB5_H
  36 #define PORTABLE_KRB5_H 1
  37
  38 /*
  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.
  41  */
  42 #ifndef CONFIG_H_INCLUDED
  43 #    include <config.h>
  44 #endif
  45 #include <portable/macros.h>
  46
  47 #if defined(HAVE_KRB5_H)
  48 #    include <krb5.h>
  49 #elif defined(HAVE_KERBEROSV5_KRB5_H)
  50 #    include <kerberosv5/krb5.h>
  51 #else
  52 #    include <krb5/krb5.h>
  53 #endif
  54 #include <stdlib.h>
  55
  56 BEGIN_DECLS
  57
  58 /* Default to a hidden visibility for all portability functions. */
  59 #pragma GCC visibility push(hidden)
  60
  61 /*
  62  * AIX included Kerberos includes the profile library but not the
  63  * krb5_appdefault functions, so we provide replacements that we have to
  64  * prototype.
  65  */
  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 **);
  71 #endif
  72
  73 /*
  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.
  77  */
  78 #ifndef HAVE_KRB5_FREE_DEFAULT_REALM
  79 #    define krb5_free_default_realm(c, r) krb5_xfree(r)
  80 #endif
  81
  82 /*
  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
  87  * really do about it.
  88  */
  89 #ifndef HAVE_KRB5_FREE_STRING
  90 #    ifdef HAVE_KRB5_XFREE
  91 #        define krb5_free_string(c, s) krb5_xfree(s)
  92 #    else
  93 #        define krb5_free_string(c, s) free(s)
  94 #    endif
  95 #endif
  96
  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)
 100 #endif
 101
 102 /*
 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.
 106  *
 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.
 110  */
 111 #ifndef HAVE_KRB5_GET_ERROR_MESSAGE
 112 const char *krb5_get_error_message(krb5_context, krb5_error_code);
 113 #endif
 114 #ifndef HAVE_KRB5_FREE_ERROR_MESSAGE
 115 void krb5_free_error_message(krb5_context, const char *);
 116 #endif
 117
 118 /*
 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
 121  * _opt_init.
 122  */
 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 **);
 126 #endif
 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)
 131 #    endif
 132 #else
 133 #    define krb5_get_init_creds_opt_free(c, o) free(o)
 134 #endif
 135
 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 */
 139 #endif
 140
 141 /*
 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.
 145  */
 146 #if !HAVE_DECL_KRB5_KT_FREE_ENTRY
 147 #    define krb5_kt_free_entry(c, e) krb5_free_keytab_entry_contents((c), (e))
 148 #endif
 149
 150 /*
 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 *.
 154  */
 155 #ifndef HAVE_KRB5_PRINCIPAL_GET_REALM
 156 const char *krb5_principal_get_realm(krb5_context, krb5_const_principal);
 157 #endif
 158
 159 /* Undo default visibility change. */
 160 #pragma GCC visibility pop
 161
 162 END_DECLS
 163
 164 #endif /* !PORTABLE_KRB5_H */