1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
/* include/krb5/certauth_plugin.h - certauth plugin header. */
/*
* Copyright (C) 2017 by Red Hat, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
* COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
* INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/*
* Declarations for certauth plugin module implementors.
*
* The certauth pluggable interface currently has only one supported major
* version, which is 1. Major version 1 has a current minor version number of
* 1.
*
* certauth plugin modules should define a function named
* certauth_<modulename>_initvt, matching the signature:
*
* krb5_error_code
* certauth_modname_initvt(krb5_context context, int maj_ver, int min_ver,
* krb5_plugin_vtable vtable);
*
* The initvt function should:
*
* - Check that the supplied maj_ver number is supported by the module, or
* return KRB5_PLUGIN_VER_NOTSUPP if it is not.
*
* - Cast the vtable pointer as appropriate for maj_ver:
* maj_ver == 1: Cast to krb5_certauth_vtable
*
* - Initialize the methods of the vtable, stopping as appropriate for the
* supplied min_ver. Optional methods may be left uninitialized.
*
* Memory for the vtable is allocated by the caller, not by the module.
*/
#ifndef KRB5_CERTAUTH_PLUGIN_H
#define KRB5_CERTAUTH_PLUGIN_H
#include <krb5/krb5.h>
#include <krb5/plugin.h>
/* Abstract module data type. */
typedef struct krb5_certauth_moddata_st *krb5_certauth_moddata;
/* A module can optionally include <kdb.h> to inspect the client principal
* entry when authorizing a request. */
struct _krb5_db_entry_new;
/*
* Optional: Initialize module data.
*/
typedef krb5_error_code
(*krb5_certauth_init_fn)(krb5_context context,
krb5_certauth_moddata *moddata_out);
/*
* Optional: Clean up the module data.
*/
typedef void
(*krb5_certauth_fini_fn)(krb5_context context, krb5_certauth_moddata moddata);
/*
* Mandatory: return 0 or KRB5_CERTAUTH_HWAUTH if the DER-encoded cert is
* authorized for PKINIT authentication by princ; otherwise return one of the
* following error codes:
* - KRB5KDC_ERR_CLIENT_NAME_MISMATCH - incorrect SAN value
* - KRB5KDC_ERR_INCONSISTENT_KEY_PURPOSE - incorrect EKU
* - KRB5KDC_ERR_CERTIFICATE_MISMATCH - other extension error
* - KRB5_PLUGIN_NO_HANDLE - the module has no opinion about cert
*
* Returning KRB5_CERTAUTH_HWAUTH will cause the hw-authent flag to be set in
* the issued ticket (new in release 1.19).
*
* - opts is used by built-in modules to receive internal data, and must be
* ignored by other modules.
* - db_entry receives the client principal database entry, and can be ignored
* by modules that do not link with libkdb5.
* - *authinds_out optionally returns a null-terminated list of authentication
* indicator strings upon KRB5_PLUGIN_NO_HANDLE or accepted authorization.
*/
typedef krb5_error_code
(*krb5_certauth_authorize_fn)(krb5_context context,
krb5_certauth_moddata moddata,
const uint8_t *cert, size_t cert_len,
krb5_const_principal princ, const void *opts,
const struct _krb5_db_entry_new *db_entry,
char ***authinds_out);
/*
* Free indicators allocated by a module. Mandatory if authorize returns
* authentication indicators.
*/
typedef void
(*krb5_certauth_free_indicator_fn)(krb5_context context,
krb5_certauth_moddata moddata,
char **authinds);
typedef struct krb5_certauth_vtable_st {
const char *name;
krb5_certauth_init_fn init;
krb5_certauth_fini_fn fini;
krb5_certauth_authorize_fn authorize;
krb5_certauth_free_indicator_fn free_ind;
} *krb5_certauth_vtable;
#endif /* KRB5_CERTAUTH_PLUGIN_H */
|
