From 8e8371d125c9f4bccb208e2d80ee286d89c1e82e Mon Sep 17 00:00:00 2001 From: Howard Chu Date: Mon, 12 Oct 2020 22:28:27 +0100 Subject: [PATCH] ITS#9364 Add docs for crypto modules --- libraries/liblmdb/lmdb.h | 20 ++++++++++++++++---- libraries/liblmdb/mdb_copy.1 | 13 +++++++++++++ libraries/liblmdb/mdb_drop.1 | 13 +++++++++++++ libraries/liblmdb/mdb_dump.1 | 13 +++++++++++++ libraries/liblmdb/mdb_dump.c | 2 ++ libraries/liblmdb/mdb_load.1 | 13 +++++++++++++ libraries/liblmdb/mdb_stat.1 | 13 +++++++++++++ libraries/liblmdb/mdb_stat.c | 2 ++ libraries/liblmdb/mtest_enc2.c | 26 +++++--------------------- 9 files changed, 90 insertions(+), 25 deletions(-) diff --git a/libraries/liblmdb/lmdb.h b/libraries/liblmdb/lmdb.h index 2fba3a5a8d..128031ac34 100644 --- a/libraries/liblmdb/lmdb.h +++ b/libraries/liblmdb/lmdb.h @@ -1739,16 +1739,27 @@ int mdb_reader_check(MDB_env *env, int *dead); */ typedef int (MDB_str2key_func)(const char *passwd, MDB_val *key); + /** @brief A structure for dynamically loaded crypto modules. + * + * This is the information that the command line tools expect + * in order to operate on encrypted or checksummed environments. + */ typedef struct MDB_crypto_funcs { MDB_str2key_func *mcf_str2key; MDB_enc_func *mcf_encfunc; MDB_sum_func *mcf_sumfunc; - int mcf_keysize; - int mcf_esumsize; - int mcf_sumsize; + int mcf_keysize; /**< The size of an encryption key, in bytes */ + int mcf_esumsize; /**< The size of the MAC, for authenticated encryption */ + int mcf_sumsize; /**< The size of the checksum, for plain checksums */ } MDB_crypto_funcs; -typedef MDB_crypto_funcs *(MDB_crypto_hooks)(); + /** @brief The function that returns the #MDB_crypto_funcs structure. + * + * The command line tools expect this function to be named "MDB_crypto". + * It must be exported by the dynamic module so that the tools can use it. + * @return A pointer to a #MDB_crypto_funcs structure. + */ +typedef MDB_crypto_funcs *(MDB_crypto_hooks)(void); #ifdef __cplusplus } @@ -1756,6 +1767,7 @@ typedef MDB_crypto_funcs *(MDB_crypto_hooks)(); /** @page tools LMDB Command Line Tools The following describes the command line tools that are available for LMDB. \li \ref mdb_copy_1 + \li \ref mdb_drop_1 \li \ref mdb_dump_1 \li \ref mdb_load_1 \li \ref mdb_stat_1 diff --git a/libraries/liblmdb/mdb_copy.1 b/libraries/liblmdb/mdb_copy.1 index fdf266368d..762d3fbf57 100644 --- a/libraries/liblmdb/mdb_copy.1 +++ b/libraries/liblmdb/mdb_copy.1 @@ -13,6 +13,10 @@ mdb_copy \- LMDB environment copy tool .BR \-n ] [\c .BR \-v ] +[\c +.BI \-m \ module +[\c +.BI \-w \ password\fR]] .B srcpath [\c .BR dstpath ] @@ -46,6 +50,15 @@ Open LDMB environment(s) which do not use subdirectories. .BR \-v Use the previous environment state instead of the latest state. This may be useful if the latest state has been corrupted. +.TP +.BI \-m \ module +Load the specified dynamic module to utilize cryptographic functions. +This is required to operate on environments that have been configured +with page-level checksums or encryption. +.TP +.BI \-w \ password +Specify the password for an encrypted environment. This is only +used if a cryptography module has been loaded. .SH DIAGNOSTICS Exit status is zero if no errors occur. diff --git a/libraries/liblmdb/mdb_drop.1 b/libraries/liblmdb/mdb_drop.1 index ff83fd98b5..877988bba7 100644 --- a/libraries/liblmdb/mdb_drop.1 +++ b/libraries/liblmdb/mdb_drop.1 @@ -12,6 +12,10 @@ mdb_drop \- LMDB database delete tool [\c .BR \-d ] [\c +.BI \-m \ module +[\c +.BI \-w \ password\fR]] +[\c .BI \-s \ subdb\fR] .BR \ envpath .SH DESCRIPTION @@ -30,6 +34,15 @@ Operate on an LMDB database which does not use subdirectories. .BR \-d Delete the specified database, don't just empty it. .TP +.BI \-m \ module +Load the specified dynamic module to utilize cryptographic functions. +This is required to operate on environments that have been configured +with page-level checksums or encryption. +.TP +.BI \-w \ password +Specify the password for an encrypted environment. This is only +used if a cryptography module has been loaded. +.TP .BR \-s \ subdb Operate on a specific subdatabase. If no database is specified, only the main database is dropped. .SH DIAGNOSTICS diff --git a/libraries/liblmdb/mdb_dump.1 b/libraries/liblmdb/mdb_dump.1 index bde2773300..cb0fab12f7 100644 --- a/libraries/liblmdb/mdb_dump.1 +++ b/libraries/liblmdb/mdb_dump.1 @@ -18,6 +18,10 @@ mdb_dump \- LMDB environment export tool [\c .BR \-p ] [\c +.BI \-m \ module +[\c +.BI \-w \ password\fR]] +[\c .BR \-a \ | .BI \-s \ subdb\fR] .BR \ envpath @@ -57,6 +61,15 @@ Note: different systems may have different notions about what characters are considered printing characters, and databases dumped in this manner may be less portable to external systems. .TP +.BI \-m \ module +Load the specified dynamic module to utilize cryptographic functions. +This is required to operate on environments that have been configured +with page-level checksums or encryption. +.TP +.BI \-w \ password +Specify the password for an encrypted environment. This is only +used if a cryptography module has been loaded. +.TP .BR \-a Dump all of the subdatabases in the environment. .TP diff --git a/libraries/liblmdb/mdb_dump.c b/libraries/liblmdb/mdb_dump.c index 1b3d4dee83..bcedd006ce 100644 --- a/libraries/liblmdb/mdb_dump.c +++ b/libraries/liblmdb/mdb_dump.c @@ -326,6 +326,8 @@ txn_abort: mdb_txn_abort(txn); env_close: mdb_env_close(env); + if (mlm) + mlm_unload(mlm); return rc ? EXIT_FAILURE : EXIT_SUCCESS; } diff --git a/libraries/liblmdb/mdb_load.1 b/libraries/liblmdb/mdb_load.1 index 7dd8aa1f42..dbcbd9b189 100644 --- a/libraries/liblmdb/mdb_load.1 +++ b/libraries/liblmdb/mdb_load.1 @@ -12,6 +12,10 @@ mdb_load \- LMDB environment import tool [\c .BR \-n ] [\c +.BI \-m \ module +[\c +.BI \-w \ password\fR]] +[\c .BI \-s \ subdb\fR] [\c .BR \-N ] @@ -50,6 +54,15 @@ Read from the specified file instead of from the standard input. .BR \-n Load an LMDB database which does not use subdirectories. .TP +.BI \-m \ module +Load the specified dynamic module to utilize cryptographic functions. +This is required to operate on environments that have been configured +with page-level checksums or encryption. +.TP +.BI \-w \ password +Specify the password for an encrypted environment. This is only +used if a cryptography module has been loaded. +.TP .BR \-s \ subdb Load a specific subdatabase. If no database is specified, data is loaded into the main database. .TP diff --git a/libraries/liblmdb/mdb_stat.1 b/libraries/liblmdb/mdb_stat.1 index a618450eff..2adceb825c 100644 --- a/libraries/liblmdb/mdb_stat.1 +++ b/libraries/liblmdb/mdb_stat.1 @@ -16,6 +16,10 @@ mdb_stat \- LMDB environment status tool [\c .BR \-v ] [\c +.BI \-m \ module +[\c +.BI \-w \ password\fR]] +[\c .BR \-r [ r ]] [\c .BR \-a \ | @@ -45,6 +49,15 @@ Display the status of an LMDB database which does not use subdirectories. Use the previous environment state instead of the latest state. This may be useful if the latest state has been corrupted. .TP +.BI \-m \ module +Load the specified dynamic module to utilize cryptographic functions. +This is required to operate on environments that have been configured +with page-level checksums or encryption. +.TP +.BI \-w \ password +Specify the password for an encrypted environment. This is only +used if a cryptography module has been loaded. +.TP .BR \-r Display information about the environment reader table. Shows the process ID, thread ID, and transaction ID for each active diff --git a/libraries/liblmdb/mdb_stat.c b/libraries/liblmdb/mdb_stat.c index 1bb1bcb342..49afb14198 100644 --- a/libraries/liblmdb/mdb_stat.c +++ b/libraries/liblmdb/mdb_stat.c @@ -269,6 +269,8 @@ txn_abort: mdb_txn_abort(txn); env_close: mdb_env_close(env); + if (mlm) + mlm_unload(mlm); return rc ? EXIT_FAILURE : EXIT_SUCCESS; } diff --git a/libraries/liblmdb/mtest_enc2.c b/libraries/liblmdb/mtest_enc2.c index b69c935d79..e0e594f835 100644 --- a/libraries/liblmdb/mtest_enc2.c +++ b/libraries/liblmdb/mtest_enc2.c @@ -34,13 +34,11 @@ int main(int argc,char * argv[]) MDB_stat mst; MDB_cursor *cursor, *cur2; MDB_cursor_op op; - MDB_val enckey; int count; int *values; char sval[32] = ""; char password[] = "This is my passphrase for now..."; - char *ekey; - void *lm; + void *mlm; char *errmsg; srand(time(NULL)); @@ -52,28 +50,14 @@ int main(int argc,char * argv[]) values[i] = rand()%1024; } - lm = lm_load("./crypto.lm", NULL, &cf, &errmsg); - if (!lm) { + E(mdb_env_create(&env)); + mlm = mlm_setup(env, "./crypto.lm", password, &errmsg); + if (!mlm) { fprintf(stderr,"Failed to load crypto module: %s\n", errmsg); exit(1); } - - E(mdb_env_create(&env)); E(mdb_env_set_maxreaders(env, 1)); E(mdb_env_set_mapsize(env, 10485760)); - if (cf->mcf_sumfunc) { - E(mdb_env_set_checksum(env, cf->mcf_sumfunc, cf->mcf_sumsize)); - } - if (cf->mcf_encfunc) { - ekey = malloc(cf->mcf_keysize); - enckey.mv_data = ekey; - enckey.mv_size = cf->mcf_keysize; - if (cf->mcf_str2key) - cf->mcf_str2key(password, &enckey); - else - strncpy(ekey, password, cf->mcf_keysize); - E(mdb_env_set_encrypt(env, cf->mcf_encfunc, &enckey, cf->mcf_esumsize)); - } E(mdb_env_open(env, "./testdb", 0 /*|MDB_NOSYNC*/, 0664)); E(mdb_txn_begin(env, NULL, 0, &txn)); @@ -199,7 +183,7 @@ int main(int argc,char * argv[]) mdb_dbi_close(env, dbi); mdb_env_close(env); - lm_unload(lm); + mlm_unload(mlm); return 0; } -- 2.47.2