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