path: root/database/eurephiadb_driver.h

/* eurephiadb_driver.h  --  API provided by the database driver
 *
 *  GPLv2 only - Copyright (C) 2008, 2009
 *               David Sommerseth <dazo@users.sourceforge.net>
 *
 *  This program is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU General Public License
 *  as published by the Free Software Foundation; version 2
 *  of the License.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
*/

/**
 * @file   eurephiadb_driver.h
 * @author David Sommerseth <dazo@users.sourceforge.net>
 * @date   2008-08-06
 *
 * @brief  eurephia database driver API.  Functions and constants
 *         provided by and used by the database drivers.
 *
 */

#include <eurephia_context.h>
#include <eurephiadb_session_struct.h>
#include <eurephia_values_struct.h>

#ifdef HAVE_LIBXML2
#include <libxml/tree.h>
#endif

#ifndef EUREPHIADB_DRIVER_H_
#define EUREPHIADB_DRIVER_H_

#define attempt_IPADDR      1   /**< type code for registering attempts on IP address */
#define attempt_CERTIFICATE 2   /**< type code for registering attempts on certificate */
#define attempt_USERNAME    3   /**< type code for registering attempts on username */

#define ATTEMPT_RESET    0x0A   /**< mode code for resetting attempts count */
#define ATTEMPT_REGISTER 0x0B   /**< mode code for registering a new attempt */

#define USERINFO_user       0x01 /**< flag for extracting user account information */
#define USERINFO_certs      0x02 /**< flag for extracting certificate information */
#define USERINFO_lastlog    0x04 /**< flag for extracting lastlog information */
#define USERINFO_attempts   0x08 /**< flag for extracting information from attempts log */
#define USERINFO_blacklist  0x10 /**< flag for extracting information from blacklist log */

#ifndef DRIVER_MODE

/**
 * Mandatory function. Retrieves driver version information
 *
 * @return Returns string (const char *) containing driver version information.
 */
const char *(*eDB_DriverVersion) (void);


/**
 * Mandatory function. Retrieves driver API level
 *
 * @return Returns integer value with API level supported by driver.
 */
int (*eDB_DriverAPIVersion) (void);

/*
 *    functions which needs to exists in the API level 1
 */

/**
 * Connect to a database
 *
 * @version API version level 1
 * @param ctx  eurephiaCTX - context to which the database connection will be established against.
 * @param argc number of arguments sent in the argument vector
 * @param argv char** argument vector with driver specific argument for
 *             establishing a database connection
 *
 * @return Returns 1 on success, otherwise 0.
 */
int (*eDBconnect) (eurephiaCTX *ctx, const int argc, const char **argv);

/**
 * Disconnects from a database
 *
 * @version API version level 1
 * @param ctx eurephiaCTX - context with the database connection to disconnect from.
 *
 */
void (*eDBdisconnect) (eurephiaCTX *ctx);

/**
 * Authenticates a certificate against the database.
 *
 * @version API version level 1
 * @param ctx    eurephiaCTX
 * @param org    X.509 organisation field (O)
 * @param cname  X.509 common name field (CN)
 * @param email  X.509 email field (emailAddress)
 * @param digest Certificate SHA1 fingerprint (digest)
 * @param depth  Certificate depth. 0 is for user certificates. 1 and higher is for CA certificates,
 *               according to the certificates position in the certificate chain.
 *
 * @return Returns certid (certificate ID) on success.  0 is returned if certificate is not found,
 *         or -1 if the certificate is blacklisted.
 */
int (*eDBauth_TLS) (eurephiaCTX *ctx, const char *org, const char *cname, const char *email,
                    const char *digest, const char *depth);

/**
 * Authenticates a client against the database, with users certificate ID, username and password.
 *
 * @version API version level 1
 * @param ctx eurephiaCTX
 * @param certid certificate ID to the user being authenticated
 * @param username username to be authenticated
 * @param passwd password provided by the user
 *
 * @return Returns uicid (user-certs ID) to the user on success.  0 if user account is not
 *         found and -1 on authentication failure.
 */
int (*eDBauth_user) (eurephiaCTX *ctx, const int certid, const char *username, const char *passwd);


/**
 * Retrieve the user ID (uid) for a given user and certificate.
 *
 * @version API version level 1
 * @param ctx eurephiaCTX
 * @param certid Certificate ID of the user
 * @param username username of the user
 *
 * @return Returns uid of user on success, 0 if user account is not found, otherwise -1 on errors.
 */
int (*eDBget_uid) (eurephiaCTX *ctx, const int certid, const char *username);


/**
 * Checks if a user account (attempt_USERNAME), certificate (attempt_CERTIFICATE) or
 * IP address (attempt_IPADDR) is blacklisted.
 *
 * @version API version level 1
 * @param ctx eurephiaCTX
 * @param type Must be one of the constants: attempt_USERNAME, attempt_CERTIFICATE or attempt_IPADDR
 * @param val  Value to be checked against the blacklist.
 *
 * @return Returns 1 if a matching record was found in the blacklist table.  Otherwise 0 is returned.
 *
 * @see attempt_IPADDR, attempt_CERTIFICATE, attempt_USERNAME
 */
int (*eDBblacklist_check) (eurephiaCTX *ctx, const int type, const char *val);


/**
 * Registers an attempt in the attempts log.  If the number of attempts exceeds the
 * configured attempts limit, it will also be blacklisted immediately.
 *
 * @version API version level 1
 * @param ctx eurephiaCTX
 * @param type Must be one of the constants: attempt_USERNAME, attempt_CERTIFICATE or attempt_IPADDR
 * @param mode Must be one of the constants: ATTEMPT_RESET to reset the attempts count
 *             or ATTEMPT_REGISTER to register an attempt.
 * @param value Value of the what to be registered.
 *
 * @see ATTEMPT_REGISTER, ATTEMPT_RESET, attempt_IPADDR, attempt_CERTIFICATE, attempt_USERNAME
 */
void (*eDBregister_attempt) (eurephiaCTX *ctx, int type, int mode, const char *value);


/**
 * Registers a client login.  This happens after the client has been authenticated successfully,
 * when OpenVPN does the OPENVPN_PLUGIN_CLIENT_CONNECT call to the eurephia-auth plug-in.
 *
 * @version API version level 1
 * @param ctx        eurephiaCTX
 * @param skey       eurephiaSESSION.  A login must be connected to an opened eurephia session.
 * @param certid     Certificate ID of the clients user certificate
 * @param uid        User id of the client
 * @param proto      String containing protocol used for the connection (udp, tcp)
 * @param remipaddr  Clients remote IP address
 * @param remport    The port the client is connecting from
 * @param vpnipaddr  The IP address openvpn assigned to the user
 * @param vpnipmask  The VPN networks netmask for the VPN connection.
 *
 * @return Returns 1 on success, otherwise 0.
 */
int (*eDBregister_login) (eurephiaCTX *ctx, eurephiaSESSION *skey, const int certid, const int uid,
                          const char *proto, const char *remipaddr, const char *remport,
                          const char *vpnipaddr, const char *vpnipmask);


/**
 *  Registers the MAC address of the clients TAP interface.  This function is called when
 *  OpenVPN does the OPENVPN_PLUGIN_LEARN_ADDRESS call to the eurephia-auth plug-in.
 *
 * @version API version level 1
 * @param ctx     eurephiaCTX
 * @param session eurephiaSESSION of the user
 * @param macaddr String (char *) containing the MAC address of the clients interface.
 *
 * @return Returns 1 on success, otherwise 0.
 */
int (*eDBregister_vpnmacaddr) (eurephiaCTX *ctx, eurephiaSESSION *session, const char *macaddr);


/**
 * Registers when a user logged out.  It will then add some information about the session to the
 * eurephia lastlog.
 *
 * @version API version level 1
 * @param ctx            eurephiaCTX
 * @param skey           eurephiaSESSOIN of the user
 * @param bytes_sent     Amount of bytes the OpenVPN server sent to the client
 * @param bytes_received Amount of bytes the OpenVPN server received from the client
 * @param duration       How long the session lasted (in seconds)
 *
 * @return Returns 1 on success, otherwise 0.
 */
int (*eDBregister_logout) (eurephiaCTX *ctx, eurephiaSESSION *skey,
                           const char *bytes_sent, const char *bytes_received, const char *duration);


/* firewall functions */
/**
 * Retrieves the name of the firewall profile the user access (user account + certificate)
 * for the user session
 *
 * @version API version level 1
 * @param ctx eurephiaCTX
 * @param session eurephiaSESSION
 *
 * @return Returns a char pointer to a buffer with the name of the firewall profile. This buffer
 *         must be freed when no longer needed.
 */
char *(*eDBget_firewall_profile) (eurephiaCTX *ctx, eurephiaSESSION *session);

/**
 * Retrieve a list of IP addresses found in the IP address blacklist table.
 *
 * @version API version level 1
 * @param ctx eurephiaCTX
 *
 * @return Returns an eurephiaVALUES chain with all blacklisted IP addresses on success, otherwise
 *         NULL is returned
 */
eurephiaVALUES *(*eDBget_blacklisted_ip) (eurephiaCTX *ctx);

/* The following functions is also declared in eurephia_session_values.c - for local internal usage. */
/**
 * Retrieve a unique session key based on a session seed.
 *
 * @version API version level 1
 * @param ctx         eurephiaCTX
 * @param type        Must be either stSESSION for a normal session or stAUTHENTICATION for an
 *                    authentication session (before the user is really logged in)
 * @param sessionseed session seed of the current connection
 *
 * @return Returns the unique session key string (char *) on success, otherwise NULL.  The session key
 *         string must be freed when no longer needed.
 */
char *(*eDBget_sessionkey_seed) (eurephiaCTX *ctx, sessionType type, const char *sessionseed);


/**
 * Retrieve a unique session key based on a connections MAC address.  This is called when
 * OpenVPN is removing the MAC address of the client as a known connection.
 *
 * @version API version level 1
 * @param ctx      eurephiaCTX
 * @param macaddr  String (char *) containing the MAC address of the client
 *
 * @return Returns the unique session key string (char *) on success, otherwise NULL.  The session key
 *         string must be freed when no longer needed.
 */
char *(*eDBget_sessionkey_macaddr) (eurephiaCTX *ctx, const char *macaddr);


/**
 * Check if a session key is unique.  In other words, it will check the given session key
 * against the database to see if it is found there or not.  If not, it is unique.
 *
 * @version API version level 1
 * @param ctx eurephiaCTX
 * @param seskey String containing the session key
 *
 * @return Returns 1 if the session key is unique and not been used earlier.
 */
int (*eDBcheck_sessionkey_uniqueness) (eurephiaCTX *ctx, const char *seskey);


/**
 * Registers a new session key against a short-term session seed.
 *
 * @version API version level 1
 * @param ctx     eurephiaCTX
 * @param seed    A string (char *) containing the short-term session seed
 * @param seskey  A string (char *) containing the new unique session key
 *
 * @return Returns 1 on success, otherwise 0
 */
int (*eDBregister_sessionkey) (eurephiaCTX *ctx, const char *seed, const char *seskey);


/**
 * Loads all session variables for a specified session key.  This is key/value pairs
 * which are unique for each connection.
 *
 * @version API version level 1
 * @param ctx     eurephiaCTX
 * @param sesskey String (char *) containing a session key
 *
 * @return Returns a pointer to an eurephiaVALUES pointer chain with all the variables available
 *         for the given session.  On errors, it will return an empty eurephiaVALUES chain.
 */
eurephiaVALUES *(*eDBload_sessiondata) (eurephiaCTX *ctx, const char *sesskey);


/**
 * Destroys a session.  It will remove all stored session variables and mark the session
 * as closed in the lastlog.  It will also remove the session seed/session key reference.
 *
 * @version API version level 1
 * @param ctx      eurephiaCTX
 * @param session  eurephiaSESSION pointer to session to be destroyed
 *
 * @return Returns 1 on success, otherwise 0.
 */
int (*eDBdestroy_session) (eurephiaCTX *ctx, eurephiaSESSION *session);


/**
 * Add, update or remove a session variable from the database.  This operation is
 * only affecting the given session.  This function will only update the database itself.
 *
 * @version API version level 1
 * @param ctx      eurephiaCTX
 * @param session  eurephiaSESSION to which the variable will be added, modified or deleted
 * @param mode     Must be one of the constants: SESSVAL_NEW, SESSVAL_UPDATE, SESSVAL_DELETE
 * @param key      Key name for the value to be stored
 * @param val      Value to be stored
 *
 * @return Returns 1 on success, otherwise 0
 * @see SESSVAL_NEW, SESSVAL_UPDATE, SESSVAL_DELETE
 */
int (*eDBstore_session_value)(eurephiaCTX *ctx, eurephiaSESSION *session, int mode,
                              const char *key, const char *val);

/*
 *    functions which needs to exists in the API level 2
 */
/**
 * Authenticate a user for the administration interface.  This interface do not
 * require any certificate validation and is intended for administration utilities
 * for eurephia.  The eurephia context type must be either ECTX_ADMIN_CONSOLE or
 * ECTX_ADMIN_WEB.
 *
 * @version API version level 2
 * @param ctx         eurephiaCTX - context used for administration task
 * @param req_access  String (char *) containing the requested administration access level
 * @param uname       username of the user being authenticated
 * @param pwd         password from the user
 *
 * @return Returns users ID (uid) on success, otherwise 0
 */
int (*eDBadminAuth) (eurephiaCTX *ctx, const char *req_access, const char *uname, const char *pwd);


/**
 * Validates a session key, to see if it still is valid (not auto-logged out or invalid session key)
 * and to check if they have access to a different access level. The eurephia context type must be
 * either ECTX_ADMIN_CONSOLE or ECTX_ADMIN_WEB.
 *
 * @version API version level 2
 * @param ctx        eurephiaCTX
 * @param sesskey    String (char *) containing the session key to validate
 * @param req_access String (char *) containing the required administration access level
 *
 * @return Returns 1 if the session is valid and the user have the needed privileges,
 *         otherwise 0 is returned.
 */
int (*eDBadminValidateSession) (eurephiaCTX *ctx, const char *sesskey, const char *req_access);


/**
 * Registers the user as logged in after a successful authentication.  The user must
 * be registered as logged in to have a valid session.
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param session eurephiaSESSION
 *
 * @return Returns 1 on success, otherwise 0
 */
int (*eDBadminRegisterLogin) (eurephiaCTX *ctx, eurephiaSESSION *session);


/**
 * Registers a session as logged out.  This will require the user to do a new authentication
 * on next access via the administration interface
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param sessionkey String (char *) containing the session key
 *
 * @return Returns 1 on success, otherwise 0
 */
int (*eDBadminLogout) (eurephiaCTX *ctx, const char *sessionkey);


#ifdef HAVE_LIBXML2
/**
 * Set or delete configuration parameters in the database.  This operation will
 * also update the in-memory copy of the configuration
 *
 * @param ctx    eurephiaCTX
 * @param cfgxml XML document specifying the operation
 *
 * XML format skeleton for setting or deleting configuration parameters
 * @code
 * <eurephia format="1">
 *      <configuration>
 *         <set key="{name of the key}">{Value to be assigned}</set>
 *         <delete key="{name of the key"}/>
 *      </configuration>
 * </eurephia>
 * @endcode
 * Only one operation can be called per request to this function.
 *
 * @return Returns a valid XML document with information about the operation, or NULL on fatal errors.
 * @see eurephiaXML_CreateDoc()
 */
xmlDoc *(*eDBadminConfiguration)(eurephiaCTX *ctx, xmlDoc *cfgxml);


/**
 * Retrieve a list over all users in the database.
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param sortkeys String containing the sort order of the fields
 *
 * @return Returns an XML document on success with all users, otherwise NULL
 * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
 */
xmlDoc *(*eDBadminGetUserList) (eurephiaCTX *ctx, const char *sortkeys);


/**
 * This function will search up a user, based on information given in a fieldMapping structure.
 * It will return an XML document containing the user information requested, controlled by the
 * infoType flag. These flags are defined in eurephiadb_driver.h
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param infoType Flags of what information to extract.  Valid flags are: USERINFO_user,
 *                 USERINFO_certs, USERINFO_lastlog, USERINFO_attempts, USERINFO_blacklist.
 *                 These flags can be bit-wise OR'ed together to extract more information
 *                 at once.
 *
 * @param srch XML document describing the search criteria
 *
 * Skeleton of an XML search document
 * @code
 *    <eurephia format="1">
 *        <fieldMapping table="users">
 *           <{search field}>{search value}</{search field}>
 *        </fieldMapping>
 *    </eurephia>
 * @endcode
 *
 * @return Returns an XML document containing the requested user information on success, otherwise
 *         NULL is returned.
 * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
 * @see USERINFO_user, USERINFO_certs, USERINFO_lastlog, USERINFO_attempts, USERINFO_blacklist
 */
xmlDoc *(*eDBadminGetUserInfo) (eurephiaCTX *ctx, int infoType, xmlDoc *srch);


/**
 * This function will add a user to the openvpn_users table, based on the
 * XML document given.
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param userinfo XML document containing information about the new user
 *
 * Skeleton of an XML document for adding a new user
 * @code
 *    <eurephia format="1">
 *       <add_user>
 *           <fieldMapping table="users">
 *               <username>{user name}</username>
 *               <password pwhash="{none|sha512}">{password}</password>
 *           </fieldMapping>
 *       </add_user>
 *    </eurephia>
 * @endcode
 *
 * The password tag can use either a clear-text password (by setting pwhash="none") or a pre-hashed
 * SHA512 password (by setting pwhash="sha512").  Beware that the SHA512 hash must be hashed with
 * the eurephia_pwd_crypt() function.
 *
 * @return Returns the user ID (uid) of the new user account on success, otherwise -1 is returned.
 * @see eurephiaXML_CreateDoc(), eurephia_pwd_crypt()
 */
int (*eDBadminAddUser) (eurephiaCTX *ctx, xmlDoc *userinfo);


/**
 * This function will update a user account based on the XML document sent in as a parameter.
 * The function will double check that the uid in the argument list and the uid in the XML
 * document is coherent.
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param uid Numeric user ID of the user account being updated
 * @param userinfo XML document containing the new information for the user account
 *
 * Skeleton of an XML document updating a user
 * @code
 *   <eurephia format="1">
 *       <update_user uid="{uid}">
 *           <fieldMapping table="users">
 *              <{field name}>{new value}</{field name}>
 *           </fieldMapping>
 *       </update_user>
 *   </eurephia>
 * @endcode
 * @remarks Beware that the uid attribute in the update_user tag must be the same user ID given as
 *          argument to the function.
 *
 * @return Returns 1 on success, otherwise 0.
 * @see eurephiaXML_CreateDoc()
 */
int (*eDBadminUpdateUser) (eurephiaCTX *ctx, const int uid, xmlDoc *userinfo);


/**
 * This function will delete a user to the openvpn_users table, based on the
 * XML document given.
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param uid Numeric user ID of the user account being updated
 * @param userinfo XML document containing information about the account which is going to be deleted
 *
 * @code
 *   <eurephia format="1">
 *       <delete_user uid="{uid}"/>
 *   </eurephia>
 * @endcode
 * @remarks The uid of the account to be deleted must also be sent
 *          as a separate parameter, as a security feature
 *
 * @return Returns 1 on success, otherwise 0.
 * @see eurephiaXML_CreateDoc()
 */
int (*eDBadminDeleteUser) (eurephiaCTX *ctx, const int uid, xmlDoc *userinfo);


/**
 * Get information about a specific certificate
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param srchxml XML document describing the search criteria
 * @param sortkeys String containing the sort order of the fields
 *
 * Skeleton of an XML search document
 * @code
 *    <eurephia format="1">
 *      <certificate_info>
 *        <fieldMapping table="certificates">
 *            <{field name}>{field value}</{field name}>
 *            ...
 *            <{field name}>{field value}</{field name}>
 *        </fieldMapping>
 *      </certificate_info>
 *    </eurephia>
 * @endcode
 *
 * @return Returns an XML document containing the requested certificate information on success, otherwise
 *         NULL is returned.
 *
 * Skeleton of a result document
 * @code
 * <eurephia format="1">
 *    <certificates certificates={number of found certs}">
 *        <certificate certid="{int}" depth="{int}" registered="{date+time}">
 *            <digest>{SHA1 digest of cert}</digest>
 *            <common_name>{(CN) common name of cert}</common_name>
 *            <organisation>{(O) organisation name of cert}</organisation>
 *            <email>{(emailAddr) e-mail address found in cert}</email>
 *        </certificate>
 *    </certificates>
 * </eurephia>
 * @endcode
 *
 * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
 */
xmlDoc *(*eDBadminGetCertificateInfo) (eurephiaCTX *ctx, xmlDoc *srchxml, const char *sortkeys);


/**
 * Register a certificate in the database
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param certinfo_xml XML document with the certificate information.
 *
 * Skeleton of an XML document needed for registering a new certificate
 * @code
 * <eurephia format="1">
 *      <register_certificate>
 *          <fieldMapping table="certificates">
 *              <depth>{cert.depth}</depth>
 *              <digest>{SHA1 digest}</digest>
 *              <common_name>{common_name}</common_name>
 *              <organisation>{org.}</organisation>
 *              <email>{email addr}</email>
 *          </fieldMapping>
 *      </register_certificate>
 * </eurephia>
 * @endcode
 *
 * @return The function returns certid of the newly registered certificate on success, otherwise -1
 * @see eurephiaXML_CreateDoc()
 */
int (*eDBadminAddCertificate) (eurephiaCTX *ctx, xmlDoc *certinfo_xml);


/**
 * Delete a certificate from the database
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param certinfo_xml XML document with the certificate information to be deleted
 *
 * Skeleton of an XML document to delete certificates.  Not all fields in the
 * fieldMapping tag is needed, to delete more than one certificate in one operation.
 * @code
 * <eurephia format="1">
 *      <delete_certificate>
 *          <fieldMapping table="certificates">
 *              <digest>{SHA1 digest}</digest>
 *              <common_name>{common_name}</common_name>
 *              <organisation>{org.}</organisation>
 *              <email>{email addr}</email>
 *          </fieldMapping>
 *      </register_certificate>
 * </eurephia>
 * @endcode
 *
 * @return Returns 1 on success, otherwise 0.
 * @see eurephiaXML_CreateDoc()
 */
int (*eDBadminDeleteCertificate) (eurephiaCTX *ctx, xmlDoc *certinfo_xml);


/**
 * Retrieve, add, modify or delete user/certificate links
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param usrcrt_xml XML document containing operation information
 *
 * Skeleton of needed XML document
 * @code
 *    <eurephia format="1">
 *        <usercerts mode="{search|register|remove|update}" [uicid="{uicid}"]>
 *            <fieldMapping table="usercerts">
 *               <{field name}>{search value}</{field name}>
 *            </fieldMapping>
 *            [<sortfields>{field name}[, {field name},...]</sortfields>] <!-- Only for mode='search' -->
 *        </usercerts
 *    </eurephia>
 * @endcode
 *
 * In search mode, it can be several field name tags to narrow the search.
 * If mode is 'update' the 'uicid' attribute must be present in the usercerts tag.
 *
 * @return Returns a valid eurephia XML document on success.  If errors happened, either an XML document
 *         with an error message will be returned or NULL.
 * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
 */
xmlDoc *(*eDBadminUserCertsLink) (eurephiaCTX *ctx, xmlDoc *usrcrt_xml);


/**
 * List, grant or revoke access to the administration utilities
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param qryxml XML document with the operation and information.
 *
 * XML format skeleton for grant_xml
 * @code
 * <eurephia format="1">
 *      <admin_access mode="{list|grant|revoke}">
 *          <fieldMapping table="eurephia_adminaccess">
 *              <uid>{user id}</uid>
 *              <interface>{C|W}</uid>
 *              <accesslevel>{access level string}</accesslevel>
 *          </fieldMapping>
 *      </admin_access>
 * </eurephia>
 * @endcode
 * To grant or revoke access, all fields are needed.  For list mode, any given fields will narrow
 * the database query.  If no fields are given to list mode, all registered records will be returned.
 * The interface tag can have two valid values, C for console interface and W for web interface.
 *
 * XML format used for list mode:
 * @code
 * <eurephia format="1">
 *     <admin_access_list>
 *         <user_access>
 *             <username uid="{uid}">{username}</username>
 *             <access_levels>
 *                 <access interface="{interface}">{access level string}</access>
 *                 ... (more access tags)
 *                 ...
 *             </access_levels>
 *         </user_access>
 *         ... (another user_access tag)
 *     </admin_access_list>
 * </eurephia>
 * @endcode
 *
 * @return Returns a valid eurephia XML document with the result of success or failure.
 *         On fatal errors NULL is returned.
 * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
 */
xmlDoc *(*eDBadminAccessLevel) (eurephiaCTX *ctx, xmlDoc *qryxml);


/**
 * Query or modify the firewall access profiles.
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param xmlqry XML document with the operation and information.
 *
 * The XML format skeleton
 * @code
 *    <eurephia format="1">
 *        <firewall_profiles mode="{search|add|delete}">
 *            <fieldMapping table="fwprofiles">
 *               <{field name}>{search value}</{field name}>
 *            </fieldMapping>
 *        </firewall_profiles>
 *    </eurephia>
 * @endcode
 * It can be several field name tags to narrow the search even more.
 * For the add mode, the fw_profile field name tag must be present.
 *
 * @return Returns a valid XML document with the result on success, otherwise either
 *         NULL or an XML error document is returned.
 * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
 */
xmlDoc *(*eDBadminFirewallProfiles) (eurephiaCTX *ctx, xmlDoc *xmlqry);


/**
 * Retrieve the eurephia lastlog
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param srch_xml XML document specifying the search query
 * @param sortkeys String containing the sort order of the fields
 *
 * The XML format skeleton
 * @code
 *    <eurephia format="1">
 *        <lastlog_query>
 *            <fieldMapping table="lastlog">
 *               <{search field}>{search value}</{search field}>
 *            </fieldMapping>
 *        </lastlog_query>
 *    </eurephia>
 * @endcode
 * Valid field names are: uid, certid, ip, vpnip, status, login, logout, id, username, macaddr, uicid
 *
 * @return Returns a valid XML document on success, otherwise NULL
 * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
 */
xmlDoc *(*eDBadminGetLastlog) (eurephiaCTX *ctx, xmlDoc *srch_xml, const char *sortkeys);


/**
 * Query or modify the attempts log.
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param qryxml document specifying the operation
 *
 * The XML format skeleton
 * @code
 *    <eurephia format="1">
 *        <attemptslog mode="{search|reset|delete}">
 *            <fieldMapping table="attempts">
 *               <{field name}>{field value}</{field field}>
 *            </fieldMapping>
 *        </attemptslog>
 *    </eurephia>
 * @endcode
 * Valid fields are: username, ip, digest, attempts, registered, lastattempt, id
 *
 * @return Returns a valid XML document on success, otherwise NULL or an XML document
 *         with an error message.
 * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
 */
xmlDoc *(*eDBadminAttemptsLog) (eurephiaCTX *ctx, xmlDoc *qryxml);


/**
 * Query or modify the attempts log.
 *
 * @version API version level 2
 * @param ctx eurephiaCTX
 * @param qryxml document specifying the operation
 *
 * The XML format skeleton
 * @code
 *    <eurephia format="1">
 *        <blacklist mode="{list|add|delete}">
 *            <fieldMapping table="blacklist">
 *               <{field name}>{field value}</{field field}>
 *            </fieldMapping>
 *        </blacklist>
 *    </eurephia>
 * @endcode
 * For listing and delete mode it be several field tags to limit the search even more.
 * For add mode only username, IP address or certificate digest can be given.
 *
 * @return Returns a valid XML document on success, otherwise NULL or an XML document
 *         with an error message.
 * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
 */
xmlDoc *(*eDBadminBlacklist) (eurephiaCTX *ctx, xmlDoc *qryxml);
#endif /* HAVE_LIBXML2 */

#endif /* !DRIVER_MODE */

#endif /* !EUREPHIADB_DRIVER_H_ */