futoin-hkdf - npm Package Compare versions

Comparing version 1.3.3 to 1.4.0

CHANGELOG.txt

@@ -0,1 +1,6 @@
+=== 1.4.0 (2021-07-02) ===
+CHANGED: hdkf.expand() info parameter to use binary buffer as-is without copying
+CHANGED: dependency maintenance
+NEW: tls, tls.info() and tls.expand_label() feature inspired by TLS v1.3 RFC8446 section 7.1
+
 === 1.3.3 (2021-01-31) ===
@@ -2,0 +7,0 @@ CHANGED: dependency maintenance

futoin.json

 {
   "name": "futoin-hkdf",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "vcs": "git",
@@ -13,3 +13,4 @@ "rms": "npm",
       "@cid tool envexec node -- sh -c \"test $NODE_ENV != production\"",
-      "@cte grunt test"
+      "@cte grunt test",
+      "@cte node node_modules/.bin/tsd"
     ],
@@ -16,0 +17,0 @@ "upgrade-deps": [

hkdf.js

@@ -98,3 +98,3 @@ 'use strict';
 const hkdf_expand = ( hash, hash_len, prk, length, info ) => {
-    const b_info = Buffer.from( info || '' );
+    const b_info = Buffer.isBuffer( info ) ? info : Buffer.from( info || '' );
     const info_len = b_info.length;
@@ -101,0 +101,0 @@

package.json

 {
   "name": "futoin-hkdf",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "description": "RFC5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF)",
@@ -38,13 +38,14 @@ "main": "hkdf.js",
   "devDependencies": {
+    "@types/node": "^15.14.0",
     "benchmark": "^2.1.4",
-    "chai": "^4.2.0",
-    "eslint": "^7.19.0",
-    "grunt": "^1.3.0",
+    "chai": "^4.3.4",
+    "eslint": "^7.29.0",
+    "grunt": "^1.4.1",
     "grunt-eslint": "^23.0.0",
-    "grunt-jsdoc-to-markdown": "^5.0.0",
+    "grunt-jsdoc-to-markdown": "^6.0.0",
     "grunt-simple-nyc": "^3.0.1",
     "grunt-text-replace": "^0.4.0",
-    "mocha": "^8.2.1",
-    "tsd": "^0.14.0"
+    "mocha": "^9.0.1",
+    "tsd": "^0.17.0"
   }
 }

README.md

@@ -14,2 +14,4 @@
 
+Additionally, it supports a `HKDF-Expand-Label` variation based on [RFC8446: The Transport Layer Security (TLS) Protocol Version 1.3, section 7.1. Key Schedule](https://datatracker.ietf.org/doc/html/rfc8446#section-7.1).
+
 The implementation is fully compliant with test vectors provided in the RFC.
@@ -98,2 +100,18 @@
 hkdf.expand(lhash, hash_len. prk, length, info); // run only step #2
+
+// TLS v1.3+
+//-------------------
+const hkdf_tls = require('futoin-hkdf/tls');
+
+const label = 'tls13 ...';
+const context = Buffer.from( /* E.g some binary hash generation */ '' );
+
+hkdf_tls(ikm, length, {salt, label, context, hash}); // Buffer(length) - derived key
+
+// Advanced usage
+hkdf_tls.expand_label(lhash, hash_len. prk, length, labe, context);
+
+// Same as:
+hkdf.expand(lhash, hash_len, prk, length, hkdf_tls.info(length, labe, context));
+
 ```
@@ -103,2 +121,13 @@
 
+## Functions
+
+<dl>
+<dt><a href="#hkdf">hkdf(ikm, length, salt, info, hash)</a> ⇒ <code>Buffer</code></dt>
+<dd><p>HMAC-based Extract-and-Expand Key Derivation Function (HKDF)</p>
+</dd>
+<dt><a href="#tls">tls(ikm, length, salt, label, info, hash)</a> ⇒ <code>Buffer</code></dt>
+<dd><p>TLS v1.3 HKDF-extract + HKFD-Expand-Label action</p>
+</dd>
+</dl>
+
 <a name="hkdf"></a>
@@ -172,2 +201,58 @@
 
+<a name="tls"></a>
 
+## tls(ikm, length, salt, label, info, hash) ⇒ <code>Buffer</code>
+TLS v1.3 HKDF-extract + HKFD-Expand-Label action
+
+**Kind**: global function  
+**Returns**: <code>Buffer</code> - Raw buffer with derived key of @p length bytes  
+**Note**: label and context are limited to 255 bytes!  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| ikm | <code>Buffer</code> \| <code>string</code> |  | Initial Keying Material |
+| length | <code>integer</code> |  | Required byte length of output |
+| salt | <code>Buffer</code> \| <code>string</code> | <code>&#x27;&#x27;</code> | Optional salt (required by fact) |
+| label | <code>Buffer</code> \| <code>string</code> | <code>&#x27;&#x27;</code> | Optional label (required by fact) |
+| info | <code>Buffer</code> \| <code>string</code> | <code>&#x27;&#x27;</code> | Optional context (safe to skip) |
+| hash | <code>string</code> | <code>&quot;&#x27;SHA-256&#x27;&quot;</code> | HMAC hash function to use |
+
+
+* [tls(ikm, length, salt, label, info, hash)](#tls) ⇒ <code>Buffer</code>
+    * [.info(length, label, context)](#tls.info) ⇒ <code>Buffer</code>
+    * [.expand_label(hash, hash_len, prk, length, label, context)](#tls.expand_label) ⇒ <code>Buffer</code>
+
+<a name="tls.info"></a>
+
+### tls.info(length, label, context) ⇒ <code>Buffer</code>
+Encode HKDF context parameter in TLS v1.3 style based on RFC8446 TLS v1.3.
+
+**Kind**: static method of [<code>tls</code>](#tls)  
+**Returns**: <code>Buffer</code> - A buffer with encoded HKDF context  
+**Note**: label and context are limited to 255 bytes!  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| length | <code>integer</code> | length of output keying material in octets |
+| label | <code>string</code> | ASCII label |
+| context | <code>Buffer</code> \| <code>string</code> | Binary context or empty string |
+
+<a name="tls.expand_label"></a>
+
+### tls.expand\_label(hash, hash_len, prk, length, label, context) ⇒ <code>Buffer</code>
+TLS-HKDF expand label action - a HKDF-Expand-Label variation based on RFC8446 TLS v1.3.
+
+**Kind**: static method of [<code>tls</code>](#tls)  
+**Returns**: <code>Buffer</code> - A buffer with output keying material  
+**Note**: label and context are limited to 255 bytes!  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| hash | <code>string</code> | Hash algorithm (as in underlying Node.js crypto library) |
+| hash_len | <code>integer</code> | Hash digest length |
+| prk | <code>Buffer</code> \| <code>string</code> | A buffer with pseudorandom key |
+| length | <code>integer</code> | length of output keying material in octets |
+| label | <code>string</code> | ASCII label |
+| context | <code>Buffer</code> \| <code>string</code> | Binary context or empty string |
+
+

No alert changes

Improved metrics

Total package byte prevSize

29934

increased by15.96%

Lines of code

200

increased by0.5%

Number of lines in readme file

255

increased by50%

Worsened metrics

Dev dependency count

11

increased by10%

No dependency changes