diff options
| -rw-r--r-- | common/eurephia_xml.c | 16 | ||||
| -rw-r--r-- | database/eurephiadb_driver.h | 82 | ||||
| -rw-r--r-- | utils/benchmark.c | 69 | ||||
| -rw-r--r-- | utils/eurephia_init.c | 28 |
4 files changed, 114 insertions, 81 deletions
diff --git a/common/eurephia_xml.c b/common/eurephia_xml.c index 80f2ccd..91eacf4 100644 --- a/common/eurephia_xml.c +++ b/common/eurephia_xml.c @@ -178,8 +178,19 @@ xmlNode *eurephiaXML_getRoot(eurephiaCTX *ctx, xmlDoc *doc, const char *nodeset, * @param info_n xmlNode with more details about the result * @param fmt stdarg format string * - * @return Returns a valid eurephia XML document as a properly formatted result message. + * @return Returns a valid eurephia ResultMsg XML document as a properly formatted result message. * On failure, NULL is returned + * + * Skeleton for a eurephia ResultMsg XML document + * @code + * <eurephia format="1"> + * <Result status="{Result|Error}"> + * <Message>{String containing a descriptive message}</Message> + * [<Details>{xmlNode including children with more detailed information}</Details>] + * </Result> + * </eurephia> + * @endcode + * The status attribute is set to "Result" on success, and "Error" in error situations */ xmlDoc *eurephiaXML_ResultMsg(eurephiaCTX *ctx, exmlResultType type, xmlNode *info_n, const char *fmt, ... ) { va_list ap; @@ -228,13 +239,14 @@ xmlNode *eurephiaXML_getRoot(eurephiaCTX *ctx, xmlDoc *doc, const char *nodeset, * Parses an eurephia Result XML document * * @param ctx eurephiaCTX - * @param resxml The result XML document + * @param resxml The result XML document, as produced by eurephiaXML_ResultMsg() * * @return Returns a pointer to an eurephiaRESULT structure containing the results. * On failure NULL is returned. This structure can be freed with free_nullsafe(). * * @remark If the result XML document is freed, the information in eurephiaRESULT will be invalidated * Immediately. However, the eurephiaRESULT pointer must still be freed. + * @see eurephiaXML_ResultMsg() */ eurephiaRESULT *eurephiaXML_ParseResultMsg(eurephiaCTX *ctx, xmlDoc *resxml) { eurephiaRESULT *res = NULL; diff --git a/database/eurephiadb_driver.h b/database/eurephiadb_driver.h index d90b2f5..e9c757c 100644 --- a/database/eurephiadb_driver.h +++ b/database/eurephiadb_driver.h @@ -565,17 +565,16 @@ int (*eDBadminDeleteUser) (eurephiaCTX *ctx, const int uid, xmlDoc *userinfo); /** - * Get information about a specific certificate + * Function for listing, registering new or deleting certificates in the database * * @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 + * @param qryxml XML document with the certificate information to be deleted * - * Skeleton of an XML search document + * Skeleton of an XML document used for eDBadminCertificate() * @code * <eurephia format="1"> - * <certificate_info> + * <certificates mode="{list|register|delete}"> * <fieldMapping table="certificates"> * <{field name}>{field value}</{field name}> * ... @@ -584,11 +583,15 @@ int (*eDBadminDeleteUser) (eurephiaCTX *ctx, const int uid, xmlDoc *userinfo); * </certificate_info> * </eurephia> * @endcode + * Valid field names are: depth, digest, common_name, org, email and certid. + * For list and delete mode, all field names can be used to narrow the search query. + * In register mode all fields are required, except certid which must not be given. * - * @return Returns an XML document containing the requested certificate information on success, otherwise - * NULL is returned. + * @return When mode is "list", it will return an XML document with all found certificates, otherwise NULL. + * If mode is "register" or "delete" an eurephia ResultMsg XML document will be returned with + * the result of the operation, or NULL on fatal errors. * - * Skeleton of a result document + * Skeleton of a result document from a "list" mode query. * @code * <eurephia format="1"> * <certificates certificates={number of found certs}"> @@ -602,68 +605,9 @@ int (*eDBadminDeleteUser) (eurephiaCTX *ctx, const int uid, xmlDoc *userinfo); * </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() + * @see eurephiaXML_CreateDoc(), eurephiaXML_ParseResultMsg(), eurephiaXML_getRoot() */ -// 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); - - -xmlDoc *(*eDBadminCertificate) (eurephiaCTX *ctx, xmlDoc *certxml); +xmlDoc *(*eDBadminCertificate) (eurephiaCTX *ctx, xmlDoc *qryxml); /** diff --git a/utils/benchmark.c b/utils/benchmark.c index 6b01fb7..77cd759 100644 --- a/utils/benchmark.c +++ b/utils/benchmark.c @@ -19,6 +19,16 @@ * */ +/** + * @file benchmark.c + * @author David Sommerseth <dazo@users.sourceforge.net> + * @date 2009-03-22 + * + * @brief Benchmarking utility to test how quickly a computer can calculate SHA512 hashes + * + */ + + #include <stdio.h> #include <stdlib.h> #include <string.h> @@ -28,16 +38,30 @@ #include <eurephia_nullsafe.h> #include <eurephia_context.h> -#define ROUNDS_MIN 1000 -#define ROUNDS_MAX 999999999 +#define ROUNDS_MIN 1000 /**< Define minimum acceptable rounds for the hashing */ +#define ROUNDS_MAX 999999999 /**< Define maximum allowed rounds for the hashing */ -// Internal functions found in passwd.c +/** + * @copydoc pack_saltinf() + */ int pack_saltinfo(char *buf, int buflen, int rounds, int saltlen, const char *pwd); + +/** + * @copydoc sha512_crypt_r() + */ inline char *sha512_crypt_r(const char *key, const char *salt, size_t maxrounds_cfg, char *buffer, int buflen); + +/** + * @copydoc gen_randsaltstr() + */ int gen_randsaltstr(eurephiaCTX *ctx, char *saltstr, int len); -// A function which calculates a hash based on a standard password, used -// for measuring the time used for hash calculation +/** + * Internal function which calculates a hash based on a standard password. This function is used + * for measuring the time used for hash calculation + * + * @param rounds Number of rounds the hashing should use + */ void benchmark_hashing(int rounds) { char *buffer = NULL; char *pwdhash = NULL; @@ -72,6 +96,15 @@ void benchmark_hashing(int rounds) { } +/** + * Internal function, calculating a time delta between two struct timeval. + * + * @param result Result pointer to where the result will be put + * @param x Value 1 with time information + * @param y Value 2 with time information + * + * @return Returns 1 if the X value is lower than the Y value + */ int timeval_subtract (result, x, y) struct timeval *result, *x, *y; { @@ -96,6 +129,14 @@ int timeval_subtract (result, x, y) return x->tv_sec < y->tv_sec; } + +/** + * Internal function. The real benchmark function. + * + * @param rounds Number of rounds to do when hashing a password + * + * @return Returns a struct timeval containing the time spent calculating the hash + */ struct timeval *do_benchmark(int rounds) { struct timeval start, end, *timediff = NULL; @@ -110,10 +151,20 @@ struct timeval *do_benchmark(int rounds) { return timediff; } -// This function will try to find the best minium and maximum rounds for -// the SHA512 hashing. The values are returned in the min and max variables -// and the thr_min and thr_max defines the minimum and maximum thresholds in -// milliseconds the hashing algorithm should use. +/** + * This function will try to find the best minium and maximum rounds for + * the SHA512 hashing. The values are returned in the min and max variables + * and the thr_min and thr_max defines the minimum and maximum thresholds in + * milliseconds the hashing algorithm should use. + * + * @param min Return pointer for the minimum hashing rounds value + * @param max Return pointer for the maximum hashing rounds value + * @param thr_min Allow the calculation of hashes to last for thr_min ms. + * @param thr_max Do not allow the hash calculation to exceed thr_max ms. + * + * @return Returns 1 if a good suggestion for min and max hashing rounds was found. + * Otherwise 0 is returned. + */ int benchmark(int *min, int *max, int thr_min, int thr_max) { int i = 0, success = 0; struct timeval *time = NULL, min_time, max_time ; diff --git a/utils/eurephia_init.c b/utils/eurephia_init.c index 7b72eb5..e0f998d 100644 --- a/utils/eurephia_init.c +++ b/utils/eurephia_init.c @@ -49,13 +49,24 @@ #include <eurephia_values.h> #include <eurephia_xml.h> -#define MODULE "eurephia_init" +#define MODULE "eurephia_init" /**< Set the module name to eurephia_init */ #include <client_context.h> #include <argparser.h> #include <get_console_input.h> +/** + * @copydoc benchmark() + */ int benchmark(int *min, int *max, int thr_min, int thr_max); + +/** + * Prints program version information to stdout + * + * @param fprg String containing full path to this binary (argv[0]) + * + * @return Returns the basename value of the binary + */ char *print_version(char *fprg) { char *prg = basename(fprg); @@ -65,6 +76,12 @@ char *print_version(char *fprg) { return prg; } + +/** + * Prints a help screen for all arguments eurephia_init can process + * + * @param fprg String containing full path to this binary (argv[0]) + */ void print_help(char *fprg) { print_version(fprg); @@ -530,6 +547,15 @@ int setup_iptables(eurephiaCTX *ctx) { } #endif + +/** + * Main function of eurephia_init + * + * @param argc + * @param argv + * + * @return Returns 0 on success, otherwise a positive integer on failure. + */ int main(int argc, char **argv) { // Default hash calculation thresholds for benchmarking int hash_thr_min = 95; // 95ms |