include/krb5/kdcpolicy_plugin.h

0001 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
0002 /* include/krb5/kdcpolicy_plugin.h - KDC policy plugin interface */
0003 /*
0004  * Copyright (C) 2017 by Red Hat, Inc.
0005  * All rights reserved.
0006  *
0007  * Redistribution and use in source and binary forms, with or without
0008  * modification, are permitted provided that the following conditions
0009  * are met:
0010  *
0011  * * Redistributions of source code must retain the above copyright
0012  *   notice, this list of conditions and the following disclaimer.
0013  *
0014  * * Redistributions in binary form must reproduce the above copyright
0015  *   notice, this list of conditions and the following disclaimer in
0016  *   the documentation and/or other materials provided with the
0017  *   distribution.
0018  *
0019  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
0020  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
0021  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
0022  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
0023  * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
0024  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
0025  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
0026  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
0027  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
0028  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0029  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
0030  * OF THE POSSIBILITY OF SUCH DAMAGE.
0031  */
0032
0033 /*
0034  * Declarations for kdcpolicy plugin module implementors.
0035  *
0036  * The kdcpolicy pluggable interface currently has only one supported major
0037  * version, which is 1.  Major version 1 has a current minor version number of
0038  * 1.
0039  *
0040  * kdcpolicy plugin modules should define a function named
0041  * kdcpolicy_<modulename>_initvt, matching the signature:
0042  *
0043  *   krb5_error_code
0044  *   kdcpolicy_modname_initvt(krb5_context context, int maj_ver, int min_ver,
0045  *                            krb5_plugin_vtable vtable);
0046  *
0047  * The initvt function should:
0048  *
0049  * - Check that the supplied maj_ver number is supported by the module, or
0050  *   return KRB5_PLUGIN_VER_NOTSUPP if it is not.
0051  *
0052  * - Cast the vtable pointer as appropriate for maj_ver:
0053  *   maj_ver == 1: Cast to krb5_kdcpolicy_vtable
0054  *
0055  * - Initialize the methods of the vtable, stopping as appropriate for the
0056  *   supplied min_ver.  Optional methods may be left uninitialized.
0057  *
0058  * Memory for the vtable is allocated by the caller, not by the module.
0059  */
0060
0061 #ifndef KRB5_POLICY_PLUGIN_H
0062 #define KRB5_POLICY_PLUGIN_H
0063
0064 #include <krb5/krb5.h>
0065
0066 /* Abstract module datatype. */
0067 typedef struct krb5_kdcpolicy_moddata_st *krb5_kdcpolicy_moddata;
0068
0069 /* A module can optionally include kdb.h to inspect principal entries when
0070  * authorizing requests. */
0071 struct _krb5_db_entry_new;
0072
0073 /*
0074  * Optional: Initialize module data.  Return 0 on success,
0075  * KRB5_PLUGIN_NO_HANDLE if the module is inoperable (due to configuration, for
0076  * example), and any other error code to abort KDC startup.  Optionally set
0077  * *data_out to a module data object to be passed to future calls.
0078  */
0079 typedef krb5_error_code
0080 (*krb5_kdcpolicy_init_fn)(krb5_context context,
0081                           krb5_kdcpolicy_moddata *data_out);
0082
0083 /* Optional: Clean up module data. */
0084 typedef krb5_error_code
0085 (*krb5_kdcpolicy_fini_fn)(krb5_context context,
0086                           krb5_kdcpolicy_moddata moddata);
0087
0088 /*
0089  * Optional: return an error code and set status to an appropriate string
0090  * literal to deny an AS request; otherwise return 0.  lifetime_out, if set,
0091  * restricts the ticket lifetime.  renew_lifetime_out, if set, restricts the
0092  * ticket renewable lifetime.
0093  */
0094 typedef krb5_error_code
0095 (*krb5_kdcpolicy_check_as_fn)(krb5_context context,
0096                               krb5_kdcpolicy_moddata moddata,
0097                               const krb5_kdc_req *request,
0098                               const struct _krb5_db_entry_new *client,
0099                               const struct _krb5_db_entry_new *server,
0100                               const char *const *auth_indicators,
0101                               const char **status, krb5_deltat *lifetime_out,
0102                               krb5_deltat *renew_lifetime_out);
0103
0104 /*
0105  * Optional: return an error code and set status to an appropriate string
0106  * literal to deny a TGS request; otherwise return 0.  lifetime_out, if set,
0107  * restricts the ticket lifetime.  renew_lifetime_out, if set, restricts the
0108  * ticket renewable lifetime.
0109  */
0110 typedef krb5_error_code
0111 (*krb5_kdcpolicy_check_tgs_fn)(krb5_context context,
0112                                krb5_kdcpolicy_moddata moddata,
0113                                const krb5_kdc_req *request,
0114                                const struct _krb5_db_entry_new *server,
0115                                const krb5_ticket *ticket,
0116                                const char *const *auth_indicators,
0117                                const char **status, krb5_deltat *lifetime_out,
0118                                krb5_deltat *renew_lifetime_out);
0119
0120 typedef struct krb5_kdcpolicy_vtable_st {
0121     const char *name;
0122     krb5_kdcpolicy_init_fn init;
0123     krb5_kdcpolicy_fini_fn fini;
0124     krb5_kdcpolicy_check_as_fn check_as;
0125     krb5_kdcpolicy_check_tgs_fn check_tgs;
0126 } *krb5_kdcpolicy_vtable;
0127
0128 #endif /* KRB5_POLICY_PLUGIN_H */