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 2fba3a5..128031a 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 fdf2663..762d3fb 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 ff83fd9..877988b 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 bde2773..cb0fab1 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 1b3d4de..bcedd00 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 7dd8aa1..dbcbd9b 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 a618450..2adceb8 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 1bb1bcb..49afb14 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 b69c935..e0e594f 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; }