xref: /freebsd/crypto/krb5/src/include/krb5/ccselect_plugin.h (revision 7f2fe78b9dd5f51c821d771b63d2e096f6fd49e9)
1*7f2fe78bSCy Schubert /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
2*7f2fe78bSCy Schubert /*
3*7f2fe78bSCy Schubert  * Copyright (C) 2011 by the Massachusetts Institute of Technology.
4*7f2fe78bSCy Schubert  * All rights reserved.
5*7f2fe78bSCy Schubert  *
6*7f2fe78bSCy Schubert  * Export of this software from the United States of America may
7*7f2fe78bSCy Schubert  *   require a specific license from the United States Government.
8*7f2fe78bSCy Schubert  *   It is the responsibility of any person or organization contemplating
9*7f2fe78bSCy Schubert  *   export to obtain such a license before exporting.
10*7f2fe78bSCy Schubert  *
11*7f2fe78bSCy Schubert  * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
12*7f2fe78bSCy Schubert  * distribute this software and its documentation for any purpose and
13*7f2fe78bSCy Schubert  * without fee is hereby granted, provided that the above copyright
14*7f2fe78bSCy Schubert  * notice appear in all copies and that both that copyright notice and
15*7f2fe78bSCy Schubert  * this permission notice appear in supporting documentation, and that
16*7f2fe78bSCy Schubert  * the name of M.I.T. not be used in advertising or publicity pertaining
17*7f2fe78bSCy Schubert  * to distribution of the software without specific, written prior
18*7f2fe78bSCy Schubert  * permission.  Furthermore if you modify this software you must label
19*7f2fe78bSCy Schubert  * your software as modified software and not distribute it in such a
20*7f2fe78bSCy Schubert  * fashion that it might be confused with the original M.I.T. software.
21*7f2fe78bSCy Schubert  * M.I.T. makes no representations about the suitability of
22*7f2fe78bSCy Schubert  * this software for any purpose.  It is provided "as is" without express
23*7f2fe78bSCy Schubert  * or implied warranty.
24*7f2fe78bSCy Schubert  */
25*7f2fe78bSCy Schubert 
26*7f2fe78bSCy Schubert /*
27*7f2fe78bSCy Schubert  * Declarations for credential cache selection module implementors.
28*7f2fe78bSCy Schubert  *
29*7f2fe78bSCy Schubert  * The ccselect pluggable interface currently has only one supported major
30*7f2fe78bSCy Schubert  * version, which is 1.  Major version 1 has a current minor version number of
31*7f2fe78bSCy Schubert  * 1.
32*7f2fe78bSCy Schubert  *
33*7f2fe78bSCy Schubert  * Credential cache selection modules should define a function named
34*7f2fe78bSCy Schubert  * ccselect_<modulename>_initvt, matching the signature:
35*7f2fe78bSCy Schubert  *
36*7f2fe78bSCy Schubert  *   krb5_error_code
37*7f2fe78bSCy Schubert  *   ccselect_modname_initvt(krb5_context context, int maj_ver, int min_ver,
38*7f2fe78bSCy Schubert  *                           krb5_plugin_vtable vtable);
39*7f2fe78bSCy Schubert  *
40*7f2fe78bSCy Schubert  * The initvt function should:
41*7f2fe78bSCy Schubert  *
42*7f2fe78bSCy Schubert  * - Check that the supplied maj_ver number is supported by the module, or
43*7f2fe78bSCy Schubert  *   return KRB5_PLUGIN_VER_NOTSUPP if it is not.
44*7f2fe78bSCy Schubert  *
45*7f2fe78bSCy Schubert  * - Cast the vtable pointer as appropriate for maj_ver:
46*7f2fe78bSCy Schubert  *     maj_ver == 1: Cast to krb5_ccselect_vtable
47*7f2fe78bSCy Schubert  *
48*7f2fe78bSCy Schubert  * - Initialize the methods of the vtable, stopping as appropriate for the
49*7f2fe78bSCy Schubert  *   supplied min_ver.  Optional methods may be left uninitialized.
50*7f2fe78bSCy Schubert  *
51*7f2fe78bSCy Schubert  * Memory for the vtable is allocated by the caller, not by the module.
52*7f2fe78bSCy Schubert  */
53*7f2fe78bSCy Schubert 
54*7f2fe78bSCy Schubert #ifndef KRB5_CCSELECT_PLUGIN_H
55*7f2fe78bSCy Schubert #define KRB5_CCSELECT_PLUGIN_H
56*7f2fe78bSCy Schubert 
57*7f2fe78bSCy Schubert #include <krb5/krb5.h>
58*7f2fe78bSCy Schubert #include <krb5/plugin.h>
59*7f2fe78bSCy Schubert 
60*7f2fe78bSCy Schubert /* An abstract type for credential cache selection module data. */
61*7f2fe78bSCy Schubert typedef struct krb5_ccselect_moddata_st *krb5_ccselect_moddata;
62*7f2fe78bSCy Schubert 
63*7f2fe78bSCy Schubert #define KRB5_CCSELECT_PRIORITY_AUTHORITATIVE 2
64*7f2fe78bSCy Schubert #define KRB5_CCSELECT_PRIORITY_HEURISTIC     1
65*7f2fe78bSCy Schubert 
66*7f2fe78bSCy Schubert /*** Method type declarations ***/
67*7f2fe78bSCy Schubert 
68*7f2fe78bSCy Schubert /*
69*7f2fe78bSCy Schubert  * Mandatory: Initialize module data and set *priority_out to one of the
70*7f2fe78bSCy Schubert  * KRB5_CCSELECT_PRIORITY constants above.  Authoritative modules will be
71*7f2fe78bSCy Schubert  * consulted before heuristic ones.
72*7f2fe78bSCy Schubert  */
73*7f2fe78bSCy Schubert typedef krb5_error_code
74*7f2fe78bSCy Schubert (*krb5_ccselect_init_fn)(krb5_context context, krb5_ccselect_moddata *data_out,
75*7f2fe78bSCy Schubert                          int *priority_out);
76*7f2fe78bSCy Schubert 
77*7f2fe78bSCy Schubert /*
78*7f2fe78bSCy Schubert  * Mandatory: Select a cache based on a server principal.  Return 0 on success,
79*7f2fe78bSCy Schubert  * with *cache_out set to the selected cache and *princ_out set to its default
80*7f2fe78bSCy Schubert  * principal.  Return KRB5_PLUGIN_NO_HANDLE to defer to other modules.  Return
81*7f2fe78bSCy Schubert  * KRB5_CC_NOTFOUND with *princ_out set if the client principal can be
82*7f2fe78bSCy Schubert  * authoritatively determined but no cache exists for it.  Return other errors
83*7f2fe78bSCy Schubert  * as appropriate.
84*7f2fe78bSCy Schubert  */
85*7f2fe78bSCy Schubert typedef krb5_error_code
86*7f2fe78bSCy Schubert (*krb5_ccselect_choose_fn)(krb5_context context, krb5_ccselect_moddata data,
87*7f2fe78bSCy Schubert                            krb5_principal server, krb5_ccache *cache_out,
88*7f2fe78bSCy Schubert                            krb5_principal *princ_out);
89*7f2fe78bSCy Schubert 
90*7f2fe78bSCy Schubert /* Optional: Release resources used by module data. */
91*7f2fe78bSCy Schubert typedef void
92*7f2fe78bSCy Schubert (*krb5_ccselect_fini_fn)(krb5_context context, krb5_ccselect_moddata data);
93*7f2fe78bSCy Schubert 
94*7f2fe78bSCy Schubert /*** vtable declarations **/
95*7f2fe78bSCy Schubert 
96*7f2fe78bSCy Schubert /* Credential cache selection plugin vtable for major version 1. */
97*7f2fe78bSCy Schubert typedef struct krb5_ccselect_vtable_st {
98*7f2fe78bSCy Schubert     const char *name;           /* Mandatory: name of module. */
99*7f2fe78bSCy Schubert     krb5_ccselect_init_fn init;
100*7f2fe78bSCy Schubert     krb5_ccselect_choose_fn choose;
101*7f2fe78bSCy Schubert     krb5_ccselect_fini_fn fini;
102*7f2fe78bSCy Schubert     /* Minor version 1 ends here. */
103*7f2fe78bSCy Schubert } *krb5_ccselect_vtable;
104*7f2fe78bSCy Schubert 
105*7f2fe78bSCy Schubert #endif /* KRB5_CCSELECT_PLUGIN_H */
106