tests/tap/kerberos.h

   1 /*
   2  * Utility functions for tests that use Kerberos.
   3  *
   4  * The canonical version of this file is maintained in the rra-c-util package,
   5  * which can be found at <http://www.eyrie.org/~eagle/software/rra-c-util/>.
   6  *
   7  * Written by Russ Allbery <eagle@eyrie.org>
   8  * Copyright 2006, 2007, 2009, 2011, 2012, 2013, 2014
   9  *     The Board of Trustees of the Leland Stanford Junior University
  10  *
  11  * Permission is hereby granted, free of charge, to any person obtaining a
  12  * copy of this software and associated documentation files (the "Software"),
  13  * to deal in the Software without restriction, including without limitation
  14  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  15  * and/or sell copies of the Software, and to permit persons to whom the
  16  * Software is furnished to do so, subject to the following conditions:
  17  *
  18  * The above copyright notice and this permission notice shall be included in
  19  * all copies or substantial portions of the Software.
  20  *
  21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  22  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  23  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  24  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  25  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  26  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  27  * DEALINGS IN THE SOFTWARE.
  28  */
  29
  30 #ifndef TAP_KERBEROS_H
  31 #define TAP_KERBEROS_H 1
  32
  33 #include <config.h>
  34 #include <tests/tap/macros.h>
  35
  36 #ifdef HAVE_KRB5
  37 # include <portable/krb5.h>
  38 #endif
  39
  40 /* Holds the information parsed from the Kerberos test configuration. */
  41 struct kerberos_config {
  42     char *keytab;               /* Path to the keytab. */
  43     char *principal;            /* Principal whose keys are in the keytab. */
  44     char *cache;                /* Path to the Kerberos ticket cache. */
  45     char *userprinc;            /* The fully-qualified principal. */
  46     char *username;             /* The local (non-realm) part of principal. */
  47     char *realm;                /* The realm part of the principal. */
  48     char *password;             /* The password. */
  49 };
  50
  51 /*
  52  * Whether to skip all tests (by calling skip_all) in kerberos_setup if
  53  * certain configuration information isn't available.
  54  */
  55 enum kerberos_needs {
  56     TAP_KRB_NEEDS_NONE     = 0x00,
  57     TAP_KRB_NEEDS_KEYTAB   = 0x01,
  58     TAP_KRB_NEEDS_PASSWORD = 0x02,
  59     TAP_KRB_NEEDS_BOTH     = 0x01 | 0x02
  60 };
  61
  62 BEGIN_DECLS
  63
  64 /*
  65  * Set up Kerberos, returning the test configuration information.  This
  66  * obtains Kerberos tickets from config/keytab, if one is present, and stores
  67  * them in a Kerberos ticket cache, sets KRB5_KTNAME and KRB5CCNAME.  It also
  68  * loads the principal and password from config/password, if it exists, and
  69  * stores the principal, password, username, and realm in the returned struct.
  70  *
  71  * If there is no config/keytab file, KRB5_KTNAME and KRB5CCNAME won't be set
  72  * and the keytab field will be NULL.  If there is no config/password file,
  73  * the principal field will be NULL.  If the files exist but loading them
  74  * fails, or authentication fails, kerberos_setup calls bail.
  75  *
  76  * kerberos_cleanup will be run as a cleanup function normally, freeing all
  77  * resources and cleaning up temporary files on process exit.  It can,
  78  * however, be called directly if for some reason the caller needs to delete
  79  * the Kerberos environment again.  However, normally the caller can just call
  80  * kerberos_setup again.
  81  */
  82 struct kerberos_config *kerberos_setup(enum kerberos_needs)
  83     __attribute__((__malloc__));
  84 void kerberos_cleanup(void);
  85
  86 /*
  87  * Generate a krb5.conf file for testing and set KRB5_CONFIG to point to it.
  88  * The [appdefaults] section will be stripped out and the default realm will
  89  * be set to the realm specified, if not NULL.  This will use config/krb5.conf
  90  * in preference, so users can configure the tests by creating that file if
  91  * the system file isn't suitable.
  92  *
  93  * Depends on data/generate-krb5-conf being present in the test suite.
  94  *
  95  * kerberos_cleanup_conf will clean up after this function, but usually
  96  * doesn't need to be called directly since it's registered as an atexit
  97  * handler.
  98  */
  99 void kerberos_generate_conf(const char *realm);
 100 void kerberos_cleanup_conf(void);
 101
 102 /* Thes interfaces are only available with native Kerberos support. */
 103 #ifdef HAVE_KRB5
 104
 105 /* Bail out with an error, appending the Kerberos error message. */
 106 void bail_krb5(krb5_context, krb5_error_code, const char *format, ...)
 107     __attribute__((__noreturn__, __nonnull__, __format__(printf, 3, 4)));
 108
 109 /* Report a diagnostic with Kerberos error to stderr prefixed with #. */
 110 void diag_krb5(krb5_context, krb5_error_code, const char *format, ...)
 111     __attribute__((__nonnull__, __format__(printf, 3, 4)));
 112
 113 /*
 114  * Given a Kerberos context and the path to a keytab, retrieve the principal
 115  * for the first entry in the keytab and return it.  Calls bail on failure.
 116  * The returned principal should be freed with krb5_free_principal.
 117  */
 118 krb5_principal kerberos_keytab_principal(krb5_context, const char *path)
 119     __attribute__((__nonnull__));
 120
 121 #endif /* HAVE_KRB5 */
 122
 123 END_DECLS
 124
 125 #endif /* !TAP_MESSAGES_H */