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. If
89 * neither `passphrase' or `repository' is set but TRUE is returned,
90 * authentication is not required.
92 * If this connection is not configured at all this returns FALSE which
93 * will result into authentication failure. Otherwise TRUE must be
97 typedef SilcBool (*SilcConnAuthGetAuthData)(SilcConnAuth connauth,
98 SilcConnectionType conn_type,
99 unsigned char **passphrase,
100 SilcUInt32 *passphrase_len,
104 /****f* silcske/SilcConnAuthAPI/SilcConnAuthCompletion
108 * typedef void (*SilcConnAuthCompletion)(SilcConnAuth connauth,
114 * Completion callback called to indicated the result of the connection
115 * authentication protocol. If the `success' is FALSE the authentication
116 * was a failure. The authentication protocol is over after this callback
120 typedef void (*SilcConnAuthCompletion)(SilcConnAuth connauth,
124 /****f* silcske/SilcConnAuthAPI/silc_connauth_alloc
128 * SilcConnAuth silc_connauth_alloc(SilcSchedule schedule, SilcSKE ske,
129 * SilcUInt32 timeout_secs);
133 * Allocates the connection authentication protocol context. The `ske'
134 * is the successfully completed key exchange context. The `timeout_secs'
135 * is the maximum time we are waiting for the protocol to finish before
136 * it is timedout. Returns NULL on error.
139 SilcConnAuth silc_connauth_alloc(SilcSchedule schedule, SilcSKE ske,
140 SilcUInt32 timeout_secs);
142 /****f* silcske/SilcConnAuthAPI/silc_connauth_free
146 * void silc_connauth_free(SilcConnAuth connauth);
150 * Frees the connection authentication protocol context `connauth'.
153 void silc_connauth_free(SilcConnAuth connauth);
155 /****f* silcske/SilcConnAuthAPI/silc_connauth_get_ske
159 * SilcSKE silc_connauth_get_ske(SilcConnAuth connauth);
163 * Returns the associated SilcSKE context from the `connauth'. It is the
164 * pointer given as argument to silc_connauth_alloc.
167 SilcSKE silc_connauth_get_ske(SilcConnAuth connauth);
169 /****f* silcske/SilcConnAuthAPI/silc_connauth_initiator
174 * silc_connauth_initiator(SilcConnAuth connauth,
175 * SilcConnectionType conn_type,
176 * SilcAuthMethod auth_method, void *auth_data,
177 * SilcUInt32 auth_data_len,
178 * SilcConnAuthCompletion completion,
183 * Starts the connection authentication protocol as initiator. The
184 * `conn_type' is the type of connection we are. The `auth_method' is
185 * the authentication method. If it is SILC_AUTH_PASSWORD the `auth_data'
186 * and `auth_data_len' is the passphrase and its length, respectively.
187 * If it is SILC_AUTH_PUBLIC_KEY the `auth_data' is the SilcPrivateKey
188 * used to produce the digital signature. The `auth_data_len' is 0.
189 * The `completion' with `context' will be called after the protocol
192 * This returns SilcAsyncOperation context which can be used to abort
193 * the protocol before it is completed. Returns NULL on error.
197 silc_connauth_initiator(SilcConnAuth connauth,
198 SilcConnectionType conn_type,
199 SilcAuthMethod auth_method, void *auth_data,
200 SilcUInt32 auth_data_len,
201 SilcConnAuthCompletion completion,
204 /****f* silcske/SilcConnAuthAPI/silc_connauth_responder
209 * silc_connauth_responder(SilcConnAuth connauth,
210 * SilcConnAuthGetAuthData get_auth_data,
211 * SilcConnAuthCompletion completion,
216 * Starts the connection authentication protocol as responder. The
217 * `get_auth_data' is called to retrieve the authentication data for
218 * this connection. The `completion' will be called after the protocol
221 * This returns SilcAsyncOperation context which can be used to abort
222 * the protocol before it is completed. Returns NULL on error.
226 silc_connauth_responder(SilcConnAuth connauth,
227 SilcConnAuthGetAuthData get_auth_data,
228 SilcConnAuthCompletion completion,
231 #endif /* SILCCONNAUTH_H */