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 <http://www.eyrie.org/~eagle/software/rra-c-util/>.
  21  *
  22  * Written by Russ Allbery <eagle@eyrie.org>
  23  *
  24  * The authors hereby relinquish any claim to any copyright that they may have
  25  * in this work, whether granted under contract or by operation of law or
  26  * international treaty, and hereby commit to the public, at large, that they
  27  * shall not, at any time in the future, seek to enforce any copyright in this
  28  * work against any person or entity, or prevent any person or entity from
  29  * copying, publishing, distributing or creating derivative works of this
  30  * work.
  31  */
  32
  33 #ifndef PORTABLE_KRB5_H
  34 #define PORTABLE_KRB5_H 1
  35
  36 /*
  37  * Allow inclusion of config.h to be skipped, since sometimes we have to use a
  38  * stripped-down version of config.h with a different name.
  39  */
  40 #ifndef CONFIG_H_INCLUDED
  41 # include <config.h>
  42 #endif
  43 #include <portable/macros.h>
  44
  45 #ifdef HAVE_KRB5_H
  46 # include <krb5.h>
  47 #else
  48 # include <krb5/krb5.h>
  49 #endif
  50 #include <stdlib.h>
  51
  52 BEGIN_DECLS
  53
  54 /* Default to a hidden visibility for all portability functions. */
  55 #pragma GCC visibility push(hidden)
  56
  57 /*
  58  * MIT-specific.  The Heimdal documentation says to use free(), but that
  59  * doesn't actually make sense since the memory is allocated inside the
  60  * Kerberos library.  Use krb5_xfree instead.
  61  */
  62 #ifndef HAVE_KRB5_FREE_DEFAULT_REALM
  63 # define krb5_free_default_realm(c, r) krb5_xfree(r)
  64 #endif
  65
  66 /*
  67  * Heimdal: krb5_xfree, MIT: krb5_free_string, older MIT uses free().  Note
  68  * that we can incorrectly allocate in the library and call free() if
  69  * krb5_free_string is not available but something we use that API for is
  70  * available, such as krb5_appdefaults_*, but there isn't anything we can
  71  * really do about it.
  72  */
  73 #ifndef HAVE_KRB5_FREE_STRING
  74 # ifdef HAVE_KRB5_XFREE
  75 #  define krb5_free_string(c, s) krb5_xfree(s)
  76 # else
  77 #  define krb5_free_string(c, s) free(s)
  78 # endif
  79 #endif
  80
  81 /* Heimdal: krb5_xfree, MIT: krb5_free_unparsed_name. */
  82 #ifdef HAVE_KRB5_XFREE
  83 # define krb5_free_unparsed_name(c, p) krb5_xfree(p)
  84 #endif
  85
  86 /*
  87  * krb5_{get,free}_error_message are the preferred APIs for both current MIT
  88  * and current Heimdal, but there are tons of older APIs we may have to fall
  89  * back on for earlier versions.
  90  *
  91  * This function should be called immediately after the corresponding error
  92  * without any intervening Kerberos calls.  Otherwise, the correct error
  93  * message and supporting information may not be returned.
  94  */
  95 #ifndef HAVE_KRB5_GET_ERROR_MESSAGE
  96 const char *krb5_get_error_message(krb5_context, krb5_error_code);
  97 #endif
  98 #ifndef HAVE_KRB5_FREE_ERROR_MESSAGE
  99 void krb5_free_error_message(krb5_context, const char *);
 100 #endif
 101
 102 /*
 103  * Both current MIT and current Heimdal prefer _opt_alloc and _opt_free, but
 104  * older versions of both require allocating your own struct and calling
 105  * _opt_init.
 106  */
 107 #ifndef HAVE_KRB5_GET_INIT_CREDS_OPT_ALLOC
 108 krb5_error_code krb5_get_init_creds_opt_alloc(krb5_context,
 109                                               krb5_get_init_creds_opt **);
 110 #endif
 111 #ifdef HAVE_KRB5_GET_INIT_CREDS_OPT_FREE
 112 # ifndef HAVE_KRB5_GET_INIT_CREDS_OPT_FREE_2_ARGS
 113 #  define krb5_get_init_creds_opt_free(c, o) krb5_get_init_creds_opt_free(o)
 114 # endif
 115 #else
 116 # define krb5_get_init_creds_opt_free(c, o) free(o)
 117 #endif
 118
 119 /* Heimdal-specific. */
 120 #ifndef HAVE_KRB5_GET_INIT_CREDS_OPT_SET_DEFAULT_FLAGS
 121 # define krb5_get_init_creds_opt_set_default_flags(c, p, r, o) /* empty */
 122 #endif
 123
 124 /*
 125  * Heimdal: krb5_kt_free_entry, MIT: krb5_free_keytab_entry_contents.  We
 126  * check for the declaration rather than the function since the function is
 127  * present in older MIT Kerberos libraries but not prototyped.
 128  */
 129 #if !HAVE_DECL_KRB5_KT_FREE_ENTRY
 130 # define krb5_kt_free_entry(c, e) krb5_free_keytab_entry_contents((c), (e))
 131 #endif
 132
 133 /*
 134  * Heimdal provides a nice function that just returns a const char *.  On MIT,
 135  * there's an accessor macro that returns the krb5_data pointer, which
 136  * requires more work to get at the underlying char *.
 137  */
 138 #ifndef HAVE_KRB5_PRINCIPAL_GET_REALM
 139 const char *krb5_principal_get_realm(krb5_context, krb5_const_principal);
 140 #endif
 141
 142 /* Undo default visibility change. */
 143 #pragma GCC visibility pop
 144
 145 END_DECLS
 146
 147 #endif /* !PORTABLE_KRB5_H */