@syncfusion/ej2-office-common 35.1.37

package/src/encryption/crypto-primitives.js

@@ -0,0 +1,302 @@
+/*
+ * Hash / HMAC / AES-CBC primitives for Agile OFFCRYPTO.
+ *
+ * @remarks
+ * [MS-OFFCRYPTO] §2.3.4.11–§2.3.4.15 pads AES-CBC plaintexts with **0x00** to
+ * `blockSize`, not PKCS #7. Node's Web Crypto `AES-CBC` decrypt expects PKCS #7
+ * and rejects Office ciphertexts. This module therefore uses the **Node.js
+ * built-in** `node:crypto` (`createHash`, `createHmac`, `createDecipheriv` with
+ * `setAutoPadding(false)`). That is a platform API, not a new npm dependency
+ * (ADR / dependencies policy). No third-party crypto packages.
+ *
+ * Supported for v1: AES-128/192/256 + CBC; SHA-1 / SHA-256 / SHA-384 / SHA-512.
+ * Symbols re-exported from the encryption package entry are public; keep
+ * `@private`
+ * only on helpers that are not part of that surface.
+ *
+ * @packageDocumentation
+ */
+var __values = (this && this.__values) || function (o) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator], i = 0;
+    if (m) return m.call(o);
+    return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+};
+import { UnsupportedEncryptionError } from './errors';
+import { IV_PAD_BYTE, KEY_PAD_BYTE } from './agile-constants';
+function __nodeCrypto() {
+    try {
+        return require('crypto');
+    }
+    catch (e) {
+        throw new Error('Node crypto is required for Agile encryption');
+    }
+}
+var _a = __nodeCrypto(), createCipheriv = _a.createCipheriv, createDecipheriv = _a.createDecipheriv, createHash = _a.createHash, createHmac = _a.createHmac;
+var HASH_TO_NODE = {
+    'SHA-1': 'sha1',
+    SHA256: 'sha256',
+    SHA384: 'sha384',
+    SHA512: 'sha512',
+};
+var HASH_DIGEST_BYTES = {
+    'SHA-1': 20,
+    SHA256: 32,
+    SHA384: 48,
+    SHA512: 64,
+};
+/**
+ * Maps OFFCRYPTO hashAlgorithm attribute to an internal name.
+ *
+ * @throws {UnsupportedEncryptionError} When the algorithm is not in the v1 set.
+ */
+export function resolveHashAlgorithm(name) {
+    switch (name) {
+        case 'SHA-1':
+        case 'SHA1':
+            return 'SHA-1';
+        case 'SHA256':
+            return 'SHA256';
+        case 'SHA384':
+            return 'SHA384';
+        case 'SHA512':
+            return 'SHA512';
+        default:
+            throw new UnsupportedEncryptionError("Unsupported OFFCRYPTO hashAlgorithm: " + sanitizeAlgToken(name));
+    }
+}
+/**
+ * Validates cipherAlgorithm + cipherChaining for v1 (AES + CBC only).
+ *
+ * @throws {UnsupportedEncryptionError} When not AES/CBC.
+ */
+export function assertSupportedCipher(cipherAlgorithm, cipherChaining) {
+    if (cipherAlgorithm !== 'AES') {
+        throw new UnsupportedEncryptionError("Unsupported OFFCRYPTO cipherAlgorithm: " + sanitizeAlgToken(cipherAlgorithm));
+    }
+    if (cipherChaining !== 'ChainingModeCBC') {
+        throw new UnsupportedEncryptionError("Unsupported OFFCRYPTO cipherChaining: " + sanitizeAlgToken(cipherChaining));
+    }
+}
+/**
+ * Validates AES keyBits (128 / 192 / 256).
+ *
+ * @throws {UnsupportedEncryptionError} When key length is not a supported AES size.
+ */
+export function assertAesKeyBits(keyBits) {
+    if (keyBits !== 128 && keyBits !== 192 && keyBits !== 256) {
+        throw new UnsupportedEncryptionError("Unsupported OFFCRYPTO AES keyBits: " + String(keyBits));
+    }
+}
+/** Digest length in bytes for a resolved hash algorithm. */
+export function hashDigestLength(hash) {
+    return HASH_DIGEST_BYTES[hash];
+}
+/** One-shot hash. */
+export function hashBytes(hash, data) {
+    var h = createHash(HASH_TO_NODE[hash]);
+    h.update(data);
+    return new Uint8Array(h.digest());
+}
+/** HMAC over message with key (DataIntegrity §2.3.4.14). */
+export function hmacBytes(hash, key, message) {
+    var h = createHmac(HASH_TO_NODE[hash], Buffer.from(key));
+    h.update(message);
+    return new Uint8Array(h.digest());
+}
+/**
+ * Concatenates byte arrays.
+ *
+ * @public
+ */
+export function concatBytes() {
+    var parts = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        parts[_i] = arguments[_i];
+    }
+    var e_1, _a, e_2, _b;
+    var total = 0;
+    try {
+        for (var parts_1 = __values(parts), parts_1_1 = parts_1.next(); !parts_1_1.done; parts_1_1 = parts_1.next()) {
+            var p = parts_1_1.value;
+            total += p.byteLength;
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (parts_1_1 && !parts_1_1.done && (_a = parts_1.return)) _a.call(parts_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    var out = new Uint8Array(total);
+    var offset = 0;
+    try {
+        for (var parts_2 = __values(parts), parts_2_1 = parts_2.next(); !parts_2_1.done; parts_2_1 = parts_2.next()) {
+            var p = parts_2_1.value;
+            out.set(p, offset);
+            offset += p.byteLength;
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (parts_2_1 && !parts_2_1.done && (_b = parts_2.return)) _b.call(parts_2);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    return out;
+}
+/**
+ * Encodes a JavaScript string as UTF-16LE (Unicode password bytes, §2.3.4.11).
+ */
+export function encodePasswordUtf16Le(password) {
+    var out = new Uint8Array(password.length * 2);
+    for (var i = 0; i < password.length; i++) {
+        var code = password.charCodeAt(i);
+        out[i * 2] = code & 0xff;
+        out[i * 2 + 1] = (code >>> 8) & 0xff;
+    }
+    return out;
+}
+/**
+ * Password-based encryption key (§2.3.4.11).
+ *
+ * H0 = H(salt + password); Hn = H(iterator LE u32 + Hn-1) for spinCount iterations;
+ * Hfinal = H(Hn + blockKey); pad/truncate to keyBits/8 with 0x36.
+ */
+export function deriveAgileKey(hash, salt, passwordUtf16Le, spinCount, blockKey, keyBits) {
+    var hn = hashBytes(hash, concatBytes(salt, passwordUtf16Le));
+    var iterator = new Uint8Array(4);
+    var iteratorView = new DataView(iterator.buffer);
+    for (var i = 0; i < spinCount; i++) {
+        iteratorView.setUint32(0, i, true);
+        hn = hashBytes(hash, concatBytes(iterator, hn));
+    }
+    var hfinal = hashBytes(hash, concatBytes(hn, blockKey));
+    return padOrTruncate(hfinal, keyBits / 8, KEY_PAD_BYTE);
+}
+/**
+ * Initialization vector (§2.3.4.12).
+ *
+ * With blockKey: IV = H(keySalt + blockKey); without: IV = keySalt.
+ * Pad/truncate to blockSize with 0x36.
+ */
+export function deriveAgileIv(hash, keySalt, blockKey, blockSize) {
+    var raw = blockKey === undefined ? keySalt : hashBytes(hash, concatBytes(keySalt, blockKey));
+    return padOrTruncate(raw, blockSize, IV_PAD_BYTE);
+}
+/**
+ * AES-CBC decrypt with zero padding (no PKCS #7 strip).
+ *
+ * @param key - AES key (16/24/32 bytes).
+ * @param iv - IV of blockSize bytes (AES block is 16; OFFCRYPTO blockSize is 16 for AES).
+ * @param ciphertext - Length MUST be a multiple of 16.
+ * @returns Plaintext of the same length as ciphertext (including zero pad).
+ */
+export function aesCbcDecrypt(key, iv, ciphertext) {
+    if (ciphertext.byteLength === 0) {
+        return new Uint8Array(0);
+    }
+    if (ciphertext.byteLength % 16 !== 0) {
+        throw new UnsupportedEncryptionError('OFFCRYPTO AES-CBC ciphertext length is not block-aligned');
+    }
+    if (iv.byteLength !== 16) {
+        throw new UnsupportedEncryptionError('OFFCRYPTO AES-CBC IV must be 16 bytes');
+    }
+    var algo = aesAlgorithmName(key.byteLength);
+    var decipher = createDecipheriv(algo, Buffer.from(key), Buffer.from(iv));
+    decipher.setAutoPadding(false);
+    var part1 = decipher.update(Buffer.from(ciphertext));
+    var part2 = decipher.final();
+    if (part2.byteLength === 0) {
+        return new Uint8Array(part1);
+    }
+    var out = new Uint8Array(part1.byteLength + part2.byteLength);
+    out.set(part1, 0);
+    out.set(part2, part1.byteLength);
+    return out;
+}
+/**
+ * AES-CBC encrypt with zero padding (no PKCS #7).
+ *
+ * @remarks
+ * Used by test fixture builders and host encrypt harnesses. Same zero-pad
+ * rules as decrypt ([MS-OFFCRYPTO] §2.3.4.13 / §2.3.4.15).
+ *
+ * @public
+ */
+export function aesCbcEncrypt(key, iv, plaintext) {
+    if (iv.byteLength !== 16) {
+        throw new UnsupportedEncryptionError('OFFCRYPTO AES-CBC IV must be 16 bytes');
+    }
+    var blockSize = 16;
+    var paddedLen = plaintext.byteLength === 0
+        ? blockSize
+        : Math.ceil(plaintext.byteLength / blockSize) * blockSize;
+    var padded = new Uint8Array(paddedLen);
+    padded.set(plaintext, 0);
+    // remaining bytes stay 0x00 (Agile zero-pad, §2.3.4.13 / §2.3.4.15).
+    var algo = aesAlgorithmName(key.byteLength);
+    var cipher = createCipheriv(algo, Buffer.from(key), Buffer.from(iv));
+    cipher.setAutoPadding(false);
+    var part1 = cipher.update(Buffer.from(padded));
+    var part2 = cipher.final();
+    if (part2.byteLength === 0) {
+        return new Uint8Array(part1);
+    }
+    var out = new Uint8Array(part1.byteLength + part2.byteLength);
+    out.set(part1, 0);
+    out.set(part2, part1.byteLength);
+    return out;
+}
+/**
+ * Constant-time comparison of two equal-length buffers.
+ * Returns false when lengths differ (not constant-time on length).
+ */
+export function timingSafeEqual(a, b) {
+    if (a.byteLength !== b.byteLength) {
+        return false;
+    }
+    var diff = 0;
+    for (var i = 0; i < a.byteLength; i++) {
+        // Lengths already equal; index is in range. Avoid non-null assertions.
+        var left = (a[i] != null ? a[i] : 0);
+        var right = (b[i] != null ? b[i] : 0);
+        diff |= left ^ right;
+    }
+    return diff === 0;
+}
+function padOrTruncate(data, size, padByte) {
+    if (data.byteLength === size) {
+        return data;
+    }
+    if (data.byteLength > size) {
+        return data.subarray(0, size);
+    }
+    var out = new Uint8Array(size);
+    out.set(data, 0);
+    out.fill(padByte, data.byteLength);
+    return out;
+}
+function aesAlgorithmName(keyBytes) {
+    switch (keyBytes) {
+        case 16:
+            return 'aes-128-cbc';
+        case 24:
+            return 'aes-192-cbc';
+        case 32:
+            return 'aes-256-cbc';
+        default:
+            throw new UnsupportedEncryptionError('Unsupported AES key length');
+    }
+}
+/** Strip control chars so algorithm tokens cannot smuggle secrets into messages. */
+function sanitizeAlgToken(token) {
+    var cleaned = token.replace(/[^\w.\-:/+]/g, '').slice(0, 64);
+    return cleaned.length > 0 ? cleaned : '(unrecognized)';
+}

package/src/encryption/decrypt-encrypted-package.d.ts

@@ -0,0 +1,16 @@
+import { DecryptSecurityLimits } from './errors';
+import { AgileDataIntegrity, AgileKeyData } from './agile-encryption-info';
+/**
+ * Decrypts EncryptedPackage ciphertext to plain OPC ZIP bytes.
+ *
+ * @param encryptedPackage - Full EncryptedPackage stream bytes.
+ * @param secretKey - Intermediate key from password unlock (keyBits/8).
+ * @param keyData - KeyData from EncryptionInfo.
+ * @param dataIntegrity - Optional integrity structure.
+ * @param limits - Security limits (single-part / total uncompressed caps).
+ *
+ * @throws {PackageLimitError} When StreamSize or ciphertext exceeds limits.
+ * @throws {InvalidPasswordError} When DataIntegrity HMAC fails (fail-closed).
+ * @throws {EncryptedPackageError} When stream structure is invalid.
+ */
+export declare function decryptEncryptedPackageStream(encryptedPackage: Uint8Array, secretKey: Uint8Array, keyData: AgileKeyData, dataIntegrity: AgileDataIntegrity | undefined, limits: DecryptSecurityLimits): Uint8Array;

package/src/encryption/decrypt-encrypted-package.js

@@ -0,0 +1,138 @@
+/*
+ * Decrypt EncryptedPackage stream ([MS-OFFCRYPTO] §2.3.4.4, §2.3.4.15)
+ * and optional DataIntegrity HMAC (§2.3.4.14).
+ *
+ * @remarks
+ * Layout: 8-byte little-endian StreamSize (u64) + encrypted payload.
+ * Payload is segmented in 4096-byte blocks; each segment uses blockKey =
+ * segment number as LE u32 with KeyData.saltValue for the IV
+ * (§2.3.4.12 / §2.3.4.15). Secret key is the intermediate key from the
+ * password key encryptor.
+ *
+ * DataIntegrity: decrypt encryptedHmacKey with blockKey BLOCK_KEY_HMAC_KEY
+ * and KeyData; decrypt encryptedHmacValue with BLOCK_KEY_HMAC_VALUE; HMAC
+ * the **entire** EncryptedPackage stream (including StreamSize prefix)
+ * with KeyData.hashAlgorithm; compare → fail closed as InvalidPasswordError.
+ *
+ * @private
+ */
+import { EncryptedPackageError, InvalidPasswordError, PackageLimitError, } from './errors';
+import { BLOCK_KEY_HMAC_KEY, BLOCK_KEY_HMAC_VALUE, ENCRYPTED_PACKAGE_SEGMENT_SIZE, } from './agile-constants';
+import { aesCbcDecrypt, deriveAgileIv, hashDigestLength, hmacBytes, timingSafeEqual, } from './crypto-primitives';
+var STREAM_SIZE_BYTES = 8;
+/**
+ * Decrypts EncryptedPackage ciphertext to plain OPC ZIP bytes.
+ *
+ * @param encryptedPackage - Full EncryptedPackage stream bytes.
+ * @param secretKey - Intermediate key from password unlock (keyBits/8).
+ * @param keyData - KeyData from EncryptionInfo.
+ * @param dataIntegrity - Optional integrity structure.
+ * @param limits - Security limits (single-part / total uncompressed caps).
+ *
+ * @throws {PackageLimitError} When StreamSize or ciphertext exceeds limits.
+ * @throws {InvalidPasswordError} When DataIntegrity HMAC fails (fail-closed).
+ * @throws {EncryptedPackageError} When stream structure is invalid.
+ */
+export function decryptEncryptedPackageStream(encryptedPackage, secretKey, keyData, dataIntegrity, limits) {
+    if (encryptedPackage.byteLength < STREAM_SIZE_BYTES) {
+        throw new EncryptedPackageError('EncryptedPackage stream is truncated');
+    }
+    // Hard cap ciphertext before any crypto work.
+    var maxCipher = Math.max(limits.singlePartUncompressedBytes, limits.totalUncompressedBytes);
+    if (encryptedPackage.byteLength >
+        maxCipher + STREAM_SIZE_BYTES + ENCRYPTED_PACKAGE_SEGMENT_SIZE) {
+        throw new PackageLimitError('singlePartUncompressedBytes', {
+            actual: encryptedPackage.byteLength,
+        });
+    }
+    var view = new DataView(encryptedPackage.buffer, encryptedPackage.byteOffset, encryptedPackage.byteLength);
+    // StreamSize is u64 LE; JS safe integer covers realistic packages under limits.
+    var streamSizeLow = view.getUint32(0, true);
+    var streamSizeHigh = view.getUint32(4, true);
+    if (streamSizeHigh !== 0) {
+        throw new PackageLimitError('singlePartUncompressedBytes', {
+            actual: Number.MAX_SAFE_INTEGER,
+        });
+    }
+    var streamSize = streamSizeLow;
+    if (streamSize > limits.singlePartUncompressedBytes) {
+        throw new PackageLimitError('singlePartUncompressedBytes', { actual: streamSize });
+    }
+    if (streamSize > limits.totalUncompressedBytes) {
+        throw new PackageLimitError('totalUncompressedBytes', { actual: streamSize });
+    }
+    var ciphertext = encryptedPackage.subarray(STREAM_SIZE_BYTES);
+    if (ciphertext.byteLength === 0 && streamSize > 0) {
+        throw new EncryptedPackageError('EncryptedPackage has StreamSize but no ciphertext');
+    }
+    // DataIntegrity over entire EncryptedPackage including StreamSize (§2.3.4.14).
+    if (dataIntegrity !== undefined) {
+        verifyDataIntegrity(encryptedPackage, secretKey, keyData, dataIntegrity);
+    }
+    var plain = decryptSegments(ciphertext, secretKey, keyData);
+    if (plain.byteLength < streamSize) {
+        throw new EncryptedPackageError('Decrypted EncryptedPackage is shorter than StreamSize');
+    }
+    return plain.subarray(0, streamSize);
+}
+function decryptSegments(ciphertext, secretKey, keyData) {
+    var segmentSize = ENCRYPTED_PACKAGE_SEGMENT_SIZE;
+    var blockSize = keyData.blockSize;
+    var out = new Uint8Array(ciphertext.byteLength);
+    var outOffset = 0;
+    var segmentIndex = 0;
+    var offset = 0;
+    while (offset < ciphertext.byteLength) {
+        var remaining = ciphertext.byteLength - offset;
+        // Last segment may be shorter but must still be block-aligned (zero-pad encrypt).
+        var segmentLen = remaining > segmentSize ? segmentSize : remaining;
+        // If not last full logical segment and remaining > segmentSize we took segmentSize.
+        // Ciphertext of each segment is rounded up to blockSize on encrypt; remaining should
+        // already be multiple of blockSize for every piece.
+        if (segmentLen % blockSize !== 0) {
+            // Pad expectation: encryptor wrote full blocks; tolerate by rounding down if corrupt.
+            throw new EncryptedPackageError('EncryptedPackage segment is not block-aligned');
+        }
+        var segmentCt = ciphertext.subarray(offset, offset + segmentLen);
+        var blockKey = segmentBlockKey(segmentIndex);
+        var iv = deriveAgileIv(keyData.hashAlgorithm, keyData.saltValue, blockKey, blockSize);
+        var segmentPt = aesCbcDecrypt(secretKey, iv, segmentCt);
+        out.set(segmentPt, outOffset);
+        outOffset += segmentPt.byteLength;
+        offset += segmentLen;
+        segmentIndex += 1;
+    }
+    return out.subarray(0, outOffset);
+}
+function segmentBlockKey(segmentIndex) {
+    var buf = new Uint8Array(4);
+    new DataView(buf.buffer).setUint32(0, segmentIndex >>> 0, true);
+    return buf;
+}
+/**
+ * §2.3.4.14 DataIntegrity verification.
+ *
+ * Fail-closed: HMAC mismatch → InvalidPasswordError (same public class as wrong
+ * password; do not leak integrity vs password distinction).
+ */
+function verifyDataIntegrity(encryptedPackage, secretKey, keyData, dataIntegrity) {
+    var hashAlgorithm = keyData.hashAlgorithm, saltValue = keyData.saltValue, blockSize = keyData.blockSize;
+    var ivHmacKey = deriveAgileIv(hashAlgorithm, saltValue, BLOCK_KEY_HMAC_KEY, blockSize);
+    var hmacKeyDecrypted = aesCbcDecrypt(secretKey, ivHmacKey, dataIntegrity.encryptedHmacKey);
+    // HMAC key length is hash digest size; truncated after decrypt (zero-padded block).
+    var digestLen = hashDigestLength(hashAlgorithm);
+    if (hmacKeyDecrypted.byteLength < digestLen) {
+        throw new InvalidPasswordError();
+    }
+    var hmacKey = hmacKeyDecrypted.subarray(0, digestLen);
+    var ivHmacValue = deriveAgileIv(hashAlgorithm, saltValue, BLOCK_KEY_HMAC_VALUE, blockSize);
+    var hmacValueDecrypted = aesCbcDecrypt(secretKey, ivHmacValue, dataIntegrity.encryptedHmacValue);
+    if (hmacValueDecrypted.byteLength < digestLen) {
+        throw new InvalidPasswordError();
+    }
+    var expectedHmac = hmacValueDecrypted.subarray(0, digestLen);
+    var actualHmac = hmacBytes(hashAlgorithm, hmacKey, encryptedPackage);
+    if (!timingSafeEqual(actualHmac.subarray(0, digestLen), expectedHmac)) {
+        throw new InvalidPasswordError();
+    }
+}

package/src/encryption/encryption-info-xml.d.ts

@@ -0,0 +1,21 @@
+import { DecryptSecurityLimits } from './errors';
+/** Parsed element node used by Agile EncryptionInfo mapping. */
+export interface XmlElement {
+    readonly kind: 'element';
+    readonly localName: string;
+    readonly namespaceUri: string;
+    readonly attributes: ReadonlyArray<XmlAttribute>;
+    readonly children: ReadonlyArray<XmlElement>;
+}
+export interface XmlAttribute {
+    readonly localName: string;
+    readonly namespaceUri: string;
+    readonly value: string;
+}
+/**
+ * Parses EncryptionInfo UTF-8 XML into a single root element tree.
+ *
+ * @throws {EncryptedPackageError} Malformed XML.
+ * @throws {PackageLimitError} Nesting / attribute / text limits.
+ */
+export declare function parseEncryptionInfoXml(xmlText: string, limits: DecryptSecurityLimits, partName?: string): XmlElement;