| 1 |
/* eurephiadb_driver.h -- API provided by the database driver |
| 2 |
* |
| 3 |
* GPLv2 only - Copyright (C) 2008 - 2012 |
| 4 |
* David Sommerseth <[email protected]> |
| 5 |
* |
| 6 |
* This program is free software; you can redistribute it and/or |
| 7 |
* modify it under the terms of the GNU General Public License |
| 8 |
* as published by the Free Software Foundation; version 2 |
| 9 |
* of the License. |
| 10 |
* |
| 11 |
* This program is distributed in the hope that it will be useful, |
| 12 |
* but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 13 |
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 14 |
* GNU General Public License for more details. |
| 15 |
* |
| 16 |
* You should have received a copy of the GNU General Public License |
| 17 |
* along with this program; if not, write to the Free Software |
| 18 |
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
| 19 |
*/ |
| 20 |
|
| 21 |
/** |
| 22 |
* @file eurephiadb_driver.h |
| 23 |
* @author David Sommerseth <[email protected]> |
| 24 |
* @date 2008-08-06 |
| 25 |
* |
| 26 |
* @brief eurephia database driver API. Functions and constants |
| 27 |
* provided by and used by the database drivers. |
| 28 |
* |
| 29 |
*/ |
| 30 |
|
| 31 |
#include <eurephia_driverapi.h> |
| 32 |
#include <eurephia_context.h> |
| 33 |
#include <eurephiadb_session_struct.h> |
| 34 |
#include <eurephia_values_struct.h> |
| 35 |
|
| 36 |
#ifdef HAVE_LIBXML2 |
| 37 |
#include <libxml/tree.h> |
| 38 |
#endif |
| 39 |
|
| 40 |
#ifndef EUREPHIADB_DRIVER_H_ |
| 41 |
#define EUREPHIADB_DRIVER_H_ |
| 42 |
|
| 43 |
#define attempt_IPADDR 1 /**< type code for registering attempts on IP address */ |
| 44 |
#define attempt_CERTIFICATE 2 /**< type code for registering attempts on certificate */ |
| 45 |
#define attempt_USERNAME 3 /**< type code for registering attempts on username */ |
| 46 |
|
| 47 |
#define ATTEMPT_RESET 0x0A /**< mode code for resetting attempts count */ |
| 48 |
#define ATTEMPT_REGISTER 0x0B /**< mode code for registering a new attempt */ |
| 49 |
|
| 50 |
#define USERINFO_user 0x01 /**< flag for extracting user account information */ |
| 51 |
#define USERINFO_certs 0x02 /**< flag for extracting certificate information */ |
| 52 |
#define USERINFO_lastlog 0x04 /**< flag for extracting lastlog information */ |
| 53 |
#define USERINFO_attempts 0x08 /**< flag for extracting information from attempts log */ |
| 54 |
#define USERINFO_blacklist 0x10 /**< flag for extracting information from blacklist log */ |
| 55 |
|
| 56 |
/** |
| 57 |
* Mandatory function. Retrieves driver version information |
| 58 |
* |
| 59 |
* @return Returns string (const char *) containing driver version information. |
| 60 |
*/ |
| 61 |
const char * EUREPHIA_DRIVERAPI_FUNC(eDB_DriverVersion)(void); |
| 62 |
|
| 63 |
|
| 64 |
/** |
| 65 |
* Mandatory function. Retrieves driver API level |
| 66 |
* |
| 67 |
* @return Returns integer value with API level supported by driver. |
| 68 |
*/ |
| 69 |
int EUREPHIA_DRIVERAPI_FUNC(eDB_DriverAPIVersion)(void); |
| 70 |
|
| 71 |
/* |
| 72 |
* functions which needs to exists in the API level 1 |
| 73 |
*/ |
| 74 |
|
| 75 |
/** |
| 76 |
* Connect to a database |
| 77 |
* |
| 78 |
* @version API version level 1 |
| 79 |
* @param ctx eurephiaCTX - context to which the database connection will be established against. |
| 80 |
* @param argc number of arguments sent in the argument vector |
| 81 |
* @param argv char** argument vector with driver specific argument for |
| 82 |
* establishing a database connection |
| 83 |
* |
| 84 |
* @return Returns 1 on success, otherwise 0. |
| 85 |
*/ |
| 86 |
int EUREPHIA_DRIVERAPI_FUNC(eDBconnect)(eurephiaCTX *ctx, const int argc, const char **argv); |
| 87 |
|
| 88 |
/** |
| 89 |
* Disconnects from a database |
| 90 |
* |
| 91 |
* @version API version level 1 |
| 92 |
* @param ctx eurephiaCTX - context with the database connection to disconnect from. |
| 93 |
* |
| 94 |
*/ |
| 95 |
void EUREPHIA_DRIVERAPI_FUNC(eDBdisconnect) (eurephiaCTX *ctx); |
| 96 |
|
| 97 |
/** |
| 98 |
* Authenticates a certificate against the database. |
| 99 |
* |
| 100 |
* @version API version level 1 |
| 101 |
* @param ctx eurephiaCTX |
| 102 |
* @param org X.509 organisation field (O) |
| 103 |
* @param cname X.509 common name field (CN) |
| 104 |
* @param email X.509 email field (emailAddress) |
| 105 |
* @param digest Certificate SHA1 fingerprint (digest) |
| 106 |
* @param depth Certificate depth. 0 is for user certificates. 1 and higher is for CA certificates, |
| 107 |
* according to the certificates position in the certificate chain. |
| 108 |
* |
| 109 |
* @return Returns certid (certificate ID) on success. 0 is returned if certificate is not found, |
| 110 |
* or -1 if the certificate is blacklisted. |
| 111 |
*/ |
| 112 |
int EUREPHIA_DRIVERAPI_FUNC(eDBauth_TLS)(eurephiaCTX *ctx, const char *org, const char *cname, |
| 113 |
const char *email, |
| 114 |
const char *digest, const unsigned int depth); |
| 115 |
|
| 116 |
/** |
| 117 |
* Authenticates a client against the database, with users certificate ID, username and password. |
| 118 |
* |
| 119 |
* @version API version level 1 |
| 120 |
* @param ctx eurephiaCTX |
| 121 |
* @param certid certificate ID to the user being authenticated |
| 122 |
* @param username username to be authenticated |
| 123 |
* @param passwd password provided by the user |
| 124 |
* |
| 125 |
* @return Returns uicid (user-certs ID) to the user on success. 0 if user account is not |
| 126 |
* found and -1 on authentication failure. |
| 127 |
*/ |
| 128 |
int EUREPHIA_DRIVERAPI_FUNC(eDBauth_user)(eurephiaCTX *ctx, const int certid, |
| 129 |
const char *username, const char *passwd); |
| 130 |
|
| 131 |
|
| 132 |
/** |
| 133 |
* Retrieve the user ID (uid) for a given user and certificate. |
| 134 |
* |
| 135 |
* @version API version level 1 |
| 136 |
* @param ctx eurephiaCTX |
| 137 |
* @param certid Certificate ID of the user |
| 138 |
* @param username username of the user |
| 139 |
* |
| 140 |
* @return Returns uid of user on success, 0 if user account is not found, otherwise -1 on errors. |
| 141 |
*/ |
| 142 |
int EUREPHIA_DRIVERAPI_FUNC(eDBget_uid)(eurephiaCTX *ctx, const int certid, const char *username); |
| 143 |
|
| 144 |
|
| 145 |
/** |
| 146 |
* Checks if a user account (attempt_USERNAME), certificate (attempt_CERTIFICATE) or |
| 147 |
* IP address (attempt_IPADDR) is blacklisted. |
| 148 |
* |
| 149 |
* @version API version level 1 |
| 150 |
* @param ctx eurephiaCTX |
| 151 |
* @param type Must be one of the constants: attempt_USERNAME, attempt_CERTIFICATE or attempt_IPADDR |
| 152 |
* @param val Value to be checked against the blacklist. |
| 153 |
* |
| 154 |
* @return Returns 1 if a matching record was found in the blacklist table. Otherwise 0 is returned. |
| 155 |
* |
| 156 |
* @see attempt_IPADDR, attempt_CERTIFICATE, attempt_USERNAME |
| 157 |
*/ |
| 158 |
int EUREPHIA_DRIVERAPI_FUNC(eDBblacklist_check)(eurephiaCTX *ctx, const int type, const char *val); |
| 159 |
|
| 160 |
|
| 161 |
/** |
| 162 |
* Registers an attempt in the attempts log. If the number of attempts exceeds the |
| 163 |
* configured attempts limit, it will also be blacklisted immediately. |
| 164 |
* |
| 165 |
* @version API version level 1 |
| 166 |
* @param ctx eurephiaCTX |
| 167 |
* @param type Must be one of the constants: attempt_USERNAME, attempt_CERTIFICATE or attempt_IPADDR |
| 168 |
* @param mode Must be one of the constants: ATTEMPT_RESET to reset the attempts count |
| 169 |
* or ATTEMPT_REGISTER to register an attempt. |
| 170 |
* @param value Value of the what to be registered. |
| 171 |
* |
| 172 |
* @see ATTEMPT_REGISTER, ATTEMPT_RESET, attempt_IPADDR, attempt_CERTIFICATE, attempt_USERNAME |
| 173 |
*/ |
| 174 |
void EUREPHIA_DRIVERAPI_FUNC(eDBregister_attempt)(eurephiaCTX *ctx, int type, int mode, const char *value); |
| 175 |
|
| 176 |
|
| 177 |
/** |
| 178 |
* Registers a client login. This happens after the client has been authenticated successfully, |
| 179 |
* when OpenVPN does the OPENVPN_PLUGIN_CLIENT_CONNECT call to the eurephia-auth plug-in. |
| 180 |
* |
| 181 |
* @version API version level 1 |
| 182 |
* @param ctx eurephiaCTX |
| 183 |
* @param skey eurephiaSESSION. A login must be connected to an opened eurephia session. |
| 184 |
* @param certid Certificate ID of the clients user certificate |
| 185 |
* @param uid User id of the client |
| 186 |
* @param proto String containing protocol used for the connection (udp, tcp) |
| 187 |
* @param remipaddr Clients remote IP address |
| 188 |
* @param remport The port the client is connecting from |
| 189 |
* @param vpnipaddr The IP address openvpn assigned to the user |
| 190 |
* @param vpnipmask The VPN networks netmask for the VPN connection. |
| 191 |
* |
| 192 |
* @return Returns 1 on success, otherwise 0. |
| 193 |
*/ |
| 194 |
int EUREPHIA_DRIVERAPI_FUNC(eDBregister_login)(eurephiaCTX *ctx, eurephiaSESSION *skey, |
| 195 |
const int certid, const int uid, |
| 196 |
const char *proto, const char *remipaddr, const char *remport, |
| 197 |
const char *vpnipaddr, const char *vpnipmask); |
| 198 |
|
| 199 |
|
| 200 |
/** |
| 201 |
* Registers the MAC address of the clients TAP interface. This function is called when |
| 202 |
* OpenVPN does the OPENVPN_PLUGIN_LEARN_ADDRESS call to the eurephia-auth plug-in. |
| 203 |
* |
| 204 |
* @version API version level 1 |
| 205 |
* @param ctx eurephiaCTX |
| 206 |
* @param session eurephiaSESSION of the user |
| 207 |
* @param macaddr String (char *) containing the MAC address of the clients interface. |
| 208 |
* |
| 209 |
* @return Returns 1 on success, otherwise 0. |
| 210 |
*/ |
| 211 |
int EUREPHIA_DRIVERAPI_FUNC(eDBregister_vpnmacaddr)(eurephiaCTX *ctx, eurephiaSESSION *session, |
| 212 |
const char *macaddr); |
| 213 |
|
| 214 |
|
| 215 |
/** |
| 216 |
* Registers the VPN clients address. This function is called when |
| 217 |
* OpenVPN does the OPENVPN_PLUGIN_LEARN_ADDRESS call to the eurephia-auth plug-in. |
| 218 |
* In TAP mode the clients VPN MAC and IP address are stored, in TUN mode the VPN IP |
| 219 |
* address is stored. |
| 220 |
* |
| 221 |
* @version API version level 3 |
| 222 |
* @param ctx eurephiaCTX |
| 223 |
* @param session eurephiaSESSION of the user |
| 224 |
* @param macaddr String (char *) containing the MAC address of the clients interface. |
| 225 |
* @param vpnip4addr String (char *) containing the IPv4 address of the clients interface. |
| 226 |
* @param vpnip6addr String (char *) containing the IPv6 address of the clients interface. |
| 227 |
* |
| 228 |
* @return Returns 1 on success, otherwise 0. |
| 229 |
*/ |
| 230 |
int EUREPHIA_DRIVERAPI_FUNC(eDBregister_vpnclientaddr)(eurephiaCTX *ctx, eurephiaSESSION *session, |
| 231 |
const char * macaddr, |
| 232 |
const char * vpnip4addr, const char *vpnip6addr); |
| 233 |
|
| 234 |
/** |
| 235 |
* Registers when a user logged out. It will then add some information about the session to the |
| 236 |
* eurephia lastlog. |
| 237 |
* |
| 238 |
* @version API version level 1 |
| 239 |
* @param ctx eurephiaCTX |
| 240 |
* @param skey eurephiaSESSOIN of the user |
| 241 |
* @param bytes_sent Amount of bytes the OpenVPN server sent to the client |
| 242 |
* @param bytes_received Amount of bytes the OpenVPN server received from the client |
| 243 |
* @param duration How long the session lasted (in seconds) |
| 244 |
* |
| 245 |
* @return Returns 1 on success, otherwise 0. |
| 246 |
*/ |
| 247 |
int EUREPHIA_DRIVERAPI_FUNC(eDBregister_logout)(eurephiaCTX *ctx, eurephiaSESSION *skey, |
| 248 |
const char *bytes_sent, const char *bytes_received, |
| 249 |
const char *duration); |
| 250 |
|
| 251 |
|
| 252 |
/* firewall functions */ |
| 253 |
/** |
| 254 |
* Retrieves the name of the firewall profile the user access (user account + certificate) |
| 255 |
* for the user session |
| 256 |
* |
| 257 |
* @version API version level 1 |
| 258 |
* @param ctx eurephiaCTX |
| 259 |
* @param session eurephiaSESSION |
| 260 |
* |
| 261 |
* @return Returns a char pointer to a buffer with the name of the firewall profile. This buffer |
| 262 |
* must be freed when no longer needed. |
| 263 |
*/ |
| 264 |
char * EUREPHIA_DRIVERAPI_FUNC(eDBget_firewall_profile) (eurephiaCTX *ctx, eurephiaSESSION *session); |
| 265 |
|
| 266 |
/** |
| 267 |
* Retrieve a list of IP addresses found in the IP address blacklist table. |
| 268 |
* |
| 269 |
* @version API version level 1 |
| 270 |
* @param ctx eurephiaCTX |
| 271 |
* |
| 272 |
* @return Returns an eurephiaVALUES chain with all blacklisted IP addresses on success, otherwise |
| 273 |
* NULL is returned |
| 274 |
*/ |
| 275 |
eurephiaVALUES * EUREPHIA_DRIVERAPI_FUNC(eDBget_blacklisted_ip)(eurephiaCTX *ctx); |
| 276 |
|
| 277 |
/* The following functions is also declared in eurephia_session_values.c - for local internal usage. */ |
| 278 |
/** |
| 279 |
* Retrieve a unique session key based on a session seed. |
| 280 |
* |
| 281 |
* @version API version level 1 |
| 282 |
* @param ctx eurephiaCTX |
| 283 |
* @param type Must be either stSESSION for a normal session or stAUTHENTICATION for an |
| 284 |
* authentication session (before the user is really logged in) |
| 285 |
* @param sessionseed session seed of the current connection |
| 286 |
* |
| 287 |
* @return Returns the unique session key string (char *) on success, otherwise NULL. The session key |
| 288 |
* string must be freed when no longer needed. |
| 289 |
*/ |
| 290 |
char * EUREPHIA_DRIVERAPI_FUNC(eDBget_sessionkey_seed)(eurephiaCTX *ctx, sessionType type, |
| 291 |
const char *sessionseed); |
| 292 |
|
| 293 |
|
| 294 |
/** |
| 295 |
* Retrieve a unique session key based on a connections MAC address. This is called when |
| 296 |
* OpenVPN is removing the MAC address of the client as a known connection. |
| 297 |
* |
| 298 |
* @version API version level 1 |
| 299 |
* @param ctx eurephiaCTX |
| 300 |
* @param macaddr String (char *) containing the MAC address of the client |
| 301 |
* |
| 302 |
* @return Returns the unique session key string (char *) on success, otherwise NULL. The session key |
| 303 |
* string must be freed when no longer needed. |
| 304 |
*/ |
| 305 |
char * EUREPHIA_DRIVERAPI_FUNC(eDBget_sessionkey_macaddr)(eurephiaCTX *ctx, const char *macaddr); |
| 306 |
|
| 307 |
|
| 308 |
/** |
| 309 |
* Check if a session key is unique. In other words, it will check the given session key |
| 310 |
* against the database to see if it is found there or not. If not, it is unique. |
| 311 |
* |
| 312 |
* @version API version level 1 |
| 313 |
* @param ctx eurephiaCTX |
| 314 |
* @param seskey String containing the session key |
| 315 |
* |
| 316 |
* @return Returns 1 if the session key is unique and not been used earlier. |
| 317 |
*/ |
| 318 |
int EUREPHIA_DRIVERAPI_FUNC(eDBcheck_sessionkey_uniqueness)(eurephiaCTX *ctx, const char *seskey); |
| 319 |
|
| 320 |
|
| 321 |
/** |
| 322 |
* Registers a new session key against a short-term session seed. |
| 323 |
* |
| 324 |
* @version API version level 1 |
| 325 |
* @param ctx eurephiaCTX |
| 326 |
* @param seed A string (char *) containing the short-term session seed |
| 327 |
* @param seskey A string (char *) containing the new unique session key |
| 328 |
* |
| 329 |
* @return Returns 1 on success, otherwise 0 |
| 330 |
*/ |
| 331 |
int EUREPHIA_DRIVERAPI_FUNC(eDBregister_sessionkey)(eurephiaCTX *ctx, const char *seed, const char *seskey); |
| 332 |
|
| 333 |
|
| 334 |
/** |
| 335 |
* Loads all session variables for a specified session key. This is key/value pairs |
| 336 |
* which are unique for each connection. |
| 337 |
* |
| 338 |
* @version API version level 1 |
| 339 |
* @param ctx eurephiaCTX |
| 340 |
* @param sesskey String (char *) containing a session key |
| 341 |
* |
| 342 |
* @return Returns a pointer to an eurephiaVALUES pointer chain with all the variables available |
| 343 |
* for the given session. On errors, it will return an empty eurephiaVALUES chain. |
| 344 |
*/ |
| 345 |
eurephiaVALUES * EUREPHIA_DRIVERAPI_FUNC(eDBload_sessiondata)(eurephiaCTX *ctx, const char *sesskey); |
| 346 |
|
| 347 |
|
| 348 |
/** |
| 349 |
* Destroys a session. It will remove all stored session variables and mark the session |
| 350 |
* as closed in the lastlog. It will also remove the session seed/session key reference. |
| 351 |
* |
| 352 |
* @version API version level 1 |
| 353 |
* @param ctx eurephiaCTX |
| 354 |
* @param session eurephiaSESSION pointer to session to be destroyed |
| 355 |
* |
| 356 |
* @return Returns 1 on success, otherwise 0. |
| 357 |
*/ |
| 358 |
int EUREPHIA_DRIVERAPI_FUNC(eDBdestroy_session)(eurephiaCTX *ctx, eurephiaSESSION *session); |
| 359 |
|
| 360 |
|
| 361 |
/** |
| 362 |
* Add, update or remove a session variable from the database. This operation is |
| 363 |
* only affecting the given session. This function will only update the database itself. |
| 364 |
* |
| 365 |
* @version API version level 1 |
| 366 |
* @param ctx eurephiaCTX |
| 367 |
* @param session eurephiaSESSION to which the variable will be added, modified or deleted |
| 368 |
* @param mode Must be one of the constants: SESSVAL_NEW, SESSVAL_UPDATE, SESSVAL_DELETE |
| 369 |
* @param key Key name for the value to be stored |
| 370 |
* @param val Value to be stored |
| 371 |
* |
| 372 |
* @return Returns 1 on success, otherwise 0 |
| 373 |
* @see SESSVAL_NEW, SESSVAL_UPDATE, SESSVAL_DELETE |
| 374 |
*/ |
| 375 |
int EUREPHIA_DRIVERAPI_FUNC(eDBstore_session_value)(eurephiaCTX *ctx, eurephiaSESSION *session, int mode, |
| 376 |
const char *key, const char *val); |
| 377 |
|
| 378 |
|
| 379 |
/* |
| 380 |
* functions which needs to exists in the API level 2 |
| 381 |
*/ |
| 382 |
#ifdef HAVE_LIBXML2 |
| 383 |
/** |
| 384 |
* Authenticate users and sessions for the administration interface. The OpenVPN plug-in |
| 385 |
* should never use this API. |
| 386 |
* |
| 387 |
* @version API version level 2 |
| 388 |
* @param ctx eurephiaCTX |
| 389 |
* @param qryxml eurephia XML document describing the operation to be done |
| 390 |
* |
| 391 |
* XML document describing authentication of a user account |
| 392 |
* @code |
| 393 |
* <eurephia format="1"> |
| 394 |
* <Authenticate mode="user"> |
| 395 |
* <username>{username}</username> |
| 396 |
* <password>{password}</password> |
| 397 |
* <accesslevel>{accesslevel}</password> |
| 398 |
* </Authenticate> |
| 399 |
* </eurephia> |
| 400 |
* @endcode |
| 401 |
* |
| 402 |
* XML document for authenticating and validating a user session to a specific access level |
| 403 |
* @code |
| 404 |
* <eurephia format="1"> |
| 405 |
* <Authenticate mode="session"> |
| 406 |
* <sessionkey>{session key}</sessionkey> |
| 407 |
* <accesslevel>{accesslevel}</password> |
| 408 |
* </Authenticate> |
| 409 |
* </eurephia> |
| 410 |
* @endcode |
| 411 |
* |
| 412 |
* XML docuument to register the user as logged in |
| 413 |
* @code |
| 414 |
* <eurephia format="1"> |
| 415 |
* <Register mode="login" uid="{uid}">{session key}</Register> |
| 416 |
* </eurephia> |
| 417 |
* @endcode |
| 418 |
* |
| 419 |
* XML docuument to register the user as logged out |
| 420 |
* @code |
| 421 |
* <eurephia format="1"> |
| 422 |
* <Register mode="logout">{session key}</Register> |
| 423 |
* </eurephia> |
| 424 |
* @endcode |
| 425 |
* |
| 426 |
* @return Returns a valid eurephia ResultMsg XML document with the result. On fatal errors, |
| 427 |
* NULL is returned. When a username/password authentication is done, the user id of the |
| 428 |
* user will be returned in the details part of the ResultMsg. |
| 429 |
* |
| 430 |
*/ |
| 431 |
xmlDoc * EUREPHIA_DRIVERAPI_FUNC(eDBadminAuthenticate)(eurephiaCTX *ctx, xmlDoc *qryxml); |
| 432 |
|
| 433 |
|
| 434 |
/** |
| 435 |
* Set or delete configuration parameters in the database. This operation will |
| 436 |
* also update the in-memory copy of the configuration |
| 437 |
* |
| 438 |
* @param ctx eurephiaCTX |
| 439 |
* @param cfgxml XML document specifying the operation |
| 440 |
* |
| 441 |
* XML format skeleton for setting or deleting configuration parameters |
| 442 |
* @code |
| 443 |
* <eurephia format="1"> |
| 444 |
* <configuration> |
| 445 |
* <set key="{name of the key}">{Value to be assigned}</set> |
| 446 |
* <delete key="{name of the key"}/> |
| 447 |
* </configuration> |
| 448 |
* </eurephia> |
| 449 |
* @endcode |
| 450 |
* Only one operation can be called per request to this function. |
| 451 |
* |
| 452 |
* @return Returns a valid XML document with information about the operation, or NULL on fatal errors. |
| 453 |
* @see eurephiaXML_CreateDoc() |
| 454 |
*/ |
| 455 |
xmlDoc * EUREPHIA_DRIVERAPI_FUNC(eDBadminConfiguration)(eurephiaCTX *ctx, xmlDoc *cfgxml); |
| 456 |
|
| 457 |
|
| 458 |
/** |
| 459 |
* Function for view, add, update or delete user accounts |
| 460 |
* |
| 461 |
* @param ctx eurephiaCTX |
| 462 |
* @param qryxml XML document with information about the operation |
| 463 |
* |
| 464 |
* @code |
| 465 |
* <eurephia format="1"> |
| 466 |
* <UserAccount mode="{view|add|update|delete}" [uid="{uid}"]> |
| 467 |
* <fieldMapping table="users"> |
| 468 |
* <{field name}>{field value}</{field name}> |
| 469 |
* ... |
| 470 |
* <{field name}>{field value}</{field name}> |
| 471 |
* </fieldMapping> |
| 472 |
* [<sortkeys>{field name}[, {field name}...]</sortkeys>] |
| 473 |
* [<extractFlags>{extract value (int)}</extractFlags>] |
| 474 |
* </UserAccount> |
| 475 |
* </eurephia> |
| 476 |
* @endcode |
| 477 |
* Valid field names are: uid, username, password, activated, deactivated, lastaccess |
| 478 |
* |
| 479 |
* If no field names and values are given in "view" mode, all user accounts will be returned. Adding |
| 480 |
* field name tags will narrow down the query. |
| 481 |
* |
| 482 |
* For "add" mode, username and password tag is required. For the password tag, the attribute "pwhash" |
| 483 |
* can be given to indicate what kind of hashing the value provided is using. If this is not set, the |
| 484 |
* password value is expected to come in clear text and will be hashed automatically with a SHA512 |
| 485 |
* algorithm. |
| 486 |
* |
| 487 |
* For the "update" mode, the uid attribute in the UserAccount tag is required. This will be the |
| 488 |
* key for which record to update. The values being updated need to be set in the fieldMapping tags. |
| 489 |
* |
| 490 |
* For "delete" mode, the "uid" attribute in the UserAccount tag is required. This mode will also ignore |
| 491 |
* any fieldMapping tags. |
| 492 |
* |
| 493 |
* @return When mode is "view", it will return an XML document with user account information on success. |
| 494 |
* On errors in "view" mode or the other modes in general, it will return an eurephia ResultMsg |
| 495 |
* XML document with the result of the operation, or NULL on fatal errors. |
| 496 |
* |
| 497 |
* @see eurephiaXML_CreateDoc(), eurephiaXML_ParseResultMsg(), eurephiaXML_getRoot() |
| 498 |
*/ |
| 499 |
xmlDoc * EUREPHIA_DRIVERAPI_FUNC(eDBadminUserAccount)(eurephiaCTX *ctx, xmlDoc *qryxml); |
| 500 |
|
| 501 |
|
| 502 |
/** |
| 503 |
* Function for listing, registering new or deleting certificates in the database |
| 504 |
* |
| 505 |
* @version API version level 2 |
| 506 |
* @param ctx eurephiaCTX |
| 507 |
* @param qryxml XML document with information about the operation |
| 508 |
* |
| 509 |
* Skeleton of an XML document used for eDBadminCertificate() |
| 510 |
* @code |
| 511 |
* <eurephia format="1"> |
| 512 |
* <certificates mode="{list|register|delete}"> |
| 513 |
* <fieldMapping table="certificates"> |
| 514 |
* <{field name}>{field value}</{field name}> |
| 515 |
* ... |
| 516 |
* <{field name}>{field value}</{field name}> |
| 517 |
* </fieldMapping> |
| 518 |
* [<sortkeys>{field name}[, {field name}...]</sortkeys>] |
| 519 |
* </certificates> |
| 520 |
* </eurephia> |
| 521 |
* @endcode |
| 522 |
* Valid field names are: depth, digest, common_name, org, email and certid. |
| 523 |
* For list and delete mode, all field names can be used to narrow the search query. |
| 524 |
* In register mode all fields are required, except certid which must not be given. |
| 525 |
* |
| 526 |
* The sortkeys tag will only be used in list mode, and it takes a list of comma separated |
| 527 |
* field names. |
| 528 |
* |
| 529 |
* @return When mode is "list", it will return an XML document with all found certificates, otherwise NULL. |
| 530 |
* If mode is "register" or "delete" an eurephia ResultMsg XML document will be returned with |
| 531 |
* the result of the operation, or NULL on fatal errors. |
| 532 |
* |
| 533 |
* Skeleton of a result document from a "list" mode query. |
| 534 |
* @code |
| 535 |
* <eurephia format="1"> |
| 536 |
* <certificates certificates={number of found certs}"> |
| 537 |
* <certificate certid="{int}" depth="{int}" registered="{date+time}"> |
| 538 |
* <digest>{SHA1 digest of cert}</digest> |
| 539 |
* <common_name>{(CN) common name of cert}</common_name> |
| 540 |
* <organisation>{(O) organisation name of cert}</organisation> |
| 541 |
* <email>{(emailAddr) e-mail address found in cert}</email> |
| 542 |
* </certificate> |
| 543 |
* </certificates> |
| 544 |
* </eurephia> |
| 545 |
* @endcode |
| 546 |
* |
| 547 |
* @see eurephiaXML_CreateDoc(), eurephiaXML_ParseResultMsg(), eurephiaXML_getRoot() |
| 548 |
*/ |
| 549 |
xmlDoc * EUREPHIA_DRIVERAPI_FUNC(eDBadminCertificate)(eurephiaCTX *ctx, xmlDoc *qryxml); |
| 550 |
|
| 551 |
|
| 552 |
/** |
| 553 |
* Retrieve, add, modify or delete user/certificate links |
| 554 |
* |
| 555 |
* @version API version level 2 |
| 556 |
* @param ctx eurephiaCTX |
| 557 |
* @param usrcrt_xml XML document containing operation information |
| 558 |
* |
| 559 |
* Skeleton of needed XML document |
| 560 |
* @code |
| 561 |
* <eurephia format="1"> |
| 562 |
* <usercerts mode="{search|register|remove|update}" [uicid="{uicid}"]> |
| 563 |
* <fieldMapping table="usercerts"> |
| 564 |
* <{field name}>{search value}</{field name}> |
| 565 |
* </fieldMapping> |
| 566 |
* [<sortfields>{field name}[, {field name},...]</sortfields>] <!-- Only for mode='search' --> |
| 567 |
* </usercerts |
| 568 |
* </eurephia> |
| 569 |
* @endcode |
| 570 |
* |
| 571 |
* In search mode, it can be several field name tags to narrow the search. |
| 572 |
* If mode is 'update' the 'uicid' attribute must be present in the usercerts tag. |
| 573 |
* |
| 574 |
* @return Returns a valid eurephia XML document on success. If errors happened, either an XML document |
| 575 |
* with an error message will be returned or NULL. |
| 576 |
* @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot() |
| 577 |
*/ |
| 578 |
xmlDoc * EUREPHIA_DRIVERAPI_FUNC(eDBadminUserCertsLink)(eurephiaCTX *ctx, xmlDoc *usrcrt_xml); |
| 579 |
|
| 580 |
|
| 581 |
/** |
| 582 |
* List, grant or revoke access to the administration utilities |
| 583 |
* |
| 584 |
* @version API version level 2 |
| 585 |
* @param ctx eurephiaCTX |
| 586 |
* @param qryxml XML document with the operation and information. |
| 587 |
* |
| 588 |
* XML format skeleton for grant_xml |
| 589 |
* @code |
| 590 |
* <eurephia format="1"> |
| 591 |
* <admin_access mode="{list|grant|revoke}"> |
| 592 |
* <fieldMapping table="eurephia_adminaccess"> |
| 593 |
* <uid>{user id}</uid> |
| 594 |
* <interface>{C|W}</uid> |
| 595 |
* <accesslevel>{access level string}</accesslevel> |
| 596 |
* </fieldMapping> |
| 597 |
* </admin_access> |
| 598 |
* </eurephia> |
| 599 |
* @endcode |
| 600 |
* To grant or revoke access, all fields are needed. For list mode, any given fields will narrow |
| 601 |
* the database query. If no fields are given to list mode, all registered records will be returned. |
| 602 |
* The interface tag can have two valid values, C for console interface and W for web interface. |
| 603 |
* |
| 604 |
* XML format used for list mode: |
| 605 |
* @code |
| 606 |
* <eurephia format="1"> |
| 607 |
* <admin_access_list> |
| 608 |
* <user_access> |
| 609 |
* <username uid="{uid}">{username}</username> |
| 610 |
* <access_levels> |
| 611 |
* <access interface="{interface}">{access level string}</access> |
| 612 |
* ... (more access tags) |
| 613 |
* ... |
| 614 |
* </access_levels> |
| 615 |
* </user_access> |
| 616 |
* ... (another user_access tag) |
| 617 |
* </admin_access_list> |
| 618 |
* </eurephia> |
| 619 |
* @endcode |
| 620 |
* |
| 621 |
* @return Returns a valid eurephia XML document with the result of success or failure. |
| 622 |
* On fatal errors NULL is returned. |
| 623 |
* @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot() |
| 624 |
*/ |
| 625 |
xmlDoc * EUREPHIA_DRIVERAPI_FUNC(eDBadminAccessLevel)(eurephiaCTX *ctx, xmlDoc *qryxml); |
| 626 |
|
| 627 |
|
| 628 |
/** |
| 629 |
* Query or modify the firewall access profiles. |
| 630 |
* |
| 631 |
* @version API version level 2 |
| 632 |
* @param ctx eurephiaCTX |
| 633 |
* @param xmlqry XML document with the operation and information. |
| 634 |
* |
| 635 |
* The XML format skeleton |
| 636 |
* @code |
| 637 |
* <eurephia format="1"> |
| 638 |
* <firewall_profiles mode="{search|add|delete}"> |
| 639 |
* <fieldMapping table="fwprofiles"> |
| 640 |
* <{field name}>{search value}</{field name}> |
| 641 |
* </fieldMapping> |
| 642 |
* </firewall_profiles> |
| 643 |
* </eurephia> |
| 644 |
* @endcode |
| 645 |
* It can be several field name tags to narrow the search even more. |
| 646 |
* For the add mode, the fw_profile field name tag must be present. |
| 647 |
* |
| 648 |
* @return Returns a valid XML document with the result on success, otherwise either |
| 649 |
* NULL or an XML error document is returned. |
| 650 |
* @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot() |
| 651 |
*/ |
| 652 |
xmlDoc * EUREPHIA_DRIVERAPI_FUNC(eDBadminFirewallProfiles)(eurephiaCTX *ctx, xmlDoc *xmlqry); |
| 653 |
|
| 654 |
|
| 655 |
/** |
| 656 |
* Retrieve the eurephia lastlog |
| 657 |
* |
| 658 |
* @version API version level 2 |
| 659 |
* @param ctx eurephiaCTX |
| 660 |
* @param srch_xml XML document specifying the search query |
| 661 |
* @param sortkeys String containing the sort order of the fields |
| 662 |
* |
| 663 |
* The XML format skeleton |
| 664 |
* @code |
| 665 |
* <eurephia format="1"> |
| 666 |
* <lastlog_query> |
| 667 |
* <fieldMapping table="lastlog"> |
| 668 |
* <{search field}>{search value}</{search field}> |
| 669 |
* </fieldMapping> |
| 670 |
* </lastlog_query> |
| 671 |
* </eurephia> |
| 672 |
* @endcode |
| 673 |
* Valid field names are: uid, certid, ip, vpnip, status, login, logout, id, username, macaddr, uicid |
| 674 |
* |
| 675 |
* @return Returns a valid XML document on success, otherwise NULL |
| 676 |
* @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot() |
| 677 |
*/ |
| 678 |
xmlDoc * EUREPHIA_DRIVERAPI_FUNC(eDBadminGetLastlog)(eurephiaCTX *ctx, xmlDoc *srch_xml, |
| 679 |
const char *sortkeys); |
| 680 |
|
| 681 |
|
| 682 |
/** |
| 683 |
* Query or modify the attempts log. |
| 684 |
* |
| 685 |
* @version API version level 2 |
| 686 |
* @param ctx eurephiaCTX |
| 687 |
* @param qryxml document specifying the operation |
| 688 |
* |
| 689 |
* The XML format skeleton |
| 690 |
* @code |
| 691 |
* <eurephia format="1"> |
| 692 |
* <attemptslog mode="{search|reset|delete}"> |
| 693 |
* <fieldMapping table="attempts"> |
| 694 |
* <{field name}>{field value}</{field field}> |
| 695 |
* </fieldMapping> |
| 696 |
* </attemptslog> |
| 697 |
* </eurephia> |
| 698 |
* @endcode |
| 699 |
* Valid fields are: username, ip, digest, attempts, registered, lastattempt, id |
| 700 |
* |
| 701 |
* @return Returns a valid XML document on success, otherwise NULL or an XML document |
| 702 |
* with an error message. |
| 703 |
* @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot() |
| 704 |
*/ |
| 705 |
xmlDoc * EUREPHIA_DRIVERAPI_FUNC(eDBadminAttemptsLog)(eurephiaCTX *ctx, xmlDoc *qryxml); |
| 706 |
|
| 707 |
|
| 708 |
/** |
| 709 |
* Query or modify the attempts log. |
| 710 |
* |
| 711 |
* @version API version level 2 |
| 712 |
* @param ctx eurephiaCTX |
| 713 |
* @param qryxml document specifying the operation |
| 714 |
* |
| 715 |
* The XML format skeleton |
| 716 |
* @code |
| 717 |
* <eurephia format="1"> |
| 718 |
* <blacklist mode="{list|add|delete}"> |
| 719 |
* <fieldMapping table="blacklist"> |
| 720 |
* <{field name}>{field value}</{field field}> |
| 721 |
* </fieldMapping> |
| 722 |
* </blacklist> |
| 723 |
* </eurephia> |
| 724 |
* @endcode |
| 725 |
* For listing and delete mode it be several field tags to limit the search even more. |
| 726 |
* For add mode only username, IP address or certificate digest can be given. |
| 727 |
* |
| 728 |
* @return Returns a valid XML document on success, otherwise NULL or an XML document |
| 729 |
* with an error message. |
| 730 |
* @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot() |
| 731 |
*/ |
| 732 |
xmlDoc * EUREPHIA_DRIVERAPI_FUNC(eDBadminBlacklist)(eurephiaCTX *ctx, xmlDoc *qryxml); |
| 733 |
#endif /* HAVE_LIBXML2 */ |
| 734 |
|
| 735 |
#endif /* !EUREPHIADB_DRIVER_H_ */ |