fix(*): hkdf is not approved by FIPS, use PBKDF2 instead on FIPS-mode

bungle · bungle · commit b4fd9c45eb37 · 2023-02-15T17:07:53.000+02:00
### Summary

It turned out that HDKF is only allowed by FIPS in TLS context. This changes
the crypto in this library to use PBKDF2 with SHA-256 using a single iteration
in places where it used HDKF before when in FIPS-mode. This change does not
affect non-fips. Effectively it makes cookies created on FIPS mode incompatible
with cookies created on non-FIPS mode, which is most likely a good thing.
diff --git a/README.md b/README.md
@@ -1262,7 +1262,7 @@ Header fields explained:
    1. derive IKM from `secret` by hashing `secret` with SHA-256, or
    2. use 32 byte IKM when passed to library with `ikm`
 2. Generate 32 bytes of crypto random session id (`sid`) 
-3. Derive 32 byte encryption key and 12 byte initialization vector with HKDF using SHA-256 
+3. Derive 32 byte encryption key and 12 byte initialization vector with HKDF using SHA-256 (on FIPS-mode it uses PBKDF2 with SHA-256 instead)
    1. Use HKDF extract to derive a new key from `ikm` to get `key` (this step can be done just once per `ikm`):
       - output length: `32`
       - digest: `"sha256"`
@@ -1292,7 +1292,8 @@ Header fields explained:
       6. Data Size
 
 There is a variation for `remember` cookies on step 3, where we may use `PBKDF2`
-instead of `HKDF`, depending  on `remember_safety` setting. The `PBKDF2` settings:
+instead of `HKDF`, depending  on `remember_safety` setting (we also use it in FIPS-mode).
+The `PBKDF2` settings:
 
 - output length: `44`
 - digest: `"sha256"`
@@ -1306,7 +1307,7 @@ if `remember_safety` is set to `"None"`, we will use the HDKF as above.
 
 # Cookie Header Authentication
 
-1. Derive 32 byte authentication key (`mac_key`) with HKDF using SHA-256:
+1. Derive 32 byte authentication key (`mac_key`) with HKDF using SHA-256  (on FIPS-mode it uses PBKDF2 with SHA-256 instead):
     1. Use HKDF extract to derive a new key from `ikm` to get `key` (this step can be done just once per `ikm` and reused with encryption key generation):
         - output length: `32`
         - digest: `"sha256"`
diff --git a/docs/index.html b/docs/index.html
@@ -120,7 +120,7 @@ <h2>Modules</h2>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.dshm.html b/docs/modules/resty.session.dshm.html
@@ -390,7 +390,7 @@ <h3>Returns:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.file.html b/docs/modules/resty.session.file.html
@@ -360,7 +360,7 @@ <h3>Returns:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.file.thread.html b/docs/modules/resty.session.file.thread.html
@@ -324,7 +324,7 @@ <h3>Returns:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.file.utils.html b/docs/modules/resty.session.file.utils.html
@@ -343,7 +343,7 @@ <h3>Returns:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.html b/docs/modules/resty.session.html
@@ -1300,7 +1300,7 @@ <h3>Usage:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.memcached.html b/docs/modules/resty.session.memcached.html
@@ -393,7 +393,7 @@ <h3>Returns:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.mysql.html b/docs/modules/resty.session.mysql.html
@@ -473,7 +473,7 @@ <h3>Usage:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.postgres.html b/docs/modules/resty.session.postgres.html
@@ -469,7 +469,7 @@ <h3>Usage:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.redis.cluster.html b/docs/modules/resty.session.redis.cluster.html
@@ -456,7 +456,7 @@ <h3>Returns:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.redis.common.html b/docs/modules/resty.session.redis.common.html
@@ -314,7 +314,7 @@ <h3>Returns:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.redis.html b/docs/modules/resty.session.redis.html
@@ -402,7 +402,7 @@ <h3>Returns:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.redis.sentinel.html b/docs/modules/resty.session.redis.sentinel.html
@@ -453,7 +453,7 @@ <h3>Returns:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.shm.html b/docs/modules/resty.session.shm.html
@@ -357,7 +357,7 @@ <h3>Returns:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/resty.session.utils.html b/docs/modules/resty.session.utils.html
@@ -66,6 +66,10 @@ <h1>Module <code>resty.session.utils</code></h1>
 
 <h2><a href="#Functions">Functions</a></h2>
 <table class="function_list">
+	<tr>
+	<td class="name" nowrap><a href="#is_fips_mode">is_fips_mode ()</a></td>
+	<td class="summary">Returns whether OpenSSL is in FIPS-mode.</td>
+	</tr>
 	<tr>
 	<td class="name" nowrap><a href="#bpack">bpack (size, value)</a></td>
 	<td class="summary">Binary pack unsigned integer.</td>
@@ -128,7 +132,8 @@ <h2><a href="#Functions">Functions</a></h2>
 	</tr>
 	<tr>
 	<td class="name" nowrap><a href="#derive_hmac_sha256_key">derive_hmac_sha256_key (ikm, nonce)</a></td>
-	<td class="summary">Derive HMAC SHA-256 key for message authentication using HDKF with SHA-256.</td>
+	<td class="summary">Derive HMAC SHA-256 key for message authentication using HDKF with SHA-256,
+ except on FIPS-mode it uses PBKDF2 with SHA-256 (single iteration).</td>
 	</tr>
 	<tr>
 	<td class="name" nowrap><a href="#encrypt_aes_256_gcm">encrypt_aes_256_gcm (key, iv, plaintext, aad)</a></td>
@@ -190,6 +195,30 @@ <h2><a href="#Functions">Functions</a></h2>
     <h2 class="section-header "><a name="Functions"></a>Functions</h2>
 
     <dl class="function">
+    <dt>
+    <a name = "is_fips_mode"></a>
+    <strong>is_fips_mode ()</strong>
+    </dt>
+    <dd>
+    Returns whether OpenSSL is in FIPS-mode.
+
+
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">boolean</span></span>
+        <code>true</code> if OpenSSL is in FIPS-mode, otherwise <code>false</code>
+    </ol>
+
+
+
+    <h3>Usage:</h3>
+    <ul>
+        <pre class="example"><span class="keyword">local</span> is_fips = <span class="global">require</span> <span class="string">"resty.session.utils"</span>.is_fips_mode()</pre>
+    </ul>
+
+</dd>
     <dt>
     <a name = "bpack"></a>
     <strong>bpack (size, value)</strong>
@@ -744,7 +773,7 @@ <h3>Usage:</h3>
     Derive a new AES-256 GCM-mode key and initialization vector. </p>
 
 <p> Safety can be:
- <em> <code>nil</code> or <code>&quot;None&quot;</code>: key and iv will be derived using HKDF with SHA-256
+ <em> <code>nil</code> or <code>&quot;None&quot;</code>: key and iv will be derived using HKDF with SHA-256, except on FIPS-mode uses PBKDF2 with SHA-256 (single iteration)
  </em> <code>Low</code>: key and iv will be derived using PBKDF2 with SHA-256 (1.000 iterations)
  <em> <code>Medium</code>: key and iv will be derived using PBKDF2 with SHA-256 (10.000 iterations)
  </em> <code>High</code>: key and iv will be derived using PBKDF2 with SHA-256 (100.000 iterations)
@@ -797,7 +826,8 @@ <h3>Usage:</h3>
     <strong>derive_hmac_sha256_key (ikm, nonce)</strong>
     </dt>
     <dd>
-    Derive HMAC SHA-256 key for message authentication using HDKF with SHA-256.
+    Derive HMAC SHA-256 key for message authentication using HDKF with SHA-256,
+ except on FIPS-mode it uses PBKDF2 with SHA-256 (single iteration).
 
 
     <h3>Parameters:</h3>
@@ -1333,7 +1363,7 @@ <h3>Returns:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-01 21:57:55 </i>
+<i style="float:right;">Last updated 2023-02-15 16:31:40 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/lib/resty/session/utils.lua b/lib/resty/session/utils.lua
@@ -21,6 +21,29 @@ local fmt = string.format
 local sub = string.sub
 
 
+local is_fips_mode do
+  local IS_FIPS
+
+  local function is_fips_mode_real()
+    return IS_FIPS == true
+  end
+
+  ---
+  -- Returns whether OpenSSL is in FIPS-mode.
+  --
+  -- @function utils.is_fips_mode
+  -- @treturn boolean `true` if OpenSSL is in FIPS-mode, otherwise `false`
+  --
+  -- @usage
+  -- local is_fips = require "resty.session.utils".is_fips_mode()
+  is_fips_mode = function()
+    IS_FIPS = require("resty.openssl").get_fips_mode()
+    is_fips_mode = is_fips_mode_real
+    return is_fips_mode()
+  end
+end
+
+
 local bpack, bunpack do
   local binpack
   local binunpack
@@ -592,7 +615,7 @@ end
 -- Derive a new AES-256 GCM-mode key and initialization vector.
 --
 -- Safety can be:
--- * `nil` or `"None"`: key and iv will be derived using HKDF with SHA-256
+-- * `nil` or `"None"`: key and iv will be derived using HKDF with SHA-256, except on FIPS-mode uses PBKDF2 with SHA-256 (single iteration)
 -- * `Low`: key and iv will be derived using PBKDF2 with SHA-256 (1.000 iterations)
 -- * `Medium`: key and iv will be derived using PBKDF2 with SHA-256 (10.000 iterations)
 -- * `High`: key and iv will be derived using PBKDF2 with SHA-256 (100.000 iterations)
@@ -625,7 +648,11 @@ local function derive_aes_gcm_256_key_and_iv(ikm, nonce, safety)
     end
 
   else
-    bytes, err = derive_hkdf_sha256(ikm, nonce, "encryption", 44)
+    if is_fips_mode() then
+      bytes, err = derive_pbkdf2_hmac_sha256(ikm, nonce, "encryption", 44, 1)
+    else
+      bytes, err = derive_hkdf_sha256(ikm, nonce, "encryption", 44)
+    end
   end
 
   if not bytes then
@@ -640,7 +667,8 @@ end
 
 
 ---
--- Derive HMAC SHA-256 key for message authentication using HDKF with SHA-256.
+-- Derive HMAC SHA-256 key for message authentication using HDKF with SHA-256,
+-- except on FIPS-mode it uses PBKDF2 with SHA-256 (single iteration).
 --
 -- @function utils.derive_hmac_sha256_key
 -- @tparam string ikm initial key material
@@ -654,6 +682,10 @@ end
 -- local nonce = utils.rand_bytes(32)
 -- local key, err = utils.derive_hmac_sha256_key(ikm, nonce)
 local function derive_hmac_sha256_key(ikm, nonce)
+  if is_fips_mode() then
+    return derive_pbkdf2_hmac_sha256(ikm, nonce, "authentication", 32, 1)
+  end
+
   return derive_hkdf_sha256(ikm, nonce, "authentication", 32)
 end
 
@@ -1093,6 +1125,7 @@ end
 
 
 return {
+  is_fips_mode = is_fips_mode,
   bpack = bpack,
   bunpack = bunpack,
   trim = trim,
