@virtru/dsp-sdk 0.4.1 → 0.5.0

package/src/lib/fips-crypto/symmetric.ts

@@ -0,0 +1,213 @@
+/*
+ * Copyright (c) Virtru Corporation.  All rights reserved.
+ *
+ * Your use of this file is governed by the Virtu Terms of Service <https://www.virtru.com/terms-of-service/>.
+ */
+
+import { Binary, type SymmetricKey } from '@opentdf/sdk/singlecontainer';
+import { ConfigurationError } from '@opentdf/sdk';
+import { getVirtruCrypto } from './primitives';
+import { isSymmetricKey, wrapSymmetricKey, unwrapSymmetricKey } from './keys';
+
+type AlgorithmUrn = string;
+type EncryptResult = { payload: Binary; authTag?: Binary };
+type DecryptResult = { payload: Binary };
+
+const AES_CBC_URN = 'http://www.w3.org/2001/04/xmlenc#aes256-cbc';
+
+const SYM_KEY_METHODS = ['encrypt', 'decrypt', 'sign', 'verify'] as const;
+
+/**
+ * Generate a random AES-256 symmetric key.
+ * The VirtruCryptoKey handle is kept alive inside the opaque SymmetricKey —
+ * key material never leaves the FIPS WASM keystore.
+ */
+export async function generateKey(length?: number): Promise<SymmetricKey> {
+  const crypto = await getVirtruCrypto();
+  const bitLen = (length || 32) * 8;
+  // extractable=true and internal=true: keystore-based AES key that can be exported
+  // for RSA key-wrapping (encryptWithPublicKey calls exportKey on the DEK).
+  const vKey = await crypto.generateKey(
+    { name: 'AES-GCM', length: bitLen as 256 },
+    true,
+    SYM_KEY_METHODS,
+    true
+  );
+  return wrapSymmetricKey(vKey, bitLen);
+}
+
+/**
+ * Encrypt a payload with a symmetric AES key.
+ * When payload is a SymmetricKey the key bytes are exported internally to
+ * perform key-wrapping — they are never surfaced to the caller.
+ */
+export async function encrypt(
+  payload: Binary | SymmetricKey,
+  key: SymmetricKey,
+  iv: Binary,
+  algorithm?: AlgorithmUrn
+): Promise<EncryptResult> {
+  const crypto = await getVirtruCrypto();
+  const algName = algorithm === AES_CBC_URN ? 'AES-CBC' : 'AES-GCM';
+
+  let payloadBytes: Uint8Array;
+  if (isSymmetricKey(payload)) {
+    // Key-wrapping path: export symmetric key bytes from keystore.
+    // Only works if the key was created with extractable:true (e.g. via importSymmetricKey).
+    payloadBytes = await crypto.exportKey('raw', unwrapSymmetricKey(payload));
+  } else {
+    payloadBytes = new Uint8Array(payload.asArrayBuffer());
+  }
+
+  const vKey = unwrapSymmetricKey(key);
+  const ivBytes = new Uint8Array(iv.asArrayBuffer());
+
+  const cipherBytes = await crypto.encrypt(
+    { name: algName, length: 256, iv: ivBytes } as any,
+    vKey,
+    payloadBytes
+  );
+
+  if (algName === 'AES-GCM') {
+    return {
+      payload: Binary.fromArrayBuffer(cipherBytes.slice(0, -16).buffer as ArrayBuffer),
+      authTag: Binary.fromArrayBuffer(cipherBytes.slice(-16).buffer as ArrayBuffer),
+    };
+  }
+  return { payload: Binary.fromArrayBuffer(cipherBytes.buffer as ArrayBuffer) };
+}
+
+/**
+ * Decrypt a payload with a symmetric AES key.
+ */
+export async function decrypt(
+  payload: Binary,
+  key: SymmetricKey,
+  iv: Binary,
+  algorithm?: AlgorithmUrn,
+  authTag?: Binary
+): Promise<DecryptResult> {
+  const crypto = await getVirtruCrypto();
+  const algName = algorithm === AES_CBC_URN ? 'AES-CBC' : 'AES-GCM';
+
+  let payloadBytes = new Uint8Array(payload.asArrayBuffer());
+  const ivBytes = new Uint8Array(iv.asArrayBuffer());
+
+  if (algName === 'AES-GCM') {
+    if (!authTag) {
+      throw new Error('Missing authTag for AES-GCM decryption');
+    }
+    const tagBytes = new Uint8Array(authTag.asArrayBuffer());
+    const combined = new Uint8Array(payloadBytes.length + tagBytes.length);
+    combined.set(payloadBytes, 0);
+    combined.set(tagBytes, payloadBytes.length);
+    payloadBytes = combined;
+  }
+
+  const vKey = unwrapSymmetricKey(key);
+  const plainBytes = await crypto.decrypt(
+    { name: algName, length: 256, iv: ivBytes } as any,
+    vKey,
+    payloadBytes
+  );
+
+  return { payload: Binary.fromArrayBuffer(plainBytes.buffer as ArrayBuffer) };
+}
+
+// ─── HMAC ─────────────────────────────────────────────────────────────────────
+
+const HMAC_PARAMS = { name: 'HMAC' as const, hash: 'SHA-256' as const };
+
+/**
+ * Compute HMAC-SHA256.
+ * The SymmetricKey must have been created with extractable:true (e.g. via
+ * importSymmetricKey) so its bytes can be re-imported as an HMAC key.
+ */
+export async function hmac(data: Uint8Array, key: SymmetricKey): Promise<Uint8Array> {
+  const crypto = await getVirtruCrypto();
+  const vKey = unwrapSymmetricKey(key);
+  // The key was imported with 'sign' usage (see importSymmetricKey).
+  // VirtruCrypto sign() checks usage.includes('sign') then calls the WASM
+  // hmac() with the slot number — the key type string is irrelevant for HMAC.
+  // Do NOT call release() here: the key handle must remain valid for future calls.
+  const sig = await crypto.sign(HMAC_PARAMS, vKey, data);
+  return new Uint8Array(sig);
+}
+
+/**
+ * Verify HMAC-SHA256 using constant-time comparison.
+ */
+export async function verifyHmac(
+  data: Uint8Array,
+  signature: Uint8Array,
+  key: SymmetricKey
+): Promise<boolean> {
+  const expected = await hmac(data, key);
+  if (signature.length !== expected.length) return false;
+  let mismatch = 0;
+  for (let i = 0; i < signature.length; i++) {
+    mismatch |= signature[i] ^ expected[i];
+  }
+  return mismatch === 0;
+}
+
+// ─── Symmetric Key Import / Split / Merge ─────────────────────────────────────
+
+/**
+ * Import raw key bytes as an opaque SymmetricKey.
+ * The resulting key is extractable so it can be used for HMAC and key-wrapping.
+ */
+export async function importSymmetricKey(keyBytes: Uint8Array): Promise<SymmetricKey> {
+  const crypto = await getVirtruCrypto();
+  const bitLen = keyBytes.length * 8;
+  // Include 'sign'/'verify' so this key can also be used for HMAC-SHA256.
+  // VirtruCrypto's sign() checks key.usage.includes('sign'); the underlying
+  // WASM hmac() takes the slot number and works with any 256-bit key material.
+  const vKey = await crypto.importKey(
+    'raw',
+    keyBytes,
+    { name: 'AES-GCM' },
+    true,
+    SYM_KEY_METHODS
+  );
+  return wrapSymmetricKey(vKey, bitLen);
+}
+
+/**
+ * Split a symmetric key into N shares using XOR secret sharing.
+ *
+ * For numShares === 1 (single-KAS), the key is returned as-is — no key
+ * material is exported and no splitting occurs. This is the common DSP case.
+ *
+ * For numShares > 1 (multi-KAS), XOR secret sharing requires exporting the
+ * raw key bytes. This is not yet implemented in FIPS mode.
+ */
+export async function splitSymmetricKey(key: SymmetricKey, numShares: number): Promise<SymmetricKey[]> {
+  if (numShares === 1) {
+    return [key];
+  }
+  throw new ConfigurationError(
+    `splitSymmetricKey with ${numShares} shares is not yet supported in FIPS mode. ` +
+    'Multi-KAS key splitting requires raw key export which violates FIPS key boundary constraints.'
+  );
+}
+
+/**
+ * Merge symmetric key shares back into the original key using XOR.
+ *
+ * For a single share (single-KAS), the share is returned as-is — no key
+ * material is exported and no XOR occurs. This is the common DSP case.
+ *
+ * For multiple shares (multi-KAS), XOR merging requires exporting raw key bytes.
+ * This is not yet implemented in FIPS mode.
+ */
+export async function mergeSymmetricKeys(shares: SymmetricKey[]): Promise<SymmetricKey> {
+  if (shares.length === 0) throw new ConfigurationError('No shares provided to mergeSymmetricKeys');
+  if (shares.length === 1) {
+    return shares[0];
+  }
+  throw new ConfigurationError(
+    `mergeSymmetricKeys with ${shares.length} shares is not yet supported in FIPS mode. ` +
+    'Multi-KAS key merging requires raw key export which violates FIPS key boundary constraints.'
+  );
+}

package/src/lib/fips-crypto-service.ts

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) Virtru Corporation.  All rights reserved.
+ *
+ * Your use of this file is governed by the Virtu Terms of Service <https://www.virtru.com/terms-of-service/>.
+ */
+
+import { type CryptoService } from '@opentdf/sdk/singlecontainer';
+
+export { initializeFipsCrypto } from './fips-crypto/primitives';
+
+export {
+  wrapPublicKey,
+  wrapPrivateKey,
+  wrapSymmetricKey,
+  wrapKeyPair,
+  unwrapPublicKey,
+  unwrapPrivateKey,
+  unwrapSymmetricKey,
+} from './fips-crypto/keys';
+
+import { randomBytes, digest } from './fips-crypto/primitives';
+import { generateKey, encrypt, decrypt, hmac, verifyHmac, importSymmetricKey, splitSymmetricKey, mergeSymmetricKeys } from './fips-crypto/symmetric';
+import { generateKeyPair, generateSigningKeyPair, encryptWithPublicKey, decryptWithPrivateKey, sign, verify, generateECKeyPair, deriveKeyFromECDH } from './fips-crypto/asymmetric';
+import { importPublicKey, importPrivateKey, exportPublicKeyPem, exportPrivateKeyPem, exportPublicKeyJwk, parsePublicKeyPem, extractPublicKeyPem, jwkToPublicKeyPem } from './fips-crypto/key-format';
+export { importPrivateKey, exportPrivateKeyPem } from './fips-crypto/key-format';
+
+// ─── FipsCryptoService ────────────────────────────────────────────────────────
+
+export const FipsCryptoService: CryptoService = {
+  name: 'FipsCryptoService',
+  method: 'http://www.w3.org/2001/04/xmlenc#aes256-cbc',
+  decrypt,
+  decryptWithPrivateKey,
+  encrypt,
+  encryptWithPublicKey,
+  generateKey,
+  generateKeyPair,
+  generateSigningKeyPair,
+  randomBytes,
+  sign,
+  verify,
+  hmac,
+  verifyHmac,
+  digest,
+  generateECKeyPair,
+  deriveKeyFromECDH,
+  importPublicKey,
+  importPrivateKey,
+  exportPublicKeyPem,
+  exportPrivateKeyPem,
+  exportPublicKeyJwk,
+  parsePublicKeyPem,
+  extractPublicKeyPem,
+  jwkToPublicKeyPem,
+  importSymmetricKey,
+  splitSymmetricKey,
+  mergeSymmetricKeys,
+};

package/src/lib/utils.test.ts

@@ -15,6 +15,15 @@ vi.mock('@opentdf/sdk', () => ({
   PermissionDeniedError: class PermissionDeniedError extends Error {},
 }));
 
+vi.mock('@opentdf/sdk/singlecontainer', () => ({
+  WebCryptoService: {
+    generateSigningKeyPair: vi.fn().mockResolvedValue({
+      publicKey: {},
+      privateKey: {},
+    }),
+  },
+}));
+
 vi.mock('@opentdf/sdk/platform', () => ({
   PlatformClient: vi.fn(),
 }));
@@ -86,6 +95,7 @@ import { validateJWSCertificateChain, getTrustedCertificates } from './utils';
 import { DSPClient } from './client';
 import { PlatformClient } from '@opentdf/sdk/platform';
 import { AuthProviders } from '@opentdf/sdk';
+import { WebCryptoService } from '@opentdf/sdk/singlecontainer';
 
 describe('validateJWSCertificateChain', () => {
   beforeEach(() => {
@@ -354,15 +364,8 @@ describe('getTrustedCertificates', () => {
     await getTrustedCertificates(mockOptions);
 
     expect(AuthProviders.refreshAuthProvider).toHaveBeenCalled();
+    expect(WebCryptoService.generateSigningKeyPair).toHaveBeenCalled();
     expect(mockAuthProvider.updateClientPublicKey).toHaveBeenCalled();
-    expect(globalThis.crypto.subtle.generateKey).toHaveBeenCalledWith(
-      {
-        name: 'ECDSA',
-        namedCurve: 'P-256',
-      },
-      true,
-      ['sign', 'verify']
-    );
   });
 
   it('creates both PlatformClient and DSPClient with correct config', async () => {

package/src/lib/utils.ts

@@ -11,6 +11,7 @@ import {
   PermissionDeniedError,
   type Source,
 } from '@opentdf/sdk';
+import { type CryptoService, WebCryptoService } from '@opentdf/sdk/singlecontainer';
 import { PlatformClient } from '@opentdf/sdk/platform';
 import { ActiveStateEnum } from '@opentdf/sdk/platform/common/common_pb.js';
 import type { Certificate } from '../gen/virtru/policy/objects_pb';
@@ -50,7 +51,7 @@ export type GetUserEntitlementsResponse = {
  * @returns An `Interceptor` function that modifies requests to include authentication headers.
  */
 
-export function createAuthInterceptor(authProvider: AuthProvider): Interceptor {
+export function createAuthInterceptor(authProvider: AuthProvider, _cryptoService?: CryptoService): Interceptor {
   return (next) => async (req) => {
     const url = new URL(req.url);
     const pathOnly = url.pathname;
@@ -79,6 +80,7 @@ export async function createAuthProvider(options: {
     userInfoEndpoint: string;
   };
   refreshToken: string;
+  cryptoService?: CryptoService;
 }): Promise<AuthProviders.OIDCRefreshTokenProvider> {
   const { oidc, refreshToken } = options;
 
@@ -102,6 +104,7 @@ export async function createOpenTDFClient(options: {
   platformEndpoint: string;
   refreshToken: string;
   obligations: string[];
+  cryptoService?: CryptoService;
 }) {
   const { platformEndpoint, obligations, ...authProviderOptions } = options;
   return new OpenTDF({
@@ -117,6 +120,7 @@ export async function createOpenTDFClient(options: {
       noVerify: true,
     },
     disableDPoP: true,
+    cryptoService: options.cryptoService,
   });
 }
 
@@ -131,6 +135,7 @@ export const getObligations = async (
     platformEndpoint: string;
     refreshToken: string;
     obligations: string[];
+    cryptoService?: CryptoService;
   }
 ): Promise<string[]> => {
   const client = await createOpenTDFClient(options);
@@ -159,10 +164,12 @@ export async function getUserEntitlements(options: {
   };
   platformEndpoint: string;
   refreshToken: string;
+  cryptoService?: CryptoService;
 }) {
   const authProvider = await createAuthProvider({
     oidc: options.oidc,
     refreshToken: options.refreshToken,
+    cryptoService: options.cryptoService,
   });
   const accessToken = await authProvider.oidcAuth.get();
   const userEntitlementsResponse = await fetch(
@@ -271,23 +278,16 @@ export async function getTrustedCertificates(options: {
   };
   platformEndpoint: string;
   refreshToken: string;
+  cryptoService?: CryptoService;
 }): Promise<Certificate[]> {
-  function generateSigningKeyPair() {
-    return crypto.subtle.generateKey(
-      {
-        name: 'ECDSA',
-        namedCurve: 'P-256',
-      },
-      true,
-      ['sign', 'verify']
-    );
-  }
+  const cs = options.cryptoService ?? WebCryptoService;
 
   const authProvider = await createAuthProvider({
     oidc: options.oidc,
     refreshToken: options.refreshToken,
+    cryptoService: options.cryptoService,
   });
-  await authProvider.updateClientPublicKey(await generateSigningKeyPair());
+  await authProvider.updateClientPublicKey(await cs.generateSigningKeyPair());
 
   // Create both clients
   const platform = new PlatformClient({
@@ -423,7 +423,8 @@ function pemToArrayBuffer(pem: string): ArrayBuffer {
  */
 export async function validateJWSCertificateChain(
   x5c: string[],
-  trustedRootCertificates: Certificate[]
+  trustedRootCertificates: Certificate[],
+  _cryptoService?: CryptoService
 ): Promise<JWSValidationResult> {
   const warnings: string[] = [];
 

package/temp/build/lint/_eslint-5eVG3S6w.json

@@ -21,10 +21,18 @@
       "tests/dsp.test.ts",
       "72K1himJItp7yd9dkZNa7RwUmQo=_KBnhlqHDJygGymeSAMhfjnUj064="
     ],
+    [
+      "tests/fips-crypto.unit.test.ts",
+      "eStngPGfsHlKIOfJ2k1WkUpqFX0=_KBnhlqHDJygGymeSAMhfjnUj064="
+    ],
     [
       "tests/setup-msw.ts",
       "Sz1wiT3itCcl8Bpq5hnfs4hPjuo=_KBnhlqHDJygGymeSAMhfjnUj064="
+    ],
+    [
+      "tests/setup-unit.ts",
+      "Hb3n5KLyWlQyrMYmNx9grgPHBCU=_KBnhlqHDJygGymeSAMhfjnUj064="
     ]
   ],
-  "filesHash": "ZUDFQlGnS2ya5rvcK6ruZA"
+  "filesHash": "flOfsEjcUy5GStpiBEHpfg"
 }