595af1
From 71dbb3a1a96a012683125a22e9bf263efb97df4d Mon Sep 17 00:00:00 2001
595af1
From: Evan Hunt <each@isc.org>
595af1
Date: Thu, 28 Sep 2017 10:09:22 -0700
595af1
Subject: [PATCH] [master] completed and corrected the crypto-random change
595af1
595af1
4724.	[func]		By default, BIND now uses the random number
595af1
			functions provided by the crypto library (i.e.,
595af1
			OpenSSL or a PKCS#11 provider) as a source of
595af1
			randomness rather than /dev/random.  This is
595af1
			suitable for virtual machine environments
595af1
			which have limited entropy pools and lack
595af1
			hardware random number generators.
595af1
595af1
			This can be overridden by specifying another
595af1
			entropy source via the "random-device" option
595af1
			in named.conf, or via the -r command line option;
595af1
			however, for functions requiring full cryptographic
595af1
			strength, such as DNSSEC key generation, this
595af1
			cannot be overridden. In particular, the -r
595af1
			command line option no longer has any effect on
595af1
			dnssec-keygen.
595af1
595af1
			This can be disabled by building with
595af1
			"configure --disable-crypto-rand".
595af1
			[RT #31459] [RT #46047]
595af1
---
595af1
 bin/confgen/keygen.c                     | 12 +++----
595af1
 bin/dnssec/dnssec-keygen.docbook         | 24 +++++++++-----
595af1
 bin/dnssec/dnssectool.c                  | 12 +++----
595af1
 bin/named/client.c                       |  3 +-
595af1
 bin/named/config.c                       |  4 ++-
595af1
 bin/named/controlconf.c                  | 19 +++++++----
595af1
 bin/named/include/named/server.h         |  2 ++
595af1
 bin/named/interfacemgr.c                 |  1 +
595af1
 bin/named/query.c                        |  1 +
595af1
 bin/named/server.c                       | 52 ++++++++++++++++++------------
595af1
 bin/nsupdate/nsupdate.c                  |  4 +--
595af1
 bin/tests/system/pipelined/pipequeries.c |  4 +--
595af1
 bin/tests/system/tkey/keycreate.c        |  4 +--
595af1
 bin/tests/system/tkey/keydelete.c        |  4 +--
595af1
 doc/arm/Bv9ARM-book.xml                  | 55 ++++++++++++++++++++++----------
595af1
 doc/arm/notes.xml                        | 26 +++++++++++++++
595af1
 lib/dns/dst_api.c                        |  7 ++--
595af1
 lib/dns/include/dst/dst.h                | 14 ++++++--
595af1
 lib/dns/openssl_link.c                   |  3 +-
595af1
 lib/isc/include/isc/entropy.h            | 50 +++++++++++++++++++++--------
595af1
 lib/isc/include/isc/random.h             | 28 ++++++++++------
595af1
 lib/isccfg/namedconf.c                   |  2 +-
595af1
 22 files changed, 222 insertions(+), 109 deletions(-)
595af1
595af1
diff --git a/bin/confgen/keygen.c b/bin/confgen/keygen.c
595af1
index fa439cc158..a7ad417a18 100644
595af1
--- a/bin/confgen/keygen.c
595af1
+++ b/bin/confgen/keygen.c
595af1
@@ -161,17 +161,15 @@ generate_key(isc_mem_t *mctx, const char *randomfile, dns_secalg_t alg,
595af1
 
595af1
 	DO("create entropy context", isc_entropy_create(mctx, &ectx));
595af1
 
595af1
-	if (randomfile != NULL && strcmp(randomfile, "keyboard") == 0) {
595af1
-		randomfile = NULL;
595af1
-		open_keyboard = ISC_ENTROPY_KEYBOARDYES;
595af1
-	}
595af1
 #ifdef ISC_PLATFORM_CRYPTORANDOM
595af1
-	if (randomfile != NULL &&
595af1
-	    strcmp(randomfile, ISC_PLATFORM_CRYPTORANDOM) == 0) {
595af1
-		randomfile = NULL;
595af1
+	if (randomfile == NULL) {
595af1
 		isc_entropy_usehook(ectx, ISC_TRUE);
595af1
 	}
595af1
 #endif
595af1
+	if (randomfile != NULL && strcmp(randomfile, "keyboard") == 0) {
595af1
+		randomfile = NULL;
595af1
+		open_keyboard = ISC_ENTROPY_KEYBOARDYES;
595af1
+	}
595af1
 	DO("start entropy source", isc_entropy_usebestsource(ectx,
595af1
 							     &entropy_source,
595af1
 							     randomfile,
595af1
diff --git a/bin/dnssec/dnssec-keygen.docbook b/bin/dnssec/dnssec-keygen.docbook
595af1
index 96dfef64b4..1c84b06126 100644
595af1
--- a/bin/dnssec/dnssec-keygen.docbook
595af1
+++ b/bin/dnssec/dnssec-keygen.docbook
595af1
@@ -349,15 +349,23 @@
595af1
 	<term>-r <replaceable class="parameter">randomdev</replaceable></term>
595af1
 	<listitem>
595af1
 	  <para>
595af1
-	    Specifies the source of randomness.  If the operating
595af1
-	    system does not provide a <filename>/dev/random</filename>
595af1
-	    or equivalent device, the default source of randomness
595af1
-	    is keyboard input.  <filename>randomdev</filename>
595af1
-	    specifies
595af1
+	    Specifies a source of randomness.  Normally, when generating
595af1
+	    DNSSEC keys, this option has no effect; the random number
595af1
+	    generation function provided by the cryptographic library will
595af1
+	    be used.
595af1
+	  </para>
595af1
+	  <para>
595af1
+	    If that behavior is disabled at compile time, however,
595af1
+	    the specified file will be used as entropy source
595af1
+	    for key generation.  <filename>randomdev</filename> is
595af1
 	    the name of a character device or file containing random
595af1
-	    data to be used instead of the default.  The special value
595af1
-	    <filename>keyboard</filename> indicates that keyboard
595af1
-	    input should be used.
595af1
+	    data to be used.  The special value <filename>keyboard</filename>
595af1
+	    indicates that keyboard input should be used.
595af1
+	  </para>
595af1
+	  <para>
595af1
+	    The default is <filename>/dev/random</filename> if the
595af1
+	    operating system provides it or an equivalent device;
595af1
+	    if not, the default source of randomness is keyboard input.
595af1
 	  </para>
595af1
 	</listitem>
595af1
       </varlistentry>
595af1
diff --git a/bin/dnssec/dnssectool.c b/bin/dnssec/dnssectool.c
595af1
index 4ea9eafa44..5dd9475dd3 100644
595af1
--- a/bin/dnssec/dnssectool.c
595af1
+++ b/bin/dnssec/dnssectool.c
595af1
@@ -239,18 +239,16 @@ setup_entropy(isc_mem_t *mctx, const char *randomfile, isc_entropy_t **ectx) {
595af1
 		ISC_LIST_INIT(sources);
595af1
 	}
595af1
 
595af1
+#ifdef ISC_PLATFORM_CRYPTORANDOM
595af1
+	if (randomfile == NULL) {
595af1
+		isc_entropy_usehook(*ectx, ISC_TRUE);
595af1
+	}
595af1
+#endif
595af1
 	if (randomfile != NULL && strcmp(randomfile, "keyboard") == 0) {
595af1
 		usekeyboard = ISC_ENTROPY_KEYBOARDYES;
595af1
 		randomfile = NULL;
595af1
 	}
595af1
 
595af1
-#ifdef ISC_PLATFORM_CRYPTORANDOM
595af1
-	if (randomfile != NULL &&
595af1
-	    strcmp(randomfile, ISC_PLATFORM_CRYPTORANDOM) == 0) {
595af1
-		randomfile = NULL;
595af1
-		isc_entropy_usehook(*ectx, ISC_TRUE);
595af1
-	}
595af1
-#endif
595af1
 	result = isc_entropy_usebestsource(*ectx, &source, randomfile,
595af1
 					   usekeyboard);
595af1
 
595af1
diff --git a/bin/named/client.c b/bin/named/client.c
595af1
index b9ebc93094..20e5f395d4 100644
595af1
--- a/bin/named/client.c
595af1
+++ b/bin/named/client.c
595af1
@@ -1605,7 +1605,8 @@ ns_client_addopt(ns_client_t *client, dns_message_t *message,
595af1
 
595af1
 		isc_buffer_init(&buf, cookie, sizeof(cookie));
595af1
 		isc_stdtime_get(&now;;
595af1
-		isc_random_get(&nonce);
595af1
+		nonce = ((isc_rng_random(ns_g_server->rngctx) << 16) |
595af1
+			 isc_rng_random(ns_g_server->rngctx));
595af1
 
595af1
 		compute_cookie(client, now, nonce, ns_g_server->secret, &buf;;
595af1
 
595af1
diff --git a/bin/named/config.c b/bin/named/config.c
595af1
index c50f759ddd..c1e72ef996 100644
595af1
--- a/bin/named/config.c
595af1
+++ b/bin/named/config.c
595af1
@@ -92,7 +92,9 @@ options {\n\
595af1
 #	pid-file \"" NS_LOCALSTATEDIR "/run/named/named.pid\"; /* or /lwresd.pid */\n\
595af1
 	port 53;\n\
595af1
 	prefetch 2 9;\n"
595af1
-#ifdef PATH_RANDOMDEV
595af1
+#if defined(ISC_PLATFORM_CRYPTORANDOM)
595af1
+"	random-device none;\n"
595af1
+#elif defined(PATH_RANDOMDEV)
595af1
 "	random-device \"" PATH_RANDOMDEV "\";\n"
595af1
 #endif
595af1
 "	recursing-file \"named.recursing\";\n\
595af1
diff --git a/bin/named/controlconf.c b/bin/named/controlconf.c
595af1
index 237e8dc31d..b905475890 100644
595af1
--- a/bin/named/controlconf.c
595af1
+++ b/bin/named/controlconf.c
595af1
@@ -322,9 +322,10 @@ log_invalid(isccc_ccmsg_t *ccmsg, isc_result_t result) {
595af1
 
595af1
 static void
595af1
 control_recvmessage(isc_task_t *task, isc_event_t *event) {
595af1
-	controlconnection_t *conn;
595af1
-	controllistener_t *listener;
595af1
-	controlkey_t *key;
595af1
+	controlconnection_t *conn = NULL;
595af1
+	controllistener_t *listener = NULL;
595af1
+	ns_server_t *server = NULL;
595af1
+	controlkey_t *key = NULL;
595af1
 	isccc_sexpr_t *request = NULL;
595af1
 	isccc_sexpr_t *response = NULL;
595af1
 	isc_uint32_t algorithm;
595af1
@@ -335,16 +336,17 @@ control_recvmessage(isc_task_t *task, isc_event_t *event) {
595af1
 	isc_buffer_t *text;
595af1
 	isc_result_t result;
595af1
 	isc_result_t eresult;
595af1
-	isccc_sexpr_t *_ctrl;
595af1
+	isccc_sexpr_t *_ctrl = NULL;
595af1
 	isccc_time_t sent;
595af1
 	isccc_time_t exp;
595af1
 	isc_uint32_t nonce;
595af1
-	isccc_sexpr_t *data;
595af1
+	isccc_sexpr_t *data = NULL;
595af1
 
595af1
 	REQUIRE(event->ev_type == ISCCC_EVENT_CCMSG);
595af1
 
595af1
 	conn = event->ev_arg;
595af1
 	listener = conn->listener;
595af1
+	server = listener->controls->server;
595af1
 	algorithm = DST_ALG_UNKNOWN;
595af1
 	secret.rstart = NULL;
595af1
 	text = NULL;
595af1
@@ -455,8 +457,11 @@ control_recvmessage(isc_task_t *task, isc_event_t *event) {
595af1
 	 * Establish nonce.
595af1
 	 */
595af1
 	if (conn->nonce == 0) {
595af1
-		while (conn->nonce == 0)
595af1
-			isc_random_get(&conn->nonce);
595af1
+		while (conn->nonce == 0) {
595af1
+			isc_uint16_t r1 = isc_rng_random(server->rngctx);
595af1
+			isc_uint16_t r2 = isc_rng_random(server->rngctx);
595af1
+			conn->nonce = (r1 << 16) | r2;
595af1
+		}
595af1
 		eresult = ISC_R_SUCCESS;
595af1
 	} else
595af1
 		eresult = ns_control_docommand(request, listener->readonly, &text);
595af1
diff --git a/bin/named/include/named/server.h b/bin/named/include/named/server.h
595af1
index d8179a60a0..e03d24d85d 100644
595af1
--- a/bin/named/include/named/server.h
595af1
+++ b/bin/named/include/named/server.h
595af1
@@ -17,6 +17,7 @@
595af1
 #include <isc/log.h>
595af1
 #include <isc/magic.h>
595af1
 #include <isc/quota.h>
595af1
+#include <isc/random.h>
595af1
 #include <isc/sockaddr.h>
595af1
 #include <isc/types.h>
595af1
 #include <isc/xml.h>
595af1
@@ -131,6 +132,7 @@ struct ns_server {
595af1
 	char *			lockfile;
595af1
 
595af1
 	isc_uint16_t		transfer_tcp_message_size;
595af1
+	isc_rng_t *		rngctx;
595af1
 };
595af1
 
595af1
 struct ns_altsecret {
595af1
diff --git a/bin/named/interfacemgr.c b/bin/named/interfacemgr.c
595af1
index d8c7188186..50f924eadb 100644
595af1
--- a/bin/named/interfacemgr.c
595af1
+++ b/bin/named/interfacemgr.c
595af1
@@ -15,6 +15,7 @@
595af1
 
595af1
 #include <isc/interfaceiter.h>
595af1
 #include <isc/os.h>
595af1
+#include <isc/random.h>
595af1
 #include <isc/string.h>
595af1
 #include <isc/task.h>
595af1
 #include <isc/util.h>
595af1
diff --git a/bin/named/query.c b/bin/named/query.c
595af1
index accbf3b24d..d89622d835 100644
595af1
--- a/bin/named/query.c
595af1
+++ b/bin/named/query.c
595af1
@@ -18,6 +18,7 @@
595af1
 #include <isc/hex.h>
595af1
 #include <isc/mem.h>
595af1
 #include <isc/print.h>
595af1
+#include <isc/random.h>
595af1
 #include <isc/rwlock.h>
595af1
 #include <isc/serial.h>
595af1
 #include <isc/stats.h>
595af1
diff --git a/bin/named/server.c b/bin/named/server.c
595af1
index ee5186c165..553e0f1ae6 100644
595af1
--- a/bin/named/server.c
595af1
+++ b/bin/named/server.c
595af1
@@ -8076,21 +8076,30 @@ load_configuration(const char *filename, ns_server_t *server,
595af1
 	 * Open the source of entropy.
595af1
 	 */
595af1
 	if (first_time) {
595af1
+		const char *randomdev = NULL;
595af1
+		int level = ISC_LOG_ERROR;
595af1
 		obj = NULL;
595af1
 		result = ns_config_get(maps, "random-device", &obj);
595af1
-		if (result != ISC_R_SUCCESS) {
595af1
-			isc_log_write(ns_g_lctx, NS_LOGCATEGORY_GENERAL,
595af1
-				      NS_LOGMODULE_SERVER, ISC_LOG_INFO,
595af1
-				      "no source of entropy found");
595af1
-		} else {
595af1
-			const char *randomdev = cfg_obj_asstring(obj);
595af1
+		if (result == ISC_R_SUCCESS) {
595af1
+			if (!cfg_obj_isvoid(obj)) {
595af1
+				level = ISC_LOG_INFO;
595af1
+				randomdev = cfg_obj_asstring(obj);
595af1
+			}
595af1
+		}
595af1
+		if (randomdev == NULL) {
595af1
 #ifdef ISC_PLATFORM_CRYPTORANDOM
595af1
-			if (strcmp(randomdev, ISC_PLATFORM_CRYPTORANDOM) == 0)
595af1
-				isc_entropy_usehook(ns_g_entropy, ISC_TRUE);
595af1
+			isc_entropy_usehook(ns_g_entropy, ISC_TRUE);
595af1
 #else
595af1
-			int level = ISC_LOG_ERROR;
595af1
-			result = isc_entropy_createfilesource(ns_g_entropy,
595af1
-							      randomdev);
595af1
+			if ((obj != NULL) && !cfg_obj_isvoid(obj))
595af1
+				level = ISC_LOG_INFO;
595af1
+			isc_log_write(named_g_lctx, NS_LOGCATEGORY_GENERAL,
595af1
+				      NS_LOGMODULE_SERVER, level,
595af1
+				      "no source of entropy found");
595af1
+			if ((obj == NULL) || cfg_obj_isvoid(obj)) {
595af1
+				CHECK(ISC_R_FAILURE);
595af1
+			}
595af1
+#endif
595af1
+		} else {
595af1
 #ifdef PATH_RANDOMDEV
595af1
 			if (ns_g_fallbackentropy != NULL) {
595af1
 				level = ISC_LOG_INFO;
595af1
@@ -8101,8 +8110,8 @@ load_configuration(const char *filename, ns_server_t *server,
595af1
 					      NS_LOGCATEGORY_GENERAL,
595af1
 					      NS_LOGMODULE_SERVER,
595af1
 					      level,
595af1
-					      "could not open entropy source "
595af1
-					      "%s: %s",
595af1
+					      "could not open "
595af1
+					      "entropy source %s: %s",
595af1
 					      randomdev,
595af1
 					      isc_result_totext(result));
595af1
 			}
595af1
@@ -8122,7 +8131,6 @@ load_configuration(const char *filename, ns_server_t *server,
595af1
 				}
595af1
 				isc_entropy_detach(&ns_g_fallbackentropy);
595af1
 			}
595af1
-#endif
595af1
 #endif
595af1
 		}
595af1
 	}
595af1
@@ -8911,6 +8919,8 @@ ns_server_create(isc_mem_t *mctx, ns_server_t **serverp) {
595af1
 	CHECKFATAL(dns_tkeyctx_create(ns_g_mctx, ns_g_entropy,
595af1
 				      &server->tkeyctx),
595af1
 		   "creating TKEY context");
595af1
+	CHECKFATAL(isc_rng_create(ns_g_mctx, ns_g_entropy, &server->rngctx),
595af1
+	           "creating random numbers context");
595af1
 
595af1
 	/*
595af1
 	 * Setup the server task, which is responsible for coordinating
595af1
@@ -9117,7 +9127,8 @@ ns_server_destroy(ns_server_t **serverp) {
595af1
 
595af1
 	if (server->zonemgr != NULL)
595af1
 		dns_zonemgr_detach(&server->zonemgr);
595af1
-
595af1
+	if (server->rngctx != NULL)
595af1
+		isc_rng_detach(&server->rngctx);
595af1
 	if (server->tkeyctx != NULL)
595af1
 		dns_tkeyctx_destroy(&server->tkeyctx);
595af1
 
595af1
@@ -13018,10 +13029,10 @@ newzone_cfgctx_destroy(void **cfgp) {
595af1
 
595af1
 static isc_result_t
595af1
 generate_salt(unsigned char *salt, size_t saltlen) {
595af1
-	int i, n;
595af1
+	size_t i, n;
595af1
 	union {
595af1
 		unsigned char rnd[256];
595af1
-		isc_uint32_t rnd32[64];
595af1
+		isc_uint16_t rnd16[128];
595af1
 	} rnd;
595af1
 	unsigned char text[512 + 1];
595af1
 	isc_region_t r;
595af1
@@ -13031,9 +13042,10 @@ generate_salt(unsigned char *salt, size_t saltlen) {
595af1
 	if (saltlen > 256U)
595af1
 		return (ISC_R_RANGE);
595af1
 
595af1
-	n = (int) (saltlen + sizeof(isc_uint32_t) - 1) / sizeof(isc_uint32_t);
595af1
-	for (i = 0; i < n; i++)
595af1
-		isc_random_get(&rnd.rnd32[i]);
595af1
+	n = (saltlen + sizeof(isc_uint16_t) - 1) / sizeof(isc_uint16_t);
595af1
+	for (i = 0; i < n; i++) {
595af1
+		rnd.rnd16[i] = isc_rng_random(ns_g_server->rngctx);
595af1
+	}
595af1
 
595af1
 	memmove(salt, rnd.rnd, saltlen);
595af1
 
595af1
diff --git a/bin/nsupdate/nsupdate.c b/bin/nsupdate/nsupdate.c
595af1
index 46c7acf4dc..a0d0278635 100644
595af1
--- a/bin/nsupdate/nsupdate.c
595af1
+++ b/bin/nsupdate/nsupdate.c
595af1
@@ -281,9 +281,7 @@ setup_entropy(isc_mem_t *mctx, const char *randomfile, isc_entropy_t **ectx) {
595af1
 	}
595af1
 
595af1
 #ifdef ISC_PLATFORM_CRYPTORANDOM
595af1
-	if (randomfile != NULL &&
595af1
-	    strcmp(randomfile, ISC_PLATFORM_CRYPTORANDOM) == 0) {
595af1
-		randomfile = NULL;
595af1
+	if (randomfile == NULL) {
595af1
 		isc_entropy_usehook(*ectx, ISC_TRUE);
595af1
 	}
595af1
 #endif
595af1
diff --git a/bin/tests/system/pipelined/pipequeries.c b/bin/tests/system/pipelined/pipequeries.c
595af1
index 810d99e267..d7d10e2e3c 100644
595af1
--- a/bin/tests/system/pipelined/pipequeries.c
595af1
+++ b/bin/tests/system/pipelined/pipequeries.c
595af1
@@ -279,9 +279,7 @@ main(int argc, char *argv[]) {
595af1
 	ectx = NULL;
595af1
 	RUNCHECK(isc_entropy_create(mctx, &ectx));
595af1
 #ifdef ISC_PLATFORM_CRYPTORANDOM
595af1
-	if (randomfile != NULL &&
595af1
-	    strcmp(randomfile, ISC_PLATFORM_CRYPTORANDOM) == 0) {
595af1
-		randomfile = NULL;
595af1
+	if (randomfile == NULL) {
595af1
 		isc_entropy_usehook(ectx, ISC_TRUE);
595af1
 	}
595af1
 #endif
595af1
diff --git a/bin/tests/system/tkey/keycreate.c b/bin/tests/system/tkey/keycreate.c
595af1
index 4f2f5b4cc5..0894db7066 100644
595af1
--- a/bin/tests/system/tkey/keycreate.c
595af1
+++ b/bin/tests/system/tkey/keycreate.c
595af1
@@ -255,9 +255,7 @@ main(int argc, char *argv[]) {
595af1
 	ectx = NULL;
595af1
 	RUNCHECK(isc_entropy_create(mctx, &ectx));
595af1
 #ifdef ISC_PLATFORM_CRYPTORANDOM
595af1
-	if (randomfile != NULL &&
595af1
-	    strcmp(randomfile, ISC_PLATFORM_CRYPTORANDOM) == 0) {
595af1
-		randomfile = NULL;
595af1
+	if (randomfile == NULL) {
595af1
 		isc_entropy_usehook(ectx, ISC_TRUE);
595af1
 	}
595af1
 #endif
595af1
diff --git a/bin/tests/system/tkey/keydelete.c b/bin/tests/system/tkey/keydelete.c
595af1
index 0975bbe4ea..5b8a4701a8 100644
595af1
--- a/bin/tests/system/tkey/keydelete.c
595af1
+++ b/bin/tests/system/tkey/keydelete.c
595af1
@@ -182,9 +182,7 @@ main(int argc, char **argv) {
595af1
 	ectx = NULL;
595af1
 	RUNCHECK(isc_entropy_create(mctx, &ectx));
595af1
 #ifdef ISC_PLATFORM_CRYPTORANDOM
595af1
-	if (randomfile != NULL &&
595af1
-	    strcmp(randomfile, ISC_PLATFORM_CRYPTORANDOM) == 0) {
595af1
-		randomfile = NULL;
595af1
+	if (randomfile == NULL) {
595af1
 		isc_entropy_usehook(ectx, ISC_TRUE);
595af1
 	}
595af1
 #endif
595af1
diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
595af1
index 3ecdc046d0..34c9e85f52 100644
595af1
--- a/doc/arm/Bv9ARM-book.xml
595af1
+++ b/doc/arm/Bv9ARM-book.xml
595af1
@@ -5070,22 +5070,45 @@ badresp:1,adberr:0,findfail:0,valfail:0]
595af1
 	    <term><command>random-device</command></term>
595af1
 	    <listitem>
595af1
 	      <para>
595af1
-		The source of entropy to be used by the server.  Entropy is
595af1
-		primarily needed
595af1
-		for DNSSEC operations, such as TKEY transactions and dynamic
595af1
-		update of signed
595af1
-		zones.  This options specifies the device (or file) from which
595af1
-		to read
595af1
-		entropy.  If this is a file, operations requiring entropy will
595af1
-		fail when the
595af1
-		file has been exhausted.  If not specified, the default value
595af1
-		is
595af1
-		<filename>/dev/random</filename>
595af1
-		(or equivalent) when present, and none otherwise.  The
595af1
-		<command>random-device</command> option takes
595af1
-		effect during
595af1
-		the initial configuration load at server startup time and
595af1
-		is ignored on subsequent reloads.
595af1
+		Specifies a source of entropy to be used by the server.
595af1
+		This is a device or file from which to read entropy.
595af1
+		If it is a file, operations requiring entropy
595af1
+		will fail when the file has been exhausted.
595af1
+	      </para>
595af1
+	      <para>
595af1
+		Entropy is needed for cryptographic operations such as
595af1
+		TKEY transactions, dynamic update of signed zones, and
595af1
+		generation of TSIG session keys. It is also used for
595af1
+		seeding and stirring the pseudo-random number generator,
595af1
+		which is used for less critical functions requiring
595af1
+		randomness such as generation of DNS message transaction
595af1
+		ID's.
595af1
+	      </para>
595af1
+	      <para>
595af1
+		If <command>random-device</command> is not specified, or
595af1
+		if it is set to <literal>none</literal>, entropy will be
595af1
+		read from the random number generation function supplied
595af1
+		by the cryptographic library with which BIND was linked
595af1
+		(i.e.  OpenSSL or a PKCS#11 provider).
595af1
+	      </para>
595af1
+	      <para>
595af1
+		The <command>random-device</command> option takes
595af1
+		effect during the initial configuration load at server
595af1
+		startup time and is ignored on subsequent reloads.
595af1
+	      </para>
595af1
+	      <para>
595af1
+		If BIND is built with
595af1
+		<command>configure --disable-crypto-rand</command>, then
595af1
+		entropy is <emphasis>not</emphasis> sourced from the
595af1
+		cryptographic library. In this case, if
595af1
+		<command>random-device</command> is not specified, the
595af1
+		default value is the system random device,
595af1
+		<filename>/dev/random</filename> or the equivalent.
595af1
+		This default can be overridden with
595af1
+		<command>configure --with-randomdev</command>.
595af1
+		If no system random device exists, then no entropy source
595af1
+		will be configured, and <command>named</command> will only
595af1
+		be able to use pseudo-random numbers.
595af1
 	      </para>
595af1
 	    </listitem>
595af1
 	  </varlistentry>
595af1
diff --git a/doc/arm/notes.xml b/doc/arm/notes.xml
595af1
index 7b7475b58f..49fe0a413e 100644
595af1
--- a/doc/arm/notes.xml
595af1
+++ b/doc/arm/notes.xml
595af1
@@ -128,6 +128,32 @@
595af1
 	  necessary.
595af1
 	</para>
595af1
       </listitem>
595af1
+      <listitem>
595af1
+	<para>
595af1
+	  By default, BIND now uses the random number generation functions
595af1
+	  in the cryptographic library (i.e., OpenSSL or a PKCS#11
595af1
+	  provider) as a source of high-quality randomness rather than
595af1
+	  <filename>/dev/random</filename>.  This is suitable for virtual
595af1
+	  machine environments, which may have limited entropy pools and
595af1
+	  lack hardware random number generators.
595af1
+	</para>
595af1
+	<para>
595af1
+	  This can be overridden by specifying another entropy source via
595af1
+	  the <command>random-device</command> option in
595af1
+	  <filename>named.conf</filename>, or via the <command>-r</command>
595af1
+	  command line option.  However, for functions requiring full
595af1
+	  cryptographic strength, such as DNSSEC key generation, this
595af1
+	  <emphasis>cannot</emphasis> be overridden. In particular, the
595af1
+	  <command>-r</command> command line option no longer has any
595af1
+	  effect on <command>dnssec-keygen</command>.
595af1
+	</para>
595af1
+	<para>
595af1
+	  This can be disabled by building with
595af1
+	  <command>configure --disable-crypto-rand</command>, in which
595af1
+	  case <filename>/dev/random</filename> will be the default
595af1
+	  entropy source.  [RT #31459] [RT #46047]
595af1
+	</para>
595af1
+      </listitem>
595af1
     </itemizedlist>
595af1
   </section>
595af1
 
595af1
diff --git a/lib/dns/dst_api.c b/lib/dns/dst_api.c
595af1
index 803e7b3538..29a4fef44b 100644
595af1
--- a/lib/dns/dst_api.c
595af1
+++ b/lib/dns/dst_api.c
595af1
@@ -276,8 +276,9 @@ dst_lib_init2(isc_mem_t *mctx, isc_entropy_t *ectx,
595af1
 #endif
595af1
 #if defined(OPENSSL) || defined(PKCS11CRYPTO)
595af1
 #ifdef ISC_PLATFORM_CRYPTORANDOM
595af1
-	if (dst_entropy_pool != NULL)
595af1
+	if (dst_entropy_pool != NULL) {
595af1
 		isc_entropy_sethook(dst_random_getdata);
595af1
+	}
595af1
 #endif
595af1
 #endif /* defined(OPENSSL) || defined(PKCS11CRYPTO) */
595af1
 	dst_initialized = ISC_TRUE;
595af1
@@ -2015,10 +2016,12 @@ dst__entropy_getdata(void *buf, unsigned int len, isc_boolean_t pseudo) {
595af1
 	else
595af1
 		flags |= ISC_ENTROPY_BLOCKING;
595af1
 #ifdef ISC_PLATFORM_CRYPTORANDOM
595af1
+	/* get entropy directly from crypto provider */
595af1
 	return (dst_random_getdata(buf, len, NULL, flags));
595af1
 #else
595af1
+	/* get entropy from entropy source or hook function */
595af1
 	return (isc_entropy_getdata(dst_entropy_pool, buf, len, NULL, flags));
595af1
-#endif
595af1
+#endif /* ISC_PLATFORM_CRYPTORANDOM */
595af1
 #endif /* PKCS11CRYPTO */
595af1
 }
595af1
 
595af1
diff --git a/lib/dns/include/dst/dst.h b/lib/dns/include/dst/dst.h
595af1
index d9b6ab6bfb..e8c1a3c287 100644
595af1
--- a/lib/dns/include/dst/dst.h
595af1
+++ b/lib/dns/include/dst/dst.h
595af1
@@ -161,8 +161,18 @@ isc_result_t
595af1
 dst_random_getdata(void *data, unsigned int length,
595af1
 		   unsigned int *returned, unsigned int flags);
595af1
 /*%<
595af1
- * \brief Return data from the crypto random generator.
595af1
- * Specialization of isc_entropy_getdata().
595af1
+ * Gets random data from the random generator provided by the
595af1
+ * crypto library, if BIND was built with --enable-crypto-rand.
595af1
+ *
595af1
+ * See isc_entropy_getdata() for parameter usage. Normally when
595af1
+ * this function is available, it will be set up as a hook in the
595af1
+ * entropy context, so that isc_entropy_getdata() is a front-end to
595af1
+ * this function.
595af1
+ *
595af1
+ * Returns:
595af1
+ * \li	ISC_R_SUCCESS on success
595af1
+ * \li	ISC_R_NOTIMPLEMENTED if BIND is built with --disable-crypto-rand
595af1
+ * \li	DST_R_OPENSSLFAILURE, DST_R_CRYPTOFAILURE, or other codes on error
595af1
  */
595af1
 
595af1
 isc_boolean_t
595af1
diff --git a/lib/dns/openssl_link.c b/lib/dns/openssl_link.c
595af1
index c1e1bde95a..91e87d00b4 100644
595af1
--- a/lib/dns/openssl_link.c
595af1
+++ b/lib/dns/openssl_link.c
595af1
@@ -482,7 +482,8 @@ dst__openssl_getengine(const char *engine) {
595af1
 
595af1
 isc_result_t
595af1
 dst_random_getdata(void *data, unsigned int length,
595af1
-		   unsigned int *returned, unsigned int flags) {
595af1
+		   unsigned int *returned, unsigned int flags)
595af1
+{
595af1
 #ifdef ISC_PLATFORM_CRYPTORANDOM
595af1
 #ifndef DONT_REQUIRE_DST_LIB_INIT
595af1
 	INSIST(dst__memory_pool != NULL);
595af1
diff --git a/lib/isc/include/isc/entropy.h b/lib/isc/include/isc/entropy.h
595af1
index d9deb8ad9b..2d373630ae 100644
595af1
--- a/lib/isc/include/isc/entropy.h
595af1
+++ b/lib/isc/include/isc/entropy.h
595af1
@@ -9,8 +9,6 @@
595af1
  * information regarding copyright ownership.
595af1
  */
595af1
 
595af1
-/* $Id: entropy.h,v 1.35 2009/10/19 02:37:08 marka Exp $ */
595af1
-
595af1
 #ifndef ISC_ENTROPY_H
595af1
 #define ISC_ENTROPY_H 1
595af1
 
595af1
@@ -190,9 +188,8 @@ isc_entropy_createcallbacksource(isc_entropy_t *ent,
595af1
 /*!<
595af1
  * \brief Create an entropy source that is polled via a callback.
595af1
  *
595af1
- * This would
595af1
- * be used when keyboard input is used, or a GUI input method.  It can
595af1
- * also be used to hook in any external entropy source.
595af1
+ * This would be used when keyboard input is used, or a GUI input method.
595af1
+ * It can also be used to hook in any external entropy source.
595af1
  *
595af1
  * Samples are added via isc_entropy_addcallbacksample(), below.
595af1
  * _addcallbacksample() is the only function which may be called from
595af1
@@ -233,15 +230,32 @@ isc_result_t
595af1
 isc_entropy_getdata(isc_entropy_t *ent, void *data, unsigned int length,
595af1
 		    unsigned int *returned, unsigned int flags);
595af1
 /*!<
595af1
- * \brief Extract data from the entropy pool.  This may load the pool from various
595af1
- * sources.
595af1
+ * \brief Get random data from entropy pool 'ent'.
595af1
+ *
595af1
+ * If a hook has been set up using isc_entropy_sethook() and
595af1
+ * isc_entropy_usehook(), then the hook function will be called to get
595af1
+ * random data.
595af1
+ *
595af1
+ * Otherwise, randomness is extracted from the entropy pool set up in BIND.
595af1
+ * This may cause the pool to be loaded from various sources. Ths is done
595af1
+ * by stirring the pool and returning a part of hash as randomness.
595af1
+ * (Note that no secrets are given away here since parts of the hash are
595af1
+ * XORed together before returning.)
595af1
+ *
595af1
+ * 'flags' may contain ISC_ENTROPY_GOODONLY, ISC_ENTROPY_PARTIAL, or
595af1
+ * ISC_ENTROPY_BLOCKING. These will be honored if the hook function is
595af1
+ * not in use. If it is, the flags will be passed to the hook function
595af1
+ * but it may ignore them.
595af1
  *
595af1
- * Do this by stiring the pool and returning a part of hash as randomness.
595af1
- * Note that no secrets are given away here since parts of the hash are
595af1
- * xored together before returned.
595af1
+ * Up to 'length' bytes of randomness are retrieved and copied into 'data'.
595af1
+ * (If 'returned' is not NULL, and the number of bytes copied is less than
595af1
+ * 'length' - which may happen if ISC_ENTROPY_PARTIAL was used - then the
595af1
+ * number of bytes copied will be stored in *returned.)
595af1
  *
595af1
- * Honor the request from the caller to only return good data, any data,
595af1
- * etc.
595af1
+ * Returns:
595af1
+ * \li	ISC_R_SUCCESS on success
595af1
+ * \li	ISC_R_NOENTROPY if entropy pool is empty
595af1
+ * \li	other error codes are possible when a hook is in use
595af1
  */
595af1
 
595af1
 void
595af1
@@ -306,13 +320,21 @@ isc_entropy_usebestsource(isc_entropy_t *ectx, isc_entropysource_t **source,
595af1
 void
595af1
 isc_entropy_usehook(isc_entropy_t *ectx, isc_boolean_t onoff);
595af1
 /*!<
595af1
- * \brief Mark/unmark the given entropy structure as being hooked.
595af1
+ * \brief Configure entropy context 'ectx' to use the hook function
595af1
+ *
595af1
+ * Sets the entropy context to call the hook function for random number
595af1
+ * generation, if such a function has been configured via
595af1
+ * isc_entropy_sethook(), whenever isc_entropy_getdata() is called.
595af1
  */
595af1
 
595af1
 void
595af1
 isc_entropy_sethook(isc_entropy_getdata_t myhook);
595af1
 /*!<
595af1
- * \brief Set the getdata hook (e.g., for a crypto random generator).
595af1
+ * \brief Set the hook function.
595af1
+ *
595af1
+ * The hook function is a global value: only one hook function
595af1
+ * can be set in the system. Individual entropy contexts may be
595af1
+ * configured to use it, or not, by calling isc_entropy_usehook().
595af1
  */
595af1
 
595af1
 ISC_LANG_ENDDECLS
595af1
diff --git a/lib/isc/include/isc/random.h b/lib/isc/include/isc/random.h
595af1
index ba53ebf35c..b57572842c 100644
595af1
--- a/lib/isc/include/isc/random.h
595af1
+++ b/lib/isc/include/isc/random.h
595af1
@@ -9,8 +9,6 @@
595af1
  * information regarding copyright ownership.
595af1
  */
595af1
 
595af1
-/* $Id: random.h,v 1.20 2009/01/17 23:47:43 tbox Exp $ */
595af1
-
595af1
 #ifndef ISC_RANDOM_H
595af1
 #define ISC_RANDOM_H 1
595af1
 
595af1
@@ -21,13 +19,23 @@
595af1
 #include <isc/mutex.h>
595af1
 
595af1
 /*! \file isc/random.h
595af1
- * \brief Implements a random state pool which will let the caller return a
595af1
- * series of possibly non-reproducible random values.
595af1
+ * \brief Implements pseudo random number generators.
595af1
+ *
595af1
+ * Two pseudo-random number generators are implemented, in isc_random_*
595af1
+ * and isc_rng_*. Neither one is very strong; they should not be used
595af1
+ * in cryptography functions.
595af1
+ *
595af1
+ * isc_random_* is based on arc4random if it is available on the system.
595af1
+ * Otherwise it is based on the posix srand() and rand() functions.
595af1
+ * It is useful for jittering values a bit here and there, such as
595af1
+ * timeouts, etc, but should not be relied upon to generate
595af1
+ * unpredictable sequences (for example, when choosing transaction IDs).
595af1
  *
595af1
- * Note that the
595af1
- * strength of these numbers is not all that high, and should not be
595af1
- * used in cryptography functions.  It is useful for jittering values
595af1
- * a bit here and there, such as timeouts, etc.
595af1
+ * isc_rng_* is based on ChaCha20, and is seeded and stirred from the
595af1
+ * system entropy source. It is stronger than isc_random_* and can
595af1
+ * be used for generating unpredictable sequences. It is still not as
595af1
+ * good as using system entropy directly (see entropy.h) and should not
595af1
+ * be used for cryptographic functions such as key generation.
595af1
  */
595af1
 
595af1
 ISC_LANG_BEGINDECLS
595af1
@@ -115,8 +123,8 @@ isc_rng_random(isc_rng_t *rngctx);
595af1
 isc_uint16_t
595af1
 isc_rng_uniformrandom(isc_rng_t *rngctx, isc_uint16_t upper_bound);
595af1
 /*%<
595af1
- * Returns a uniformly distributed pseudo random 16-bit unsigned
595af1
- * integer.
595af1
+ * Returns a uniformly distributed pseudo-random 16-bit unsigned integer
595af1
+ * less than 'upper_bound'.
595af1
  */
595af1
 
595af1
 ISC_LANG_ENDDECLS
595af1
diff --git a/lib/isccfg/namedconf.c b/lib/isccfg/namedconf.c
595af1
index 8d496ff9ce..dd08187312 100644
595af1
--- a/lib/isccfg/namedconf.c
595af1
+++ b/lib/isccfg/namedconf.c
595af1
@@ -1106,7 +1106,7 @@ options_clauses[] = {
595af1
 	{ "pid-file", &cfg_type_qstringornone, 0 },
595af1
 	{ "port", &cfg_type_uint32, 0 },
595af1
 	{ "querylog", &cfg_type_boolean, 0 },
595af1
-	{ "random-device", &cfg_type_qstring, 0 },
595af1
+	{ "random-device", &cfg_type_qstringornone, 0 },
595af1
 	{ "recursing-file", &cfg_type_qstring, 0 },
595af1
 	{ "recursive-clients", &cfg_type_uint32, 0 },
595af1
 	{ "reserved-sockets", &cfg_type_uint32, 0 },
595af1
-- 
595af1
2.14.4
595af1