ITS#9364 Add docs for crypto modules

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

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.

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

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

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;
 }

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

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

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;
 }

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;
 }