dstu-core 0.4.0 → 0.5.0

package/README.md

@@ -55,12 +55,13 @@ console.log(dstu.secretboxOpen(key, sealed).toString()); // "a message worth pro
 | Module | Functions/classes | Notes |
 |---|---|---|
 | `crypto_secretbox` | `secretboxKeygen`, `secretboxSeal`, `secretboxOpen` | Single-message authenticated encryption. `examples/secretbox.js`. |
-| `crypto_box` | `boxKeygen`, `boxPublicKey`, `boxSeal`, `boxOpen` | Public-key encryption (hybrid via KDF over `hazmat::dstu9041`, `l(p)=256`, D-169). `boxSeal`/`boxOpen` are not memory-bounded — the whole message is held in memory. `examples/box.js`. |
-| `crypto_box512` | `box512Keygen`, `box512PublicKey`, `box512Seal`, `box512Open` | `l(p)=512`/E512/1 sibling of `crypto_box` (T-193/T-204). `examples/box512.js`. |
+| `crypto_box` | `boxKeygen`, `boxPublicKey`, `boxSeal`, `boxOpen`, `BoxEncryptor`, `BoxDecryptor` | Public-key encryption (hybrid via KDF over `hazmat::dstu9041`, `l(p)=256`, D-169). `boxSeal`/`boxOpen` hold the whole message in memory; the `stream.Transform` `BoxEncryptor`/`BoxDecryptor` write and read the same bytes (format v3) chunk by chunk, as `uacrypt box-seal`/`box-open` do. `examples/box.js`. |
+| `crypto_box384` | `box384Keygen`, `box384PublicKey`, `box384Seal`, `box384Open`, `Box384Encryptor`, `Box384Decryptor` | `l(p)=384`/E384/1 sibling of `crypto_box` (T-297). `examples/box384.js`. |
+| `crypto_box512` | `box512Keygen`, `box512PublicKey`, `box512Seal`, `box512Open`, `Box512Encryptor`, `Box512Decryptor` | `l(p)=512`/E512/1 sibling of `crypto_box` (T-193/T-204). `examples/box512.js`. |
 | `crypto_secretstream` | `secretstreamKeygen`, `SecretStreamPushState`, `SecretStreamPullState`, `SecretStreamEncryptor`, `SecretStreamDecryptor` | Chunked streaming AEAD. The `stream.Transform` `SecretStreamEncryptor`/`SecretStreamDecryptor` wire format matches `uacrypt encrypt`/`decrypt` exactly (D-118). `examples/secretstream-file.js`. |
 | `crypto_sign` | `signKeygen`, `signVerifyingKey`, `signMessage`, `signVerify` | DSTU 4145 `m=163` digital signatures, deterministic nonce (no RNG dependency). `examples/sign.js`. |
 | `crypto_sign257` | `sign257Keygen`, `sign257VerifyingKey`, `sign257Message`, `sign257Verify` | `m=257` sibling of `crypto_sign` (T-199/T-204) — the curve real Diia-issued qualified signatures use. `examples/sign257.js`. |
-| `crypto_pwhash` | `pwhashHashPassword`, `pwhashVerifyPassword`, `PWHASH_INTERACTIVE`/`PWHASH_MODERATE`/`PWHASH_SENSITIVE` | Argon2id (the one deliberately non-DSTU component, D-49/D-50). `examples/password-hashing.js`. |
+| `crypto_pwhash` | `pwhashHashPassword`, `pwhashVerifyPassword`, `pwhashDeriveKey`, `PWHASH_INTERACTIVE`/`PWHASH_MODERATE`/`PWHASH_SENSITIVE`, `PassphraseEncryptor`, `PassphraseDecryptor` | Argon2id (the one deliberately non-DSTU component, D-49/D-50). `pwhashDeriveKey` equals libsodium's `crypto_pwhash`. `PassphraseEncryptor`/`PassphraseDecryptor` write and read the files `uacrypt encrypt --passphrase` makes (D-219/D-240); each runs Argon2id at 256 MiB once, synchronously on the calling thread like `pwhashHashPassword`. `examples/password-hashing.js`. |
 | `crypto_auth` | `authKeygen`, `auth`, `authVerify` | Keyed message authentication (Kupyna-KMAC). `examples/misc.js`. |
 | `crypto_kdf` | `kdfKeygen`, `kdfDeriveSubkey` | Deterministic subkey derivation. `subkeyId` is a plain non-negative `number`, not `BigInt`. `examples/misc.js`. |
 | `crypto_generichash` | `kupyna256`, `kupyna512`, `Kupyna256Hasher`, `Kupyna512Hasher` | One-shot and streaming Kupyna hashing. `examples/misc.js`. |

package/js/index.js

@@ -15,10 +15,9 @@
  */
 
 const native = require('../native/index.js');
-const { SecretStreamEncryptor, SecretStreamDecryptor } = require('./secretstream.js');
+const streams = require('./secretstream.js');
 
 module.exports = {
   ...native,
-  SecretStreamEncryptor,
-  SecretStreamDecryptor,
+  ...streams,
 };

package/js/secretstream.js

@@ -42,11 +42,16 @@ const CHUNK_BYTES = 8 * 1024;
 class SecretStreamEncryptor extends Transform {
   constructor(key, options) {
     super(options);
-    this._enc = new native.SecretStreamFileEncryptor(key);
+    this._enc = this._startCodec(key);
     this._buf = Buffer.alloc(0);
     this.push(this._enc.prefix);
   }
 
+  /** The native codec for `key`; the box/passphrase subclasses start it their own way. */
+  _startCodec(key) {
+    return new native.SecretStreamFileEncryptor(key);
+  }
+
   _transform(chunk, _encoding, callback) {
     this._buf = Buffer.concat([this._buf, chunk]);
     let err;
@@ -96,14 +101,27 @@ class SecretStreamEncryptor extends Transform {
 class SecretStreamDecryptor extends Transform {
   constructor(key, options) {
     super(options);
-    this._dec = new native.SecretStreamFileDecryptor(key);
+    this._dec = this._startCodec(key);
     this._buf = Buffer.alloc(0);
   }
 
+  /** The native codec for `key`, or null while a subclass still collects its prefix. */
+  _startCodec(key) {
+    return new native.SecretStreamFileDecryptor(key);
+  }
+
   _transform(chunk, _encoding, callback) {
     this._buf = Buffer.concat([this._buf, chunk]);
     let err;
     try {
+      if (this._dec === null) {
+        if (this._buf.length < this._prefixBytes) {
+          process.nextTick(callback);
+          return;
+        }
+        this._dec = this._openPrefixed(this._buf.subarray(0, this._prefixBytes));
+        this._buf = this._buf.subarray(this._prefixBytes);
+      }
       let pos = 0;
       for (let want = this._dec.nextLen(); this._buf.length - pos >= want; want = this._dec.nextLen()) {
         const plaintext = this._dec.feed(this._buf.subarray(pos, pos + want));
@@ -121,6 +139,7 @@ class SecretStreamDecryptor extends Transform {
   _flush(callback) {
     let err;
     try {
+      if (this._dec === null) throw new Error(`input too short to contain a ${this._prefixName}`);
       const plaintext = this._dec.finish();
       if (plaintext.length > 0) this.push(plaintext);
     } catch (e) {
@@ -130,4 +149,130 @@ class SecretStreamDecryptor extends Transform {
   }
 }
 
-module.exports = { SecretStreamEncryptor, SecretStreamDecryptor };
+function checkLength(buf, bytes, name) {
+  if (!Buffer.isBuffer(buf) || buf.length !== bytes) {
+    throw new TypeError(`${name} must be a ${bytes}-byte Buffer`);
+  }
+}
+
+/**
+ * `crypto_box` sealed to `publicKey` as a stream (format v3, T-265/T-269): the same bytes
+ * `boxSeal` returns, written chunk by chunk; `boxOpen`/`BoxDecryptor` read them.
+ */
+class BoxEncryptor extends SecretStreamEncryptor {
+  _startCodec(publicKey) {
+    return native.SecretStreamFileEncryptor.boxSeal(publicKey);
+  }
+}
+
+/** `crypto_box384` counterpart of `BoxEncryptor`. */
+class Box384Encryptor extends SecretStreamEncryptor {
+  _startCodec(publicKey) {
+    return native.SecretStreamFileEncryptor.box384Seal(publicKey);
+  }
+}
+
+/** `crypto_box512` counterpart of `BoxEncryptor`. */
+class Box512Encryptor extends SecretStreamEncryptor {
+  _startCodec(publicKey) {
+    return native.SecretStreamFileEncryptor.box512Seal(publicKey);
+  }
+}
+
+/**
+ * A passphrase file (D-219/D-240) - the bytes `uacrypt encrypt --passphrase` writes. The
+ * constructor runs Argon2id (256 MiB, t=3, about a second) on the calling thread.
+ */
+class PassphraseEncryptor extends SecretStreamEncryptor {
+  _startCodec(passphrase) {
+    return native.SecretStreamFileEncryptor.passphraseSeal(passphrase);
+  }
+}
+
+/**
+ * Collects the bytes in front of the stream file, then opens the codec with them. The secret is
+ * held only until then.
+ */
+class PrefixedDecryptor extends SecretStreamDecryptor {
+  _startCodec(secret) {
+    this._secret = secret;
+    return null;
+  }
+
+  _openPrefixed(prefix) {
+    const dec = this._openCodec(this._secret, prefix);
+    this._secret = null;
+    return dec;
+  }
+}
+
+/** Reads a `crypto_box` stream (or a `boxSeal` blob) with bounded memory. */
+class BoxDecryptor extends PrefixedDecryptor {
+  constructor(secretKey, options) {
+    checkLength(secretKey, 32, 'secretKey');
+    super(secretKey, options);
+    this._prefixBytes = native.BOX_OPEN_STREAM_PREFIX_BYTES;
+    this._prefixName = 'sealed message';
+  }
+
+  _openCodec(secretKey, prefix) {
+    return native.SecretStreamFileDecryptor.boxOpen(secretKey, prefix);
+  }
+}
+
+/** `crypto_box384` counterpart of `BoxDecryptor`. */
+class Box384Decryptor extends PrefixedDecryptor {
+  constructor(secretKey, options) {
+    checkLength(secretKey, 48, 'secretKey');
+    super(secretKey, options);
+    this._prefixBytes = native.BOX384_OPEN_STREAM_PREFIX_BYTES;
+    this._prefixName = 'sealed message';
+  }
+
+  _openCodec(secretKey, prefix) {
+    return native.SecretStreamFileDecryptor.box384Open(secretKey, prefix);
+  }
+}
+
+/** `crypto_box512` counterpart of `BoxDecryptor`. */
+class Box512Decryptor extends PrefixedDecryptor {
+  constructor(secretKey, options) {
+    checkLength(secretKey, 64, 'secretKey');
+    super(secretKey, options);
+    this._prefixBytes = native.BOX512_OPEN_STREAM_PREFIX_BYTES;
+    this._prefixName = 'sealed message';
+  }
+
+  _openCodec(secretKey, prefix) {
+    return native.SecretStreamFileDecryptor.box512Open(secretKey, prefix);
+  }
+}
+
+/**
+ * Reads a passphrase file. The header is checked before Argon2 runs (on the calling thread, once
+ * the header has arrived); a wrong passphrase errors at the first record.
+ */
+class PassphraseDecryptor extends PrefixedDecryptor {
+  constructor(passphrase, options) {
+    super(passphrase, options);
+    this._prefixBytes = native.PASSPHRASE_FILE_HEADER_BYTES;
+    this._prefixName = 'passphrase file header';
+  }
+
+  _openCodec(passphrase, header) {
+    return native.SecretStreamFileDecryptor.passphraseOpen(header, passphrase);
+  }
+}
+
+module.exports = {
+  SecretStreamEncryptor,
+  SecretStreamDecryptor,
+  BoxEncryptor,
+  BoxDecryptor,
+  Box384Encryptor,
+  Box384Decryptor,
+  Box512Encryptor,
+  Box512Decryptor,
+  PassphraseEncryptor,
+  PassphraseDecryptor,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dstu-core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Node.js bindings for dstu-core (Ukrainian DSTU cryptographic standards)",
   "main": "js/index.js",
@@ -47,9 +47,9 @@
     "prepublishOnly": "napi prepublish -t npm --skip-gh-release"
   },
   "optionalDependencies": {
-    "dstu-core-linux-x64-gnu": "0.4.0",
-    "dstu-core-darwin-arm64": "0.4.0",
-    "dstu-core-win32-x64-msvc": "0.4.0",
-    "dstu-core-linux-arm64-gnu": "0.4.0"
+    "dstu-core-linux-x64-gnu": "0.5.0",
+    "dstu-core-darwin-arm64": "0.5.0",
+    "dstu-core-win32-x64-msvc": "0.5.0",
+    "dstu-core-linux-arm64-gnu": "0.5.0"
   }
 }