include/krb5/certauth_plugin.h

0001 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
0002 /* include/krb5/certauth_plugin.h - certauth plugin header. */
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 certauth plugin module implementors.
0035  *
0036  * The certauth pluggable interface currently has only one supported major
0037  * version, which is 1.  Major version 1 has a current minor version number of
0038  * 2.
0039  *
0040  * certauth plugin modules should define a function named
0041  * certauth_<modulename>_initvt, matching the signature:
0042  *
0043  *   krb5_error_code
0044  *   certauth_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_certauth_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_CERTAUTH_PLUGIN_H
0062 #define KRB5_CERTAUTH_PLUGIN_H
0063
0064 #include <krb5/krb5.h>
0065 #include <krb5/plugin.h>
0066
0067 /* Abstract module data type. */
0068 typedef struct krb5_certauth_moddata_st *krb5_certauth_moddata;
0069
0070 /* A module can optionally include <kdb.h> to inspect the client principal
0071  * entry when authorizing a request. */
0072 struct _krb5_db_entry_new;
0073
0074 /*
0075  * Optional: Initialize module data.
0076  */
0077 typedef krb5_error_code
0078 (*krb5_certauth_init_fn)(krb5_context context,
0079                          krb5_certauth_moddata *moddata_out);
0080
0081 /*
0082  * Optional: Initialize module data.  Supersedes init if present.
0083  */
0084 typedef krb5_error_code
0085 (*krb5_certauth_init_ex_fn)(krb5_context context, const char *const *realmlist,
0086                             krb5_certauth_moddata *moddata_out);
0087
0088 /*
0089  * Optional: Clean up the module data.
0090  */
0091 typedef void
0092 (*krb5_certauth_fini_fn)(krb5_context context, krb5_certauth_moddata moddata);
0093
0094 /*
0095  * Mandatory: decode cert as an X.509 certificate and determine whether it is
0096  * authorized to authenticate as the requested client principal princ using
0097  * PKINIT.  Return 0 or KRB5_CERTAUTH_HWAUTH if the certificate is authorized.
0098  * Otherwise return one of the following error codes:
0099  *
0100  * - KRB5KDC_ERR_CLIENT_NAME_MISMATCH - incorrect SAN value
0101  * - KRB5KDC_ERR_INCONSISTENT_KEY_PURPOSE - incorrect EKU
0102  * - KRB5KDC_ERR_CERTIFICATE_MISMATCH - other extension error
0103  * - KRB5_PLUGIN_NO_HANDLE or KRB5_CERTAUTH_HWAUTH_PASS - the module has no
0104  *   opinion about whether cert is authorized
0105  *
0106  * Returning KRB5_CERTAUTH_HWAUTH will authorize the PKINIT authentication and
0107  * cause the hw-authent flag to be set in the issued ticket (new in release
0108  * 1.19).  Returning KRB5_CERTAUTH_HWAUTH_PASS does not authorize the PKINIT
0109  * authentication, but causes the hw-authent flag to be set if another module
0110  * authorizes it (new in release 1.20)
0111  *
0112  * - opts is used by built-in modules to receive internal data, and must be
0113  *   ignored by other modules.
0114  * - db_entry receives the client principal database entry, and can be ignored
0115  *   by modules that do not link with libkdb5.
0116  * - *authinds_out optionally returns a null-terminated list of authentication
0117  *   indicator strings upon KRB5_PLUGIN_NO_HANDLE or accepted authorization.
0118  */
0119 typedef krb5_error_code
0120 (*krb5_certauth_authorize_fn)(krb5_context context,
0121                               krb5_certauth_moddata moddata,
0122                               const uint8_t *cert, size_t cert_len,
0123                               krb5_const_principal princ, const void *opts,
0124                               const struct _krb5_db_entry_new *db_entry,
0125                               char ***authinds_out);
0126
0127 /*
0128  * Free indicators allocated by a module.  Mandatory if authorize returns
0129  * authentication indicators.
0130  */
0131 typedef void
0132 (*krb5_certauth_free_indicator_fn)(krb5_context context,
0133                                    krb5_certauth_moddata moddata,
0134                                    char **authinds);
0135
0136 typedef struct krb5_certauth_vtable_st {
0137     const char *name;
0138     krb5_certauth_init_fn init;
0139     krb5_certauth_fini_fn fini;
0140     krb5_certauth_authorize_fn authorize;
0141     krb5_certauth_free_indicator_fn free_ind;
0142     /* Minor version 1 ends here. */
0143
0144     krb5_certauth_init_ex_fn init_ex;
0145     /* Minor version 2 ends here. */
0146 } *krb5_certauth_vtable;
0147
0148 #endif /* KRB5_CERTAUTH_PLUGIN_H */