ITS#9364 Add docs for crypto modules

diff --git a/libraries/liblmdb/lmdb.h b/libraries/liblmdb/lmdb.h
index 2fba3a5a8d3d91d74c3e4a7c4d51c3a7850a7bac..128031ac346bbb56c9961260ada2c1adf83e7cde 100644 (file)
--- 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 fdf266368dae374595f2429f00323d76d9486bcd..762d3fbf57c24557a39b4ddd690424b733dc9d50 100644 (file)
--- 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 ff83fd98b5c29e7cee5e2fdf47761ab91e57d873..877988bba7f817db8f189ec4192b578c2597d7cc 100644 (file)
--- 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 bde27733002346eab533f47e66f3e2e20ea079ad..cb0fab12f749a07cca78d9f07b19822c43ba94c3 100644 (file)
--- 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 1b3d4dee83ee53793768d56480c07c9bcff815d4..bcedd006cef4d72e92bd065dace90643fefb8728 100644 (file)
--- 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 7dd8aa1f425aef1d61b2c94250ee1167f6b3ae98..dbcbd9b189afef805eebaf10b585bbfff9f06ac6 100644 (file)
--- 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 a618450eff67bb1fb77e8bbcbc111d73c544e478..2adceb825c5d446accb46433288140493eb8dc5e 100644 (file)
--- 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 1bb1bcb3424535d07f8a05ed4803422b869ea9f1..49afb14198fe7d517095098903122e347b4f794b 100644 (file)
--- 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 b69c935d790a1de98b71f3e42c0a6cb420a615d2..e0e594f8353426950173d56b9dcc4bba02b5abcb 100644 (file)
--- 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;
 }