5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2005 - 2007 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silcske/SILC Connection Authentication
24 * SILC Connection Authenetication protocol API is used to perform the
25 * connection authentication after successful SILC Key Exchange protocol.
26 * The interface supports authentication based on passphrases and digital
27 * signatures. It is also possible to have no authentication at all.
31 #ifndef SILCCONNAUTH_H
32 #define SILCCONNAUTH_H
34 /****s* silcske/SilcConnAuthAPI/SilcConnAuth
38 * typedef struct SilcConnAuthStruct *SilcConnAuth;
42 * The connection authentication context allocated by silc_connauth_alloc
43 * and given as arguments to all silc_connauth_* functions. It is freed
44 * by silc_connauth_free.
47 typedef struct SilcConnAuthStruct *SilcConnAuth;
49 /****d* silcske/SilcConnAuthAPI/SilcConnectionType
53 * typedef enum { ... } SilcConnectionType;
57 * The type of the connection.
62 SILC_CONN_UNKNOWN = 0, /* Unknown type, cannot be sent */
63 SILC_CONN_CLIENT = 1, /* Client connection */
64 SILC_CONN_SERVER = 2, /* Server connection */
65 SILC_CONN_ROUTER = 3 /* Router connection */
69 /****f* silcske/SilcConnAuthAPI/SilcConnAuthGetAuthData
74 * (*SilcConnAuthGetAuthData)(SilcConnAuth connauth,
75 * SilcConnectionType conn_type,
76 * unsigned char **passphrase,
77 * SilcUInt32 *passphrase_len,
78 * SilcSKR *repository,
83 * Authentication callback to retrieve the authentication data from the
84 * application. This is responder callback. If the authentication
85 * method is passphrase it must be returned to `passphrase' pointer.
86 * If it is digital signatures the key repository pointer must be
87 * returned into `repository' pointer, which the library will use to
88 * find the correct public key to verify the digital signature.
90 * If this connection is not configured at all this returns FALSE which
91 * will result into authentication failure. Otherwise TRUE must be
95 typedef SilcBool (*SilcConnAuthGetAuthData)(SilcConnAuth connauth,
96 SilcConnectionType conn_type,
97 unsigned char **passphrase,
98 SilcUInt32 *passphrase_len,
102 /****f* silcske/SilcConnAuthAPI/SilcConnAuthCompletion
106 * typedef void (*SilcConnAuthCompletion)(SilcConnAuth connauth,
112 * Completion callback called to indicated the result of the connection
113 * authentication protocol. If the `success' is FALSE the authentication
114 * was a failure. The authentication protocol is over after this callback
118 typedef void (*SilcConnAuthCompletion)(SilcConnAuth connauth,
122 /****f* silcske/SilcConnAuthAPI/silc_connauth_alloc
126 * SilcConnAuth silc_connauth_alloc(SilcSchedule schedule, SilcSKE ske,
127 * SilcUInt32 timeout_secs);
131 * Allocates the connection authentication protocol context. The `ske'
132 * is the successfully completed key exchange context. The `timeout_secs'
133 * is the maximum time we are waiting for the protocol to finish before
134 * it is timedout. Returns NULL on error.
137 SilcConnAuth silc_connauth_alloc(SilcSchedule schedule, SilcSKE ske,
138 SilcUInt32 timeout_secs);
140 /****f* silcske/SilcConnAuthAPI/silc_connauth_free
144 * void silc_connauth_free(SilcConnAuth connauth);
148 * Frees the connection authentication protocol context `connauth'.
151 void silc_connauth_free(SilcConnAuth connauth);
153 /****f* silcske/SilcConnAuthAPI/silc_connauth_get_ske
157 * SilcSKE silc_connauth_get_ske(SilcConnAuth connauth);
161 * Returns the associated SilcSKE context from the `connauth'. It is the
162 * pointer given as argument to silc_connauth_alloc.
165 SilcSKE silc_connauth_get_ske(SilcConnAuth connauth);
167 /****f* silcske/SilcConnAuthAPI/silc_connauth_initiator
172 * silc_connauth_initiator(SilcConnAuth connauth,
173 * SilcConnectionType conn_type,
174 * SilcAuthMethod auth_method, void *auth_data,
175 * SilcUInt32 auth_data_len,
176 * SilcConnAuthCompletion completion,
181 * Starts the connection authentication protocol as initiator. The
182 * `conn_type' is the type of connection we are. The `auth_method' is
183 * the authentication method. If it is SILC_AUTH_PASSWORD the `auth_data'
184 * and `auth_data_len' is the passphrase and its length, respectively.
185 * If it is SILC_AUTH_PUBLIC_KEY the `auth_data' is the SilcPrivateKey
186 * used to produce the digital signature. The `auth_data_len' is 0.
187 * The `completion' with `context' will be called after the protocol
190 * This returns SilcAsyncOperation context which can be used to abort
191 * the protocol before it is completed. Returns NULL on error.
195 silc_connauth_initiator(SilcConnAuth connauth,
196 SilcConnectionType conn_type,
197 SilcAuthMethod auth_method, void *auth_data,
198 SilcUInt32 auth_data_len,
199 SilcConnAuthCompletion completion,
202 /****f* silcske/SilcConnAuthAPI/silc_connauth_responder
207 * silc_connauth_responder(SilcConnAuth connauth,
208 * SilcConnAuthGetAuthData get_auth_data,
209 * SilcConnAuthCompletion completion,
214 * Starts the connection authentication protocol as responder. The
215 * `get_auth_data' is called to retrieve the authentication data for
216 * this connection. The `completion' will be called after the protocol
219 * This returns SilcAsyncOperation context which can be used to abort
220 * the protocol before it is completed. Returns NULL on error.
224 silc_connauth_responder(SilcConnAuth connauth,
225 SilcConnAuthGetAuthData get_auth_data,
226 SilcConnAuthCompletion completion,
229 #endif /* SILCCONNAUTH_H */