jpayne@69: /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ jpayne@69: /* include/krb5/certauth_plugin.h - certauth plugin header. */ jpayne@69: /* jpayne@69: * Copyright (C) 2017 by Red Hat, Inc. jpayne@69: * All rights reserved. jpayne@69: * jpayne@69: * Redistribution and use in source and binary forms, with or without jpayne@69: * modification, are permitted provided that the following conditions jpayne@69: * are met: jpayne@69: * jpayne@69: * * Redistributions of source code must retain the above copyright jpayne@69: * notice, this list of conditions and the following disclaimer. jpayne@69: * jpayne@69: * * Redistributions in binary form must reproduce the above copyright jpayne@69: * notice, this list of conditions and the following disclaimer in jpayne@69: * the documentation and/or other materials provided with the jpayne@69: * distribution. jpayne@69: * jpayne@69: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS jpayne@69: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT jpayne@69: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS jpayne@69: * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE jpayne@69: * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, jpayne@69: * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES jpayne@69: * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR jpayne@69: * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) jpayne@69: * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, jpayne@69: * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) jpayne@69: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED jpayne@69: * OF THE POSSIBILITY OF SUCH DAMAGE. jpayne@69: */ jpayne@69: jpayne@69: /* jpayne@69: * Declarations for certauth plugin module implementors. jpayne@69: * jpayne@69: * The certauth pluggable interface currently has only one supported major jpayne@69: * version, which is 1. Major version 1 has a current minor version number of jpayne@69: * 1. jpayne@69: * jpayne@69: * certauth plugin modules should define a function named jpayne@69: * certauth__initvt, matching the signature: jpayne@69: * jpayne@69: * krb5_error_code jpayne@69: * certauth_modname_initvt(krb5_context context, int maj_ver, int min_ver, jpayne@69: * krb5_plugin_vtable vtable); jpayne@69: * jpayne@69: * The initvt function should: jpayne@69: * jpayne@69: * - Check that the supplied maj_ver number is supported by the module, or jpayne@69: * return KRB5_PLUGIN_VER_NOTSUPP if it is not. jpayne@69: * jpayne@69: * - Cast the vtable pointer as appropriate for maj_ver: jpayne@69: * maj_ver == 1: Cast to krb5_certauth_vtable jpayne@69: * jpayne@69: * - Initialize the methods of the vtable, stopping as appropriate for the jpayne@69: * supplied min_ver. Optional methods may be left uninitialized. jpayne@69: * jpayne@69: * Memory for the vtable is allocated by the caller, not by the module. jpayne@69: */ jpayne@69: jpayne@69: #ifndef KRB5_CERTAUTH_PLUGIN_H jpayne@69: #define KRB5_CERTAUTH_PLUGIN_H jpayne@69: jpayne@69: #include jpayne@69: #include jpayne@69: jpayne@69: /* Abstract module data type. */ jpayne@69: typedef struct krb5_certauth_moddata_st *krb5_certauth_moddata; jpayne@69: jpayne@69: /* A module can optionally include to inspect the client principal jpayne@69: * entry when authorizing a request. */ jpayne@69: struct _krb5_db_entry_new; jpayne@69: jpayne@69: /* jpayne@69: * Optional: Initialize module data. jpayne@69: */ jpayne@69: typedef krb5_error_code jpayne@69: (*krb5_certauth_init_fn)(krb5_context context, jpayne@69: krb5_certauth_moddata *moddata_out); jpayne@69: jpayne@69: /* jpayne@69: * Optional: Clean up the module data. jpayne@69: */ jpayne@69: typedef void jpayne@69: (*krb5_certauth_fini_fn)(krb5_context context, krb5_certauth_moddata moddata); jpayne@69: jpayne@69: /* jpayne@69: * Mandatory: decode cert as an X.509 certificate and determine whether it is jpayne@69: * authorized to authenticate as the requested client principal princ using jpayne@69: * PKINIT. Return 0 or KRB5_CERTAUTH_HWAUTH if the certificate is authorized. jpayne@69: * Otherwise return one of the following error codes: jpayne@69: * jpayne@69: * - KRB5KDC_ERR_CLIENT_NAME_MISMATCH - incorrect SAN value jpayne@69: * - KRB5KDC_ERR_INCONSISTENT_KEY_PURPOSE - incorrect EKU jpayne@69: * - KRB5KDC_ERR_CERTIFICATE_MISMATCH - other extension error jpayne@69: * - KRB5_PLUGIN_NO_HANDLE or KRB5_CERTAUTH_HWAUTH_PASS - the module has no jpayne@69: * opinion about whether cert is authorized jpayne@69: * jpayne@69: * Returning KRB5_CERTAUTH_HWAUTH will authorize the PKINIT authentication and jpayne@69: * cause the hw-authent flag to be set in the issued ticket (new in release jpayne@69: * 1.19). Returning KRB5_CERTAUTH_HWAUTH_PASS does not authorize the PKINIT jpayne@69: * authentication, but causes the hw-authent flag to be set if another module jpayne@69: * authorizes it (new in release 1.20) jpayne@69: * jpayne@69: * - opts is used by built-in modules to receive internal data, and must be jpayne@69: * ignored by other modules. jpayne@69: * - db_entry receives the client principal database entry, and can be ignored jpayne@69: * by modules that do not link with libkdb5. jpayne@69: * - *authinds_out optionally returns a null-terminated list of authentication jpayne@69: * indicator strings upon KRB5_PLUGIN_NO_HANDLE or accepted authorization. jpayne@69: */ jpayne@69: typedef krb5_error_code jpayne@69: (*krb5_certauth_authorize_fn)(krb5_context context, jpayne@69: krb5_certauth_moddata moddata, jpayne@69: const uint8_t *cert, size_t cert_len, jpayne@69: krb5_const_principal princ, const void *opts, jpayne@69: const struct _krb5_db_entry_new *db_entry, jpayne@69: char ***authinds_out); jpayne@69: jpayne@69: /* jpayne@69: * Free indicators allocated by a module. Mandatory if authorize returns jpayne@69: * authentication indicators. jpayne@69: */ jpayne@69: typedef void jpayne@69: (*krb5_certauth_free_indicator_fn)(krb5_context context, jpayne@69: krb5_certauth_moddata moddata, jpayne@69: char **authinds); jpayne@69: jpayne@69: typedef struct krb5_certauth_vtable_st { jpayne@69: const char *name; jpayne@69: krb5_certauth_init_fn init; jpayne@69: krb5_certauth_fini_fn fini; jpayne@69: krb5_certauth_authorize_fn authorize; jpayne@69: krb5_certauth_free_indicator_fn free_ind; jpayne@69: } *krb5_certauth_vtable; jpayne@69: jpayne@69: #endif /* KRB5_CERTAUTH_PLUGIN_H */