@opentdf/sdk 0.12.0 → 0.13.0-beta.119

package/tdf3/src/crypto/core/rsa.ts

@@ -0,0 +1,144 @@
+import { Binary } from '../../binary.js';
+import {
+  type KeyAlgorithm,
+  type KeyPair,
+  MIN_ASYMMETRIC_KEY_SIZE_BITS,
+  type PrivateKey,
+  type PublicKey,
+  type SymmetricKey,
+} from '../declarations.js';
+import { ConfigurationError } from '../../../../src/errors.js';
+import { unwrapKey, unwrapSymmetricKey, wrapPrivateKey, wrapPublicKey } from './keys.js';
+
+const ENC_DEC_METHODS: KeyUsage[] = ['encrypt', 'decrypt'];
+const SIGN_VERIFY_METHODS: KeyUsage[] = ['sign', 'verify'];
+
+/**
+ * Get a DOMString representing the algorithm to use for an
+ * asymmetric key generation.
+ */
+export function rsaOaepSha1(
+  modulusLength: number = MIN_ASYMMETRIC_KEY_SIZE_BITS
+): RsaHashedKeyGenParams {
+  if (!modulusLength || modulusLength < MIN_ASYMMETRIC_KEY_SIZE_BITS) {
+    throw new ConfigurationError('Invalid key size requested');
+  }
+  return {
+    name: 'RSA-OAEP',
+    hash: {
+      name: 'SHA-1',
+    },
+    modulusLength,
+    // 24 bit representation of 65537
+    publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
+  };
+}
+
+export function rsaPkcs1Sha256(
+  modulusLength: number = MIN_ASYMMETRIC_KEY_SIZE_BITS
+): RsaHashedKeyGenParams {
+  if (!modulusLength || modulusLength < MIN_ASYMMETRIC_KEY_SIZE_BITS) {
+    throw new ConfigurationError('Invalid key size requested');
+  }
+  return {
+    name: 'RSASSA-PKCS1-v1_5',
+    hash: {
+      name: 'SHA-256',
+    },
+    modulusLength,
+    // 24 bit representation of 65537
+    publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
+  };
+}
+
+/**
+ * Generate an RSA key pair
+ * @see    {@link https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey}
+ * @param  size in bits
+ */
+export async function generateKeyPair(size?: number): Promise<KeyPair> {
+  const keySize = size || MIN_ASYMMETRIC_KEY_SIZE_BITS;
+  const algoDomString = rsaOaepSha1(keySize);
+  const keyPair = await crypto.subtle.generateKey(algoDomString, true, ENC_DEC_METHODS);
+
+  // Map to supported algorithm sizes
+  let algorithm: KeyAlgorithm;
+  if (keySize === 2048) {
+    algorithm = 'rsa:2048';
+  } else if (keySize === 4096) {
+    algorithm = 'rsa:4096';
+  } else {
+    throw new ConfigurationError(
+      `Unsupported RSA key size: ${keySize}. Only 2048 and 4096 are supported.`
+    );
+  }
+
+  return {
+    publicKey: wrapPublicKey(keyPair.publicKey, algorithm),
+    privateKey: wrapPrivateKey(keyPair.privateKey, algorithm),
+  };
+}
+
+/**
+ * Generate an RSA key pair suitable for signatures
+ * @see    {@link https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey}
+ */
+export async function generateSigningKeyPair(): Promise<KeyPair> {
+  const rsaParams = rsaPkcs1Sha256(2048);
+  const keyPair = await crypto.subtle.generateKey(rsaParams, true, SIGN_VERIFY_METHODS);
+
+  const algorithm: KeyAlgorithm = 'rsa:2048';
+  return {
+    publicKey: wrapPublicKey(keyPair.publicKey, algorithm),
+    privateKey: wrapPrivateKey(keyPair.privateKey, algorithm),
+  };
+}
+
+/**
+ * Encrypt using a public key (RSA-OAEP).
+ * Accepts Binary or SymmetricKey for key wrapping.
+ * @param payload Payload to encrypt (Binary) or symmetric key to wrap (SymmetricKey)
+ * @param publicKey Opaque public key
+ * @return Encrypted payload
+ */
+export async function encryptWithPublicKey(
+  payload: Binary | SymmetricKey,
+  publicKey: PublicKey
+): Promise<Binary> {
+  let payloadBuffer: BufferSource;
+
+  // Handle SymmetricKey unwrapping
+  if ('_brand' in payload && payload._brand === 'SymmetricKey') {
+    // Pass Uint8Array directly — Web Crypto respects byteOffset/byteLength on typed array views.
+    payloadBuffer = unwrapSymmetricKey(payload);
+  } else {
+    // Binary payload
+    payloadBuffer = (payload as Binary).asArrayBuffer();
+  }
+
+  const cryptoKey = unwrapKey(publicKey);
+  const result = await crypto.subtle.encrypt({ name: 'RSA-OAEP' }, cryptoKey, payloadBuffer);
+  return Binary.fromArrayBuffer(result);
+}
+
+/**
+ * Decrypt a public-key encrypted payload with a private key
+ * @param  encryptedPayload  Payload to decrypt
+ * @param  privateKey        Opaque private key
+ * @return Decrypted payload
+ */
+export async function decryptWithPrivateKey(
+  encryptedPayload: Binary,
+  privateKey: PrivateKey
+): Promise<Binary> {
+  console.assert(typeof encryptedPayload === 'object', 'encryptedPayload must be object');
+
+  const cryptoKey = unwrapKey(privateKey);
+  const payload = await crypto.subtle.decrypt(
+    { name: 'RSA-OAEP' },
+    cryptoKey,
+    encryptedPayload.asArrayBuffer()
+  );
+  const bufferView = new Uint8Array(payload);
+  return Binary.fromArrayBuffer(bufferView.buffer);
+}

package/tdf3/src/crypto/core/signing.ts

@@ -0,0 +1,214 @@
+import {
+  type AsymmetricSigningAlgorithm,
+  type PrivateKey,
+  type PublicKey,
+} from '../declarations.js';
+import { ConfigurationError } from '../../../../src/errors.js';
+import { unwrapKey } from './keys.js';
+
+/**
+ * Get the Web Crypto algorithm parameters for a signing algorithm.
+ */
+function getSigningAlgorithmParams(algorithm: AsymmetricSigningAlgorithm): {
+  importParams: RsaHashedImportParams | EcKeyImportParams;
+  signParams: AlgorithmIdentifier | EcdsaParams;
+} {
+  switch (algorithm) {
+    case 'RS256':
+      return {
+        importParams: { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+        signParams: 'RSASSA-PKCS1-v1_5',
+      };
+    case 'ES256':
+      return {
+        importParams: { name: 'ECDSA', namedCurve: 'P-256' },
+        signParams: { name: 'ECDSA', hash: 'SHA-256' } as EcdsaParams,
+      };
+    case 'ES384':
+      return {
+        importParams: { name: 'ECDSA', namedCurve: 'P-384' },
+        signParams: { name: 'ECDSA', hash: 'SHA-384' } as EcdsaParams,
+      };
+    case 'ES512':
+      return {
+        importParams: { name: 'ECDSA', namedCurve: 'P-521' },
+        signParams: { name: 'ECDSA', hash: 'SHA-512' } as EcdsaParams,
+      };
+    default:
+      throw new ConfigurationError(`Unsupported signing algorithm: ${algorithm}`);
+  }
+}
+
+/**
+ * Convert IEEE P1363 signature format (used by WebCrypto ECDSA) to DER format (used by JWT).
+ * RS256 signatures don't need conversion.
+ */
+function ieeeP1363ToDer(signature: Uint8Array, algorithm: AsymmetricSigningAlgorithm): Uint8Array {
+  if (algorithm === 'RS256') {
+    return signature;
+  }
+
+  // IEEE P1363: r || s where each is padded to key size
+  const halfLen = signature.length / 2;
+  const r = signature.slice(0, halfLen);
+  const s = signature.slice(halfLen);
+
+  // Remove leading zeros but keep one if the high bit is set
+  const trimLeadingZeros = (arr: Uint8Array): Uint8Array => {
+    let i = 0;
+    while (i < arr.length - 1 && arr[i] === 0) i++;
+    return arr.slice(i);
+  };
+
+  let rTrimmed = trimLeadingZeros(r);
+  let sTrimmed = trimLeadingZeros(s);
+
+  // Add leading zero if high bit is set (to keep positive in DER)
+  if (rTrimmed[0] & 0x80) {
+    const padded = new Uint8Array(rTrimmed.length + 1);
+    padded.set(rTrimmed, 1);
+    rTrimmed = padded;
+  }
+  if (sTrimmed[0] & 0x80) {
+    const padded = new Uint8Array(sTrimmed.length + 1);
+    padded.set(sTrimmed, 1);
+    sTrimmed = padded;
+  }
+
+  // DER SEQUENCE: 0x30 [length] [r INTEGER] [s INTEGER]
+  // INTEGER: 0x02 [length] [value]
+  const rDer = new Uint8Array([0x02, rTrimmed.length, ...rTrimmed]);
+  const sDer = new Uint8Array([0x02, sTrimmed.length, ...sTrimmed]);
+
+  const seqLen = rDer.length + sDer.length;
+  // DER length: short-form for < 128, long-form (0x81 nn) for 128-255.
+  // ECDSA sequences never exceed 255 bytes for any supported curve.
+  const lenBytes = seqLen < 128 ? new Uint8Array([seqLen]) : new Uint8Array([0x81, seqLen]);
+  const result = new Uint8Array(1 + lenBytes.length + seqLen);
+  result[0] = 0x30;
+  result.set(lenBytes, 1);
+  result.set(rDer, 1 + lenBytes.length);
+  result.set(sDer, 1 + lenBytes.length + rDer.length);
+
+  return result;
+}
+
+/**
+ * Convert DER signature format (used by JWT) to IEEE P1363 format (used by WebCrypto ECDSA).
+ * RS256 signatures don't need conversion.
+ */
+function derToIeeeP1363(signature: Uint8Array, algorithm: AsymmetricSigningAlgorithm): Uint8Array {
+  if (algorithm === 'RS256') {
+    return signature;
+  }
+
+  // Determine the expected component length based on algorithm
+  let componentLen: number;
+  switch (algorithm) {
+    case 'ES256':
+      componentLen = 32;
+      break;
+    case 'ES384':
+      componentLen = 48;
+      break;
+    case 'ES512':
+      componentLen = 66;
+      break;
+    default:
+      throw new ConfigurationError(`Unsupported algorithm for DER conversion: ${algorithm}`);
+  }
+
+  if (signature[0] !== 0x30) {
+    throw new ConfigurationError('Invalid DER signature: expected SEQUENCE');
+  }
+
+  // Skip SEQUENCE tag, then parse DER length (short- or long-form).
+  let offset = 1;
+  if (signature[offset] & 0x80) {
+    // Long-form: low 7 bits = number of subsequent length bytes.
+    const lenBytesCount = signature[offset] & 0x7f;
+    if (lenBytesCount === 0 || lenBytesCount > 4) {
+      throw new ConfigurationError('Invalid DER signature: invalid long-form length');
+    }
+    offset += 1 + lenBytesCount;
+    if (offset > signature.length) {
+      throw new ConfigurationError('Invalid DER signature: length bytes exceed signature length');
+    }
+  } else {
+    // Short-form: single length byte.
+    offset += 1;
+  }
+
+  // Parse r INTEGER
+  if (signature[offset] !== 0x02) {
+    throw new ConfigurationError('Invalid DER signature: expected INTEGER for r');
+  }
+  const rLen = signature[offset + 1];
+  offset += 2;
+  let r = signature.slice(offset, offset + rLen);
+  offset += rLen;
+
+  // Parse s INTEGER
+  if (signature[offset] !== 0x02) {
+    throw new ConfigurationError('Invalid DER signature: expected INTEGER for s');
+  }
+  const sLen = signature[offset + 1];
+  offset += 2;
+  let s = signature.slice(offset, offset + sLen);
+
+  // Remove leading zero padding if present
+  if (r[0] === 0 && r.length > componentLen) {
+    r = r.slice(1);
+  }
+  if (s[0] === 0 && s.length > componentLen) {
+    s = s.slice(1);
+  }
+
+  // Pad to component length
+  const result = new Uint8Array(componentLen * 2);
+  result.set(r, componentLen - r.length);
+  result.set(s, componentLen * 2 - s.length);
+
+  return result;
+}
+
+/**
+ * Sign data with an asymmetric private key.
+ */
+export async function sign(
+  data: Uint8Array,
+  privateKey: PrivateKey,
+  algorithm: AsymmetricSigningAlgorithm
+): Promise<Uint8Array> {
+  const { signParams } = getSigningAlgorithmParams(algorithm);
+
+  // Unwrap the internal CryptoKey
+  const key = unwrapKey(privateKey);
+
+  // Sign the data
+  const signature = await crypto.subtle.sign(signParams, key, data);
+
+  // Convert from IEEE P1363 to DER for EC algorithms
+  return ieeeP1363ToDer(new Uint8Array(signature), algorithm);
+}
+
+/**
+ * Verify signature with an asymmetric public key.
+ */
+export async function verify(
+  data: Uint8Array,
+  signature: Uint8Array,
+  publicKey: PublicKey,
+  algorithm: AsymmetricSigningAlgorithm
+): Promise<boolean> {
+  const { signParams } = getSigningAlgorithmParams(algorithm);
+
+  // Unwrap the internal CryptoKey
+  const key = unwrapKey(publicKey);
+
+  // Convert from DER to IEEE P1363 for EC algorithms
+  const ieeeSignature = derToIeeeP1363(signature, algorithm);
+
+  // Verify the signature
+  return crypto.subtle.verify(signParams, key, ieeeSignature, data);
+}

package/tdf3/src/crypto/core/symmetric.ts

@@ -0,0 +1,265 @@
+import { Algorithms, type AlgorithmUrn } from '../../ciphers/algorithms.js';
+import { Binary } from '../../binary.js';
+import {
+  type DecryptResult,
+  type EncryptResult,
+  type HashAlgorithm,
+  type SymmetricKey,
+} from '../declarations.js';
+import { ConfigurationError, DecryptError } from '../../../../src/errors.js';
+import { encodeArrayBuffer as hexEncode } from '../../../../src/encodings/hex.js';
+import { keyMerge } from '../../utils/keysplit.js';
+import { unwrapSymmetricKey, wrapSymmetricKey } from './keys.js';
+
+const ENC_DEC_METHODS: KeyUsage[] = ['encrypt', 'decrypt'];
+
+/**
+ * Generate a random symmetric key (opaque).
+ * @param length - Key length in bytes (default 32 for AES-256)
+ * @return Opaque symmetric key
+ */
+export async function generateKey(length?: number): Promise<SymmetricKey> {
+  const keyBytes = await randomBytes(length || 32);
+  return wrapSymmetricKey(keyBytes);
+}
+
+export async function randomBytes(byteLength: number): Promise<Uint8Array> {
+  const r = new Uint8Array(byteLength);
+  crypto.getRandomValues(r);
+  return r;
+}
+
+/**
+ * Returns a promise to the encryption key as a binary string.
+ *
+ * Note: This function should almost never fail as it includes a fallback
+ * if for some reason the native generate key fails.
+ *
+ * @param length The key length, defaults to 256
+ *
+ * @returns The hex string.
+ */
+export async function randomBytesAsHex(length: number): Promise<string> {
+  // Create a typed array of the correct length to fill
+  const r = new Uint8Array(length);
+  crypto.getRandomValues(r);
+  return hexEncode(r.buffer);
+}
+
+/**
+ * Decrypt content synchronously
+ * @param payload The payload to decrypt
+ * @param key     The symmetric encryption key (opaque)
+ * @param iv      The initialization vector
+ * @param algorithm The algorithm to use for encryption
+ * @param authTag The authentication tag for authenticated crypto.
+ */
+export function decrypt(
+  payload: Binary,
+  key: SymmetricKey,
+  iv: Binary,
+  algorithm?: AlgorithmUrn,
+  authTag?: Binary
+): Promise<DecryptResult> {
+  return _doDecrypt(payload, key, iv, algorithm, authTag);
+}
+
+/**
+ * Encrypt content synchronously
+ * @param payload   The payload to encrypt
+ * @param key       The encryption key
+ * @param iv        The initialization vector
+ * @param algorithm The algorithm to use for encryption
+ */
+export function encrypt(
+  payload: Binary | SymmetricKey,
+  key: SymmetricKey,
+  iv: Binary,
+  algorithm?: AlgorithmUrn
+): Promise<EncryptResult> {
+  return _doEncrypt(payload, key, iv, algorithm);
+}
+
+async function _doEncrypt(
+  payload: Binary | SymmetricKey,
+  key: SymmetricKey,
+  iv: Binary,
+  algorithm?: AlgorithmUrn
+): Promise<EncryptResult> {
+  console.assert(payload != null);
+  console.assert(key != null);
+  console.assert(iv != null);
+
+  // Handle both Binary and SymmetricKey payloads
+  let payloadBuffer: BufferSource;
+  if ('_brand' in payload && payload._brand === 'SymmetricKey') {
+    // Pass Uint8Array directly — Web Crypto respects byteOffset/byteLength on typed array views.
+    payloadBuffer = unwrapSymmetricKey(payload);
+  } else {
+    // Binary payload
+    payloadBuffer = (payload as Binary).asArrayBuffer();
+  }
+
+  const algoDomString = getSymmetricAlgoDomString(iv, algorithm);
+  const keyBytes = unwrapSymmetricKey(key);
+  const importedKey = await _importKey(keyBytes, algoDomString);
+  const encrypted = await crypto.subtle.encrypt(algoDomString, importedKey, payloadBuffer);
+  if (algoDomString.name === 'AES-GCM') {
+    return {
+      payload: Binary.fromArrayBuffer(encrypted.slice(0, -16)),
+      authTag: Binary.fromArrayBuffer(encrypted.slice(-16)),
+    };
+  }
+  return {
+    payload: Binary.fromArrayBuffer(encrypted),
+  };
+}
+
+async function _doDecrypt(
+  payload: Binary,
+  key: SymmetricKey,
+  iv: Binary,
+  algorithm?: AlgorithmUrn,
+  authTag?: Binary
+): Promise<DecryptResult> {
+  console.assert(payload != null);
+  console.assert(key != null);
+  console.assert(iv != null);
+
+  let payloadBuffer = payload.asArrayBuffer();
+
+  // Concat the the auth tag to the payload for decryption
+  if (authTag) {
+    const authTagBuffer = authTag.asArrayBuffer();
+    const gcmPayload = new Uint8Array(payloadBuffer.byteLength + authTagBuffer.byteLength);
+    gcmPayload.set(new Uint8Array(payloadBuffer), 0);
+    gcmPayload.set(new Uint8Array(authTagBuffer), payloadBuffer.byteLength);
+    payloadBuffer = gcmPayload.buffer;
+  }
+
+  const algoDomString = getSymmetricAlgoDomString(iv, algorithm);
+  const keyBytes = unwrapSymmetricKey(key);
+  const importedKey = await _importKey(keyBytes, algoDomString);
+  algoDomString.iv = iv.asArrayBuffer();
+
+  const decrypted = await crypto.subtle
+    .decrypt(algoDomString, importedKey, payloadBuffer)
+    // Catching this error so we can specifically check for OperationError
+    .catch((err) => {
+      if (err.name === 'OperationError') {
+        throw new DecryptError(err);
+      }
+
+      throw err;
+    });
+  return { payload: Binary.fromArrayBuffer(decrypted) };
+}
+
+function _importKey(keyBytes: Uint8Array, algorithm: AesCbcParams | AesGcmParams) {
+  return crypto.subtle.importKey('raw', keyBytes, algorithm, true, ENC_DEC_METHODS);
+}
+
+/**
+ * Get a DOMString representing the algorithm to use for a crypto
+ * operation. Defaults to AES-CBC.
+ * @param  {String|undefined} algorithm
+ * @return {DOMString} Algorithm to use
+ */
+function getSymmetricAlgoDomString(
+  iv: Binary,
+  algorithm?: AlgorithmUrn
+): AesCbcParams | AesGcmParams {
+  let nativeAlgorithm = 'AES-CBC';
+  if (algorithm === Algorithms.AES_256_GCM) {
+    nativeAlgorithm = 'AES-GCM';
+  }
+
+  return {
+    name: nativeAlgorithm,
+    iv: iv.asArrayBuffer(),
+  };
+}
+
+/**
+ * Create an ArrayBuffer from a hex string.
+ * https://developers.google.com/web/updates/2012/06/How-to-convert-ArrayBuffer-to-and-from-String?hl=en
+ * @param  hex - Hex string
+ */
+export function hex2Ab(hex: string): ArrayBuffer {
+  const buffer = new ArrayBuffer(hex.length / 2);
+  const bufferView = new Uint8Array(buffer);
+
+  for (let i = 0; i < hex.length; i += 2) {
+    bufferView[i / 2] = parseInt(hex.substr(i, 2), 16);
+  }
+
+  return buffer;
+}
+
+/**
+ * Compute hash digest.
+ */
+export async function digest(algorithm: HashAlgorithm, data: Uint8Array): Promise<Uint8Array> {
+  const validAlgorithms: HashAlgorithm[] = ['SHA-256', 'SHA-384', 'SHA-512'];
+  if (!validAlgorithms.includes(algorithm)) {
+    throw new ConfigurationError(`Unsupported hash algorithm: ${algorithm}`);
+  }
+
+  const hashBuffer = await crypto.subtle.digest(algorithm, data);
+  return new Uint8Array(hashBuffer);
+}
+
+/**
+ * Compute HMAC-SHA256 of data with a symmetric key.
+ */
+export async function hmac(data: Uint8Array, key: SymmetricKey): Promise<Uint8Array> {
+  const keyBytes = unwrapSymmetricKey(key);
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    keyBytes,
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign']
+  );
+
+  const signature = await crypto.subtle.sign('HMAC', cryptoKey, data);
+  return new Uint8Array(signature);
+}
+
+/**
+ * Verify HMAC-SHA256.
+ * Standalone utility — not part of CryptoService interface.
+ */
+export async function verifyHmac(
+  data: Uint8Array,
+  signature: Uint8Array,
+  key: SymmetricKey
+): Promise<boolean> {
+  const keyBytes = unwrapSymmetricKey(key);
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    keyBytes,
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['verify']
+  );
+  return crypto.subtle.verify('HMAC', cryptoKey, signature, data);
+}
+
+/**
+ * Import raw key bytes as an opaque symmetric key.
+ * Used for external keys (e.g., unwrapped from KAS).
+ */
+export async function importSymmetricKey(keyBytes: Uint8Array): Promise<SymmetricKey> {
+  return wrapSymmetricKey(keyBytes);
+}
+
+/**
+ * Merge symmetric key shares back into the original key using XOR.
+ * Key bytes are extracted internally for merging.
+ */
+export async function mergeSymmetricKeys(shares: SymmetricKey[]): Promise<SymmetricKey> {
+  const splitBytes = shares.map(unwrapSymmetricKey);
+  const merged = keyMerge(splitBytes);
+  return wrapSymmetricKey(merged);
+}