Add build-time option to opt-out of CPU Jitter Entropy (#2733)

Adds a build-time option DISABLE_USAGE_OF_CPU_JITTER_ENTROPY to opt-out of CPU Jitter Entropy. That is, with this option CPU Jitter Entropy will never be configured, the tree-DRBG will not be used. Furthermore, CPU Jitter Entropy will not even be included in any compilation units.

When using DISABLE_USAGE_OF_CPU_JITTER_ENTROPY we can no longer guarantee two entropy sources because only the Operating System type will be required to be available. rdrand and rndr will be used if supported in any given run-time, but it's not a guarantee.

Author: torben-hansen

CMakeLists.txt

@@ -95,6 +95,8 @@ option(ENABLE_DATA_INDEPENDENT_TIMING "Enable automatic setting/resetting Data-I
 (DIT) flag in cryptographic functions. Currently only applicable to Arm64 (except on Windows)" OFF)
 option(ENABLE_PRE_SONAME_BUILD "Build AWS-LC without SONAME configuration for shared library builds" ON)
 option(ENABLE_SOURCE_MODIFICATION "Allow the build to update files in the source directory. This is typically done to update versioning." ON)
+option(DISABLE_CPU_JITTER_ENTROPY "Disable usage of CPU Jitter Entropy as an entropy source. This option cannot be used with the FIPS build. With this configuration, randomness generation might not use two independent entropy sources." OFF)
+
 include(cmake/go.cmake)
 
 if(NOT ENABLE_PRE_SONAME_BUILD AND BUILD_SHARED_LIBS AND UNIX AND NOT APPLE)
@@ -110,9 +112,20 @@ message(STATUS "PERFORM_SONAME_BUILD: ${PERFORM_SONAME_BUILD}")
 
 enable_language(C)
 
-# The validated entropy source will always be configured to be CPU Jitter
-# Entropy by default; because it's the root of the Tree DRBG.
-message(STATUS "Entropy source configured: Dynamic (default: CPU Jitter)")
+if(DISABLE_CPU_JITTER_ENTROPY)
+  if(FIPS)
+    message(FATAL_ERROR "Cannot opt-out of CPU Jitter for the FIPS build")
+  endif()
+  add_definitions(-DDISABLE_CPU_JITTER_ENTROPY)
+  message(STATUS "Entropy source configuration: CPU Jitter opt-out")
+  message(STATUS "Entropy source configured: Dynamic (default: Operating system)")
+else()
+  # The validated entropy source will always be configured to be CPU Jitter
+  # Entropy by default; because it's the root of the Tree DRBG.
+  message(STATUS "Entropy source configured: Dynamic (default: CPU Jitter)")
+endif()
+
+
 
 if(${CMAKE_SYSTEM_NAME} STREQUAL "OpenBSD")
   # OpenBSD by defaults links with --execute-only this is problematic for two reasons:
@@ -1110,7 +1123,11 @@ if(BUILD_TESTING)
   endmacro()
 endif()
 
-add_subdirectory(third_party/jitterentropy)
+# By default, include jitter entropy.
+if(NOT DISABLE_CPU_JITTER_ENTROPY)
+  add_subdirectory(third_party/jitterentropy)
+endif()
+
 add_subdirectory(crypto)
 if(BUILD_LIBSSL)
   add_subdirectory(ssl)

crypto/CMakeLists.txt

@@ -618,7 +618,11 @@ function(build_libcrypto)
     message(FATAL_ERROR "NAME, MODULE_SOURCE are required arguments to build_libcrypto")
   endif()
 
-  add_library(${arg_NAME} $<TARGET_OBJECTS:crypto_objects> ${CRYPTO_FIPS_OBJECTS} ${arg_MODULE_SOURCE} $<TARGET_OBJECTS:jitterentropy>)
+  add_library(${arg_NAME} $<TARGET_OBJECTS:crypto_objects> ${CRYPTO_FIPS_OBJECTS} ${arg_MODULE_SOURCE})
+
+  if(NOT DISABLE_CPU_JITTER_ENTROPY)
+    target_sources(${arg_NAME} PRIVATE $<TARGET_OBJECTS:jitterentropy>)
+  endif()
 
   if(FIPS_DELOCATE OR FIPS_SHARED)
     add_dependencies(${arg_NAME} bcm_o_target)

crypto/crypto_test.cc

@@ -26,6 +26,7 @@
 
 #include <gtest/gtest.h>
 #include "test/test_util.h"
+#include "ube/snapsafe_detect.h"
 
 static int AWS_LC_ERROR_return(void) {
   GUARD_PTR(NULL);
@@ -74,7 +75,9 @@ TEST(CryptoTest, Strndup) {
 }
 
 TEST(CryptoTest, aws_lc_assert_entropy_cpu_jitter) {
-  ASSERT_EQ(1, FIPS_is_entropy_cpu_jitter());
+  if (FIPS_mode() == 1 && CRYPTO_get_snapsafe_supported() != 1) {
+    ASSERT_EQ(1, FIPS_is_entropy_cpu_jitter());
+  }
 }
 
 TEST(CryptoTest, OPENSSL_hexstr2buf) {

crypto/fipsmodule/rand/cpu_jitter_test.cc

@@ -1,6 +1,8 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0 OR ISC
 
+#if !defined(DISABLE_CPU_JITTER_ENTROPY)
+
 #include <gtest/gtest.h>
 
 #include "../../test/test_util.h"
@@ -63,3 +65,5 @@ TEST(CPUJitterEntropyTest, Basic) {
   unsigned int jitter_version = 3060300;
   EXPECT_EQ(jitter_version, jent_version());
 }
+
+#endif // !defined(DISABLE_CPU_JITTER_ENTROPY)

crypto/fipsmodule/rand/entropy/entropy_source_test.cc

@@ -3,6 +3,8 @@
 
 #include <gtest/gtest.h>
 
+#include <openssl/crypto.h>
+
 #include "internal.h"
 #include "../../../ube/snapsafe_detect.h"
 
@@ -75,13 +77,24 @@ TEST(EntropySources, Configuration) {
 // Snapsafe detection is only defined for Linux. So, only strongly assert on
 // that kernel.
 #if defined(AWSLC_SNAPSAFE_TESTING) && defined(OPENSSL_LINUX)
-  EXPECT_EQ(SNAPSAFE_FALLBACK_ENTROPY_SOURCE, get_entropy_source_method_id_FOR_TESTING());
+  EXPECT_EQ(OPT_OUT_CPU_JITTER_ENTROPY_SOURCE, get_entropy_source_method_id_FOR_TESTING());
+
+// If entropy build configuration choose to explicitly opt-out of CPU Jitter
+// Entropy
+#elif defined(DISABLE_CPU_JITTER_ENTROPY)
+  EXPECT_EQ(OPT_OUT_CPU_JITTER_ENTROPY_SOURCE, get_entropy_source_method_id_FOR_TESTING());
+
 #else
   int expected_entropy_source_id = TREE_DRBG_JITTER_ENTROPY_SOURCE;
   if (CRYPTO_get_snapsafe_supported()) {
-    expected_entropy_source_id = SNAPSAFE_FALLBACK_ENTROPY_SOURCE;
+    expected_entropy_source_id = OPT_OUT_CPU_JITTER_ENTROPY_SOURCE;
   }
 
   EXPECT_EQ(expected_entropy_source_id, get_entropy_source_method_id_FOR_TESTING());
+
+  // For FIPS build we can strongly assert.
+  if (FIPS_mode() == 1 && CRYPTO_get_snapsafe_supported() != 1) {
+    EXPECT_NE(OPT_OUT_CPU_JITTER_ENTROPY_SOURCE, get_entropy_source_method_id_FOR_TESTING());
+  }
 #endif
 }

crypto/fipsmodule/rand/entropy/entropy_sources.c

@@ -36,6 +36,7 @@ static int entropy_get_extra_entropy(
   return 1;
 }
 
+// Tree-DRBG entropy source configuration.
 // - Tree DRBG with Jitter Entropy as root for seeding.
 // - OS as personalization string source.
 // - If run-time is on an x86_64 or Arm64 CPU and it supports rdrand
@@ -56,52 +57,68 @@ DEFINE_LOCAL_DATA(struct entropy_source_methods, tree_jitter_entropy_source_meth
   out->id = TREE_DRBG_JITTER_ENTROPY_SOURCE;
 }
 
-static int snapsafe_fallback_initialize(
+static int opt_out_cpu_jitter_initialize(
   struct entropy_source_t *entropy_source) {
   return 1;
 }
 
-static void snapsafe_fallback_zeroize_thread(struct entropy_source_t *entropy_source) {}
+static void opt_out_cpu_jitter_zeroize_thread(struct entropy_source_t *entropy_source) {}
 
-static void snapsafe_fallback_free_thread(struct entropy_source_t *entropy_source) {}
+static void opt_out_cpu_jitter_free_thread(struct entropy_source_t *entropy_source) {}
 
-static int snapsafe_fallback_get_seed_wrap(
+static int opt_out_cpu_jitter_get_seed_wrap(
   const struct entropy_source_t *entropy_source, uint8_t seed[CTR_DRBG_ENTROPY_LEN]) {
   return snapsafe_fallback_get_seed(seed);
 }
 
-static int use_snapsafe_fallback_entropy(void) {
+// Define conditions for not using CPU Jitter
+static int is_snapsafe_environment(void) {
   return CRYPTO_get_snapsafe_supported();
 }
 
-// Snapsafe fallback environment configurations
-// CPU source required for rule-of-two.
+static int has_explicitly_opted_out_of_cpu_jitter(void) {
+#if defined(DISABLE_CPU_JITTER_ENTROPY)
+  return 1;
+#else
+  return 0;
+#endif
+}
+
+static int use_opt_out_cpu_jitter_entropy(void) {
+  if (has_explicitly_opted_out_of_cpu_jitter() == 1 ||
+      is_snapsafe_environment() == 1) {
+    return 1;
+  }
+  return 0;
+}
+
+// Out-out CPU Jitter configurations. CPU source required for rule-of-two.
 // - OS as seed source source.
 // - Uses rdrand or rndr, if supported, for personalization string. Otherwise
 // falls back to OS source.
-DEFINE_LOCAL_DATA(struct entropy_source_methods, snapsafe_fallback_entropy_source_methods) {
-  out->initialize = snapsafe_fallback_initialize;
-  out->zeroize_thread = snapsafe_fallback_zeroize_thread;
-  out->free_thread = snapsafe_fallback_free_thread;
-  out->get_seed = snapsafe_fallback_get_seed_wrap;
+DEFINE_LOCAL_DATA(struct entropy_source_methods, opt_out_cpu_jitter_entropy_source_methods) {
+  out->initialize = opt_out_cpu_jitter_initialize;
+  out->zeroize_thread = opt_out_cpu_jitter_zeroize_thread;
+  out->free_thread = opt_out_cpu_jitter_free_thread;
+  out->get_seed = opt_out_cpu_jitter_get_seed_wrap;
   if (have_hw_rng_x86_64() == 1 ||
       have_hw_rng_aarch64() == 1) {
     out->get_extra_entropy = entropy_get_prediction_resistance;
   } else {
     // Fall back to seed source because a second source must always be present.
-    out->get_extra_entropy = snapsafe_fallback_get_seed_wrap;
+    out->get_extra_entropy = opt_out_cpu_jitter_get_seed_wrap;
   }
   out->get_prediction_resistance = NULL;
-  out->id = SNAPSAFE_FALLBACK_ENTROPY_SOURCE;
+  out->id = OPT_OUT_CPU_JITTER_ENTROPY_SOURCE;
 }
 
 static const struct entropy_source_methods * get_entropy_source_methods(void) {
   if (*allow_entropy_source_methods_override_bss_get() == 1) {
     return *entropy_source_methods_override_bss_get();
   }
 
-  if (use_snapsafe_fallback_entropy()) {
-    return snapsafe_fallback_entropy_source_methods();
+  if (use_opt_out_cpu_jitter_entropy()) {
+    return opt_out_cpu_jitter_entropy_source_methods();
   }
 
   return tree_jitter_entropy_source_methods();

crypto/fipsmodule/rand/entropy/internal.h

@@ -15,7 +15,7 @@ extern "C" {
 
 #define OVERRIDDEN_ENTROPY_SOURCE 0
 #define TREE_DRBG_JITTER_ENTROPY_SOURCE 1
-#define SNAPSAFE_FALLBACK_ENTROPY_SOURCE 2
+#define OPT_OUT_CPU_JITTER_ENTROPY_SOURCE 2
 
 #define ENTROPY_JITTER_MAX_NUM_TRIES (3)
 
@@ -55,11 +55,20 @@ OPENSSL_EXPORT void override_entropy_source_method_FOR_TESTING(
 
 OPENSSL_EXPORT int get_entropy_source_method_id_FOR_TESTING(void);
 
-OPENSSL_EXPORT int tree_jitter_initialize(struct entropy_source_t *entropy_source);
-OPENSSL_EXPORT void tree_jitter_zeroize_thread_drbg(struct entropy_source_t *entropy_source);
-OPENSSL_EXPORT void tree_jitter_free_thread_drbg(struct entropy_source_t *entropy_source);
-OPENSSL_EXPORT int tree_jitter_get_seed(
-  const struct entropy_source_t *entropy_source, uint8_t seed[CTR_DRBG_ENTROPY_LEN]);
+#if !defined(DISABLE_CPU_JITTER_ENTROPY)
+  OPENSSL_EXPORT int tree_jitter_initialize(struct entropy_source_t *entropy_source);
+  OPENSSL_EXPORT void tree_jitter_zeroize_thread_drbg(struct entropy_source_t *entropy_source);
+  OPENSSL_EXPORT void tree_jitter_free_thread_drbg(struct entropy_source_t *entropy_source);
+  OPENSSL_EXPORT int tree_jitter_get_seed(
+    const struct entropy_source_t *entropy_source, uint8_t seed[CTR_DRBG_ENTROPY_LEN]);
+#else // !defined(DISABLE_CPU_JITTER_ENTROPY)
+  // Define stubs for tree-DRBG functions that implements the entropy source
+  // interface.
+  static inline int tree_jitter_initialize(struct entropy_source_t *entropy_source) { return 0; }
+  static inline void tree_jitter_zeroize_thread_drbg(struct entropy_source_t *entropy_source) { abort(); }
+  static inline void tree_jitter_free_thread_drbg(struct entropy_source_t *entropy_source) { abort(); }
+  static inline int tree_jitter_get_seed(const struct entropy_source_t *entropy_source, uint8_t seed[CTR_DRBG_ENTROPY_LEN]) { return 0; }
+#endif // !defined(DISABLE_CPU_JITTER_ENTROPY)
 
 // rndr_multiple8 writes |len| number of bytes to |buf| generated using the
 // rndr instruction. |len| must be a multiple of 8.

crypto/fipsmodule/rand/entropy/tree_drbg_jitter_entropy.c

@@ -1,6 +1,8 @@
 // Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0 OR ISC
 
+#if !defined(DISABLE_CPU_JITTER_ENTROPY)
+
 #include <openssl/ctrdrbg.h>
 #include <openssl/mem.h>
 #include <openssl/type_check.h>
@@ -535,3 +537,5 @@ OPENSSL_EXPORT int set_thread_and_global_tree_drbg_reseed_counter_FOR_TESTING(
   CRYPTO_STATIC_MUTEX_unlock_write(global_seed_drbg_lock_bss_get());
   return ret;
 }
+
+#endif // !defined(DISABLE_CPU_JITTER_ENTROPY)

crypto/fipsmodule/rand/entropy/tree_drbg_jitter_entropy_isolated_test.cc

@@ -1,6 +1,8 @@
 // Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0 OR ISC
 
+#if !defined(DISABLE_CPU_JITTER_ENTROPY)
+
 #include <gtest/gtest.h>
 
 #include "internal.h"
@@ -551,3 +553,5 @@ TEST(treeDrbgJitterentropyTest, SkippedALL) {
 }
 
 #endif
+
+#endif // !defined(DISABLE_CPU_JITTER_ENTROPY)

crypto/fipsmodule/self_check/fips.c

@@ -19,6 +19,8 @@
 #include "../../internal.h"
 #include "../delocate.h"
 
+#include "../rand/entropy/internal.h"
+
 
 int FIPS_mode(void) {
 #if defined(BORINGSSL_FIPS) && !defined(OPENSSL_ASAN)
@@ -29,6 +31,9 @@ int FIPS_mode(void) {
 }
 
 int FIPS_is_entropy_cpu_jitter(void) {
+  if (OPT_OUT_CPU_JITTER_ENTROPY_SOURCE == get_entropy_source_method_id_FOR_TESTING()) {
+    return 0;
+  }
   return 1;
 }