1 /* 2 3 silcconnauth.h 4 5 Author: Pekka Riikonen <priikone@silcnet.org> 6 7 Copyright (C) 2005 - 2007 Pekka Riikonen 8 9 The contents of this file are subject to one of the Licenses specified 10 in the COPYING file; You may not use this file except in compliance 11 with the License. 12 13 The software distributed under the License is distributed on an "AS IS" 14 basis, in the hope that it will be useful, but WITHOUT WARRANTY OF ANY 15 KIND, either expressed or implied. See the COPYING file for more 16 information. 17 18 */ 19 20 /****h* silcske/SILC Connection Authentication 21 * 22 * DESCRIPTION 23 * 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. 28 * 29 ***/ 30 31 #ifndef SILCCONNAUTH_H 32 #define SILCCONNAUTH_H 33 34 /****s* silcske/SilcConnAuthAPI/SilcConnAuth 35 * 36 * NAME 37 * 38 * typedef struct SilcConnAuthStruct *SilcConnAuth; 39 * 40 * DESCRIPTION 41 * 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. 45 * 46 ***/ 47 typedef struct SilcConnAuthStruct *SilcConnAuth; 48 49 /****d* silcske/SilcConnAuthAPI/SilcConnectionType 50 * 51 * NAME 52 * 53 * typedef enum { ... } SilcConnectionType; 54 * 55 * DESCRIPTION 56 * 57 * The type of the connection. 58 * 59 * SOURCE 60 */ 61 typedef enum { 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 */ 66 } SilcConnectionType; 67 /***/ 68 69 /****f* silcske/SilcConnAuthAPI/SilcConnAuthGetAuthData 70 * 71 * SYNOPSIS 72 * 73 * typedef SilcBool 74 * (*SilcConnAuthGetAuthData)(SilcConnAuth connauth, 75 * SilcConnectionType conn_type, 76 * unsigned char **passphrase, 77 * SilcUInt32 *passphrase_len, 78 * SilcSKR *repository, 79 * void *context); 80 * 81 * DESCRIPTION 82 * 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. 91 * 92 * If this connection is not configured at all this returns FALSE which 93 * will result into authentication failure. Otherwise TRUE must be 94 * returned. 95 * 96 ***/ 97 typedef SilcBool (*SilcConnAuthGetAuthData)(SilcConnAuth connauth, 98 SilcConnectionType conn_type, 99 unsigned char **passphrase, 100 SilcUInt32 *passphrase_len, 101 SilcSKR *repository, 102 void *context); 103 104 /****f* silcske/SilcConnAuthAPI/SilcConnAuthCompletion 105 * 106 * SYNOPSIS 107 * 108 * typedef void (*SilcConnAuthCompletion)(SilcConnAuth connauth, 109 * SilcBool success, 110 * void *context); 111 * 112 * DESCRIPTION 113 * 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 117 * is called. 118 * 119 ***/ 120 typedef void (*SilcConnAuthCompletion)(SilcConnAuth connauth, 121 SilcBool success, 122 void *context); 123 124 /****f* silcske/SilcConnAuthAPI/silc_connauth_alloc 125 * 126 * SYNOPSIS 127 * 128 * SilcConnAuth silc_connauth_alloc(SilcSchedule schedule, SilcSKE ske, 129 * SilcUInt32 timeout_secs); 130 * 131 * DESCRIPTION 132 * 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. 137 * 138 ***/ 139 SilcConnAuth silc_connauth_alloc(SilcSchedule schedule, SilcSKE ske, 140 SilcUInt32 timeout_secs); 141 142 /****f* silcske/SilcConnAuthAPI/silc_connauth_free 143 * 144 * SYNOPSIS 145 * 146 * void silc_connauth_free(SilcConnAuth connauth); 147 * 148 * DESCRIPTION 149 * 150 * Frees the connection authentication protocol context `connauth'. 151 * 152 ***/ 153 void silc_connauth_free(SilcConnAuth connauth); 154 155 /****f* silcske/SilcConnAuthAPI/silc_connauth_get_ske 156 * 157 * SYNOPSIS 158 * 159 * SilcSKE silc_connauth_get_ske(SilcConnAuth connauth); 160 * 161 * DESCRIPTION 162 * 163 * Returns the associated SilcSKE context from the `connauth'. It is the 164 * pointer given as argument to silc_connauth_alloc. 165 * 166 ***/ 167 SilcSKE silc_connauth_get_ske(SilcConnAuth connauth); 168 169 /****f* silcske/SilcConnAuthAPI/silc_connauth_initiator 170 * 171 * SYNOPSIS 172 * 173 * SilcAsyncOperation 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, 179 * void *context); 180 * 181 * DESCRIPTION 182 * 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 190 * has completed. 191 * 192 * This returns SilcAsyncOperation context which can be used to abort 193 * the protocol before it is completed. Returns NULL on error. 194 * 195 ***/ 196 SilcAsyncOperation 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, 202 void *context); 203 204 /****f* silcske/SilcConnAuthAPI/silc_connauth_responder 205 * 206 * SYNOPSIS 207 * 208 * SilcAsyncOperation 209 * silc_connauth_responder(SilcConnAuth connauth, 210 * SilcConnAuthGetAuthData get_auth_data, 211 * SilcConnAuthCompletion completion, 212 * void *context); 213 * 214 * DESCRIPTION 215 * 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 219 * has completed. 220 * 221 * This returns SilcAsyncOperation context which can be used to abort 222 * the protocol before it is completed. Returns NULL on error. 223 * 224 ***/ 225 SilcAsyncOperation 226 silc_connauth_responder(SilcConnAuth connauth, 227 SilcConnAuthGetAuthData get_auth_data, 228 SilcConnAuthCompletion completion, 229 void *context); 230 231 #endif /* SILCCONNAUTH_H */ 232