Mercurial > dropbear

comparison pubkeyapi.h @ 1653:76189c9ffea2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
External Public-Key Authentication API (#72) * Implemented dynamic loading of an external plug-in shared library to delegate public key authentication * Moved conditional compilation of the plugin infrastructure into the configure.ac script to be able to add -ldl to dropbear build only when the flag is enabled * Added tags file to the ignore list * Updated API to have the constructor to return function pointers in the pliugin instance. Added support for passing user name to the checkpubkey function. Added options to the session returned by the plugin and have dropbear to parse and process them * Added -rdynamic to the linker flags when EPKA is enabled * Changed the API to pass a previously created session to the checkPubKey function (created during preauth) * Added documentation to the API * Added parameter addrstring to plugin creation function * Modified the API to retrieve the auth options. Instead of having them as field of the EPKASession struct, they are stored internally (plugin-dependent) in the plugin/session and retrieved through a pointer to a function (in the session) * Changed option string to be a simple char * instead of unsigned char *
author fabriziobertocci <fabriziobertocci@gmail.com>
date Wed, 15 May 2019 09:43:57 -0400
parents
children cc0fc5131c5c
comparison
equal deleted inserted replaced
1652:d2753238f35f 1653:76189c9ffea2
1 /*
2 * Dropbear - a SSH2 server
3 *
4 * Copyright (c) 2002,2003 Matt Johnston
5 * All rights reserved.
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23 * SOFTWARE. */
24 #ifndef DROPBEAR_PUBKEY_H
25 #define DROPBEAR_PUBKEY_H
26
27
28 /* External Public Key API (EPKA) Plug-in Interface
29 *
30 * See:
31 * https://github.com/fabriziobertocci/dropbear-epka
32 * for additional information and examples about this API
33 *
34 */
35
36 struct EPKAInstance;
37 struct EPKASession;
38
39 /* API VERSION INFORMATION -
40 * Dropbear will:
41 * - Reject any plugin with a major version mismatch
42 * - Load and print a warning if the plugin's minor version is HIGHER than
43 * dropbear's minor version (assumes properties are added at the end of
44 * EPKAInstance or EPKASession). This is a case of plugin newer than dropbear.
45 * - Reject if the plugin minor version is SMALLER than dropbear one (case
46 * of plugin older than dropbear).
47 * - Load (with no warnings) if version match.
48 */
49 #define DROPBEAR_EPKA_VERSION_MAJOR 1
50 #define DROPBEAR_EPKA_VERSION_MINOR 0
51
52
53 /* Creates an instance of the plugin.
54 *
55 * This is the main entry point of the plug-in and should be IMMUTABLE across
56 * different API versions. Dropbear will check the version number
57 * returned in the api_version to match the version it understands and reject
58 * any plugin for which API major version does not match.
59 *
60 * If the version MINOR is different, dropbear will allow the plugin to run
61 * only if: plugin_MINOR > dropbear_MINOR
62 *
63 * If plugin_MINOR < dropbeart_MINOR or if the MAJOR version is different
64 * dropbear will reject the plugin and terminate the execution.
65 *
66 * addrstring is the IP address of the client.
67 *
68 * Returns NULL in case of failure, otherwise a void * of the instance that need
69 * to be passed to all the subsequent call to the plugin
70 */
71 typedef struct EPKAInstance *(* PubkeyExtPlugin_newFn)(int verbose,
72 const char *options,
73 const char *addrstring);
74 #define DROPBEAR_PUBKEY_PLUGIN_FNNAME_NEW "plugin_new"
75
76
77 /* Validate a client through public key authentication
78 *
79 * If session has not been already created, creates it and store it
80 * in *sessionInOut.
81 * If session is a non-NULL, it will reuse it.
82 *
83 * Returns DROPBEAR_SUCCESS (0) if success or DROPBEAR_FAILURE (-1) if
84 * authentication fails
85 */
86 typedef int (* PubkeyExtPlugin_checkPubKeyFn)(struct EPKAInstance *pluginInstance,
87 struct EPKASession **sessionInOut,
88 const char* algo,
89 unsigned int algolen,
90 const unsigned char* keyblob,
91 unsigned int keybloblen,
92 const char *username);
93
94 /* Notify the plugin that auth completed (after signature verification)
95 */
96 typedef void (* PubkeyExtPlugin_authSuccessFn)(struct EPKASession *session);
97
98 /* Deletes a session
99 * TODO: Add a reason why the session is terminated. See svr_dropbear_exit (in svr-session.c)
100 */
101 typedef void (* PubkeyExtPlugin_sessionDeleteFn)(struct EPKASession *session);
102
103 /* Deletes the plugin instance */
104 typedef void (* PubkeyExtPlugin_deleteFn)(struct EPKAInstance *pluginInstance);
105
106
107 /* The EPKAInstance object - A simple container of the pointer to the functions used
108 * by Dropbear.
109 *
110 * A plug-in can extend it to add its own properties
111 *
112 * The instance is created from the call to the plugin_new() function of the
113 * shared library.
114 * The delete_plugin function should delete the object.
115 */
116 struct EPKAInstance {
117 int api_version[2]; /* 0=Major, 1=Minor */
118
119 PubkeyExtPlugin_checkPubKeyFn checkpubkey; /* mandatory */
120 PubkeyExtPlugin_authSuccessFn auth_success; /* optional */
121 PubkeyExtPlugin_sessionDeleteFn delete_session; /* mandatory */
122 PubkeyExtPlugin_deleteFn delete_plugin; /* mandatory */
123 };
124
125 /*****************************************************************************
126 * SESSION
127 ****************************************************************************/
128 /* Returns the options from the session.
129 * The returned buffer will be destroyed when the session is deleted.
130 * Option buffer string NULL-terminated
131 */
132 typedef char * (* PubkeyExtPlugin_getOptionsFn)(struct EPKASession *session);
133
134
135 /* An SSH Session. Created during pre-auth and reused during the authentication.
136 * The plug-in should delete this object (or any object extending it) from
137 * the delete_session() function.
138 *
139 * Extend it to cache user and authentication information that can be
140 * reused between pre-auth and auth (and to store whatever session-specific
141 * variable you need to keep).
142 *
143 * Store any optional auth options in the auth_options property of the session.
144 */
145 struct EPKASession {
146 struct EPKAInstance * plugin_instance;
147
148 PubkeyExtPlugin_getOptionsFn get_options;
149 };
150
151 #endif