jitter: add a new provider containing a jitter entropy source alone

This entropy source can be used instead of SEED-SRC. Sample openssl.cnf configuration is provided. It is built as a separate provider, because it is likely to require less frequent updates than fips provider. The same build likely can span multiple generations of FIPS 140 standard revisions. Note that rand-instances currently chain from public/private instances to primary, prior to consuming the seed. Thus currently a unique ESV needs to be obtained, and resue of jitterentropy.a certificate is not possible as is. Separately a patch will be sent to allow for unchaining public/private RAND instances for the purpose of reusing ESV. Also I do wonder if it makes sense to create a fips variant of stock SEED-SRC entropy source, which in addition to using getrandom() also verifies that the kernel is operating in FIPS mode and thus is likely a validated entropy source. As in on Linux, check that /proc/sys/crypto/fips_enabled is set to 1, and similar checks on Windows / MacOS and so on. Reviewed-by: Shane Lontis <[email protected]> Reviewed-by: Paul Dale <[email protected]> (Merged from openssl#24844)
a-mair · Jul 31, 2024 · b28b312 · b28b312
1 parent 4f5febe
commit b28b312
Show file tree

Hide file tree

Showing 15 changed files with 458 additions and 1 deletion.
diff --git a/.github/workflows/run-checker-daily.yml b/.github/workflows/run-checker-daily.yml
@@ -191,6 +191,34 @@ jobs:
       if: steps.sctp_auth.outcome == 'success' && steps.sctp_auth.conclusion == 'success'
       run: make test HARNESS_JOBS=${HARNESS_JOBS:-4}
 
+  jitter_provider:
+    runs-on: ubuntu-latest
+    steps:
+    - name: checkout openssl
+      uses: actions/checkout@v4
+    - name: checkout jitter
+      uses: actions/checkout@v4
+      with:
+        repository: smuellerDD/jitterentropy-library
+        ref: v3.5.0
+        path: jitter
+    - name: build jitter
+      run: make -C jitter/
+    - name: checkout fuzz/corpora submodule
+      run: git submodule update --init --depth 1 fuzz/corpora
+    - name: config
+      run: ./config enable-jitter --with-jitter-include=jitter/ --with-jitter-lib=jitter/ && perl configdata.pm --dump
+    - name: make
+      run: make -s -j4
+    - name: get cpu info
+      run: |
+        cat /proc/cpuinfo
+        ./util/opensslwrap.sh version -c
+    - name: make test
+      run: make test HARNESS_JOBS=${HARNESS_JOBS:-4}
+    - name: test jitter entropy
+      run: ./util/wrap.pl -jitter ./apps/openssl rand -hex 8
+
   enable_brotli_dynamic:
     runs-on: ubuntu-latest
     steps:

diff --git a/CHANGES.md b/CHANGES.md
@@ -167,6 +167,11 @@ OpenSSL 3.3
 
 ### Changes between 3.2 and 3.3.0 [9 Apr 2024]
 
+ * Add a new random seed source RNG `JITTER` using a statically linked
+   jitterentropy library.
+
+   *Dimitri John Ledkov*
+
  * The `-verify` option to the `openssl crl` and `openssl req` will make
    the program exit with 1 on failure.
 

diff --git a/Configurations/00-base-templates.conf b/Configurations/00-base-templates.conf
@@ -59,6 +59,8 @@ my %targets=(
         includes        =>
             sub {
                 my @incs = ();
+                push @incs, $withargs{jitter_include}
+                    if !$disabled{jitter} && $withargs{jitter_include};
                 push @incs, $withargs{brotli_include}
                     if !$disabled{brotli} && $withargs{brotli_include};
                 push @incs, $withargs{zlib_include}
@@ -95,6 +97,7 @@ my %targets=(
         lflags          =>
             sub {
                 my @libs = ();
+                push(@libs, "-L".$withargs{jitter_lib}) if $withargs{jitter_lib};
                 push(@libs, "-L".$withargs{zlib_lib}) if $withargs{zlib_lib};
                 push(@libs, "-L".$withargs{brotli_lib}) if $withargs{brotli_lib};
                 push(@libs, "-L".$withargs{zstd_lib}) if $withargs{zstd_lib};
@@ -103,6 +106,7 @@ my %targets=(
         ex_libs         =>
             sub {
                 my @libs = ();
+                push(@libs, "-l:libjitterentropy.a") if !defined($disabled{jitter});
                 push(@libs, "-lz") if !defined($disabled{zlib}) && defined($disabled{"zlib-dynamic"});
                 if (!defined($disabled{brotli}) && defined($disabled{"brotli-dynamic"})) {
                     push(@libs, "-lbrotlienc");

diff --git a/Configure b/Configure
@@ -476,6 +476,7 @@ my @disablables = (
     "gost",
     "http",
     "idea",
+    "jitter",
     "ktls",
     "legacy",
     "loadereng",
@@ -586,6 +587,7 @@ our %disabled = ( # "what"         => "comment"
                   "fuzz-afl"            => "default",
                   "fuzz-libfuzzer"      => "default",
                   "pie"                 => "default",
+                  "jitter"              => "default",
                   "ktls"                => "default",
                   "md2"                 => "default",
                   "msan"                => "default",
@@ -1019,6 +1021,14 @@ while (@argvcopy)
                         {
                         $config{openssldir}=$1;
                         }
+                elsif (/^--with-jitter-include=(.*)$/)
+                        {
+                        $withargs{jitter_include}=$1;
+                        }
+                elsif (/^--with-jitter-lib=(.*)$/)
+                        {
+                        $withargs{jitter_lib}=$1;
+                        }
                 elsif (/^--with-zlib-lib=(.*)$/)
                         {
                         $withargs{zlib_lib}=$1;

diff --git a/INSTALL.md b/INSTALL.md
@@ -521,6 +521,46 @@ at the end of this document.
 
 [rng]: #notes-on-random-number-generation
 
+# jitter
+
+When configured with `enable-jitter`, a "JITTER" RNG is compiled that
+can provided alternative software seed source. It can be configured by
+loadin setting `seed` setting in `openssl.cnf`. An example
+`openssl.cnf` is shown below:
+
+    openssl_conf = openssl_init
+
+    # Comment out the next line to ignore configuration errors
+    config_diagnostics = 1
+
+    [openssl_init]
+    providers = provider_sect
+    random = random
+
+    [provider_sect]
+    default = default_sect
+
+    [default_sect]
+    activate = 1
+
+    [random]
+    seed=JITTER
+
+It uses statically linked [jitterentropy-library](https://github.com/smuellerDD/jitterentropy-library) as the seed source.
+
+Additional configuration flags available:
+
+    --with-jitter-include=DIR
+
+The directory for the location of the jitterentropy.h include file, if
+it is outside the system include path.
+
+    --with-jitter-lib=DIR
+
+This is the directory containing the static libjitterentropy.a
+library, if it is outside the system library path.
+
+
 Setting the FIPS HMAC key
 -------------------------
 

diff --git a/crypto/info.c b/crypto/info.c
@@ -15,6 +15,11 @@
 #include "internal/e_os.h"
 #include "buildinf.h"
 
+#ifndef OPENSSL_NO_JITTER
+# include <stdio.h>
+# include <jitterentropy.h>
+#endif
+
 #if defined(__arm__) || defined(__arm) || defined(__aarch64__)
 # include "arm_arch.h"
 # define CPU_INFO_STR_LEN 128
@@ -182,6 +187,11 @@ DEFINE_RUN_ONCE_STATIC(init_info_strings)
 #endif
 #ifdef OPENSSL_RAND_SEED_OS
         add_seeds_string("os-specific");
+#endif
+#ifndef OPENSSL_NO_JITTER
+        char jent_version_string[32];
+        sprintf(jent_version_string, "JITTER (%d)", jent_version());
+        add_seeds_string(jent_version_string);
 #endif
         seed_sources = seeds;
     }

diff --git a/providers/baseprov.c b/providers/baseprov.c
@@ -93,6 +93,9 @@ static const OSSL_ALGORITHM base_store[] = {
 
 static const OSSL_ALGORITHM base_rands[] = {
     { PROV_NAMES_SEED_SRC, "provider=base", ossl_seed_src_functions },
+#ifndef OPENSSL_NO_JITTER
+    { PROV_NAMES_JITTER, "provider=base", ossl_jitter_functions },
+#endif
     { NULL, NULL, NULL }
 };
 

diff --git a/providers/defltprov.c b/providers/defltprov.c
@@ -387,6 +387,9 @@ static const OSSL_ALGORITHM deflt_rands[] = {
     { PROV_NAMES_HASH_DRBG, "provider=default", ossl_drbg_hash_functions },
     { PROV_NAMES_HMAC_DRBG, "provider=default", ossl_drbg_ossl_hmac_functions },
     { PROV_NAMES_SEED_SRC, "provider=default", ossl_seed_src_functions },
+#ifndef OPENSSL_NO_JITTER
+    { PROV_NAMES_JITTER, "provider=default", ossl_jitter_functions },
+#endif
     { PROV_NAMES_TEST_RAND, "provider=default", ossl_test_rng_functions },
     { NULL, NULL, NULL }
 };

diff --git a/providers/implementations/include/prov/implementations.h b/providers/implementations/include/prov/implementations.h
@@ -290,6 +290,7 @@ extern const OSSL_DISPATCH ossl_kdf_argon2id_functions[];
 /* RNGs */
 extern const OSSL_DISPATCH ossl_test_rng_functions[];
 extern const OSSL_DISPATCH ossl_seed_src_functions[];
+extern const OSSL_DISPATCH ossl_jitter_functions[];
 extern const OSSL_DISPATCH ossl_drbg_hash_functions[];
 extern const OSSL_DISPATCH ossl_drbg_ossl_hmac_functions[];
 extern const OSSL_DISPATCH ossl_drbg_ctr_functions[];

diff --git a/providers/implementations/include/prov/names.h b/providers/implementations/include/prov/names.h
@@ -311,6 +311,7 @@
 #define PROV_NAMES_HMAC_DRBG "HMAC-DRBG"
 #define PROV_NAMES_TEST_RAND "TEST-RAND"
 #define PROV_NAMES_SEED_SRC "SEED-SRC"
+#define PROV_NAMES_JITTER "JITTER"
 
 /*-
  * Asymmetric algos

diff --git a/providers/implementations/include/prov/seeding.h b/providers/implementations/include/prov/seeding.h
@@ -13,6 +13,7 @@
 /* Hardware-based seeding functions. */
 size_t ossl_prov_acquire_entropy_from_tsc(RAND_POOL *pool);
 size_t ossl_prov_acquire_entropy_from_cpu(RAND_POOL *pool);
+size_t ossl_prov_acquire_entropy_from_jitter(RAND_POOL *pool);
 
 /*
  * External seeding functions from the core dispatch table.

diff --git a/providers/implementations/rands/build.info b/providers/implementations/rands/build.info
@@ -3,4 +3,4 @@ SUBDIRS=seeding
 $RANDS_GOAL=../../libdefault.a ../../libfips.a
 
 SOURCE[$RANDS_GOAL]=drbg.c test_rng.c drbg_ctr.c drbg_hash.c drbg_hmac.c crngt.c
-SOURCE[../../libdefault.a]=seed_src.c
+SOURCE[../../libdefault.a]=seed_src.c seed_src_jitter.c