@opentdf/sdk 0.1.0-beta.1701

package/src/nanotdf/encrypt.ts

@@ -0,0 +1,197 @@
+import NanoTDF from './NanoTDF.js';
+import Header from './models/Header.js';
+import ResourceLocator from './models/ResourceLocator.js';
+import DefaultParams from './models/DefaultParams.js';
+import EmbeddedPolicy from './models/Policy/EmbeddedPolicy.js';
+import Payload from './models/Payload.js';
+import getHkdfSalt from './helpers/getHkdfSalt.js';
+import { getBitLength as authTagLengthForCipher } from './models/Ciphers.js';
+import { TypedArray } from '../tdf/index.js';
+import { GMAC_BINDING_LEN } from './constants.js';
+import { AlgorithmName, KeyFormat, KeyUsageType } from './../nanotdf-crypto/enums.js';
+
+import {
+  encrypt as cryptoEncrypt,
+  keyAgreement,
+  digest,
+  exportCryptoKey,
+} from '../nanotdf-crypto/index.js';
+import { KasPublicKeyInfo } from '../access.js';
+import { computeECDSASig, extractRSValuesFromSignature } from '../nanotdf-crypto/ecdsaSignature.js';
+import { ConfigurationError } from '../errors.js';
+
+/**
+ * Encrypt the plain data into nanotdf buffer
+ *
+ * @param policy Policy that will added to the nanotdf
+ * @param kasInfo KAS url and public key data
+ * @param ephemeralKeyPair SDK ephemeral key pair to generate symmetric key
+ * @param iv
+ * @param data The data to be encrypted
+ * @param ecdsaBinding Flag to enable ECDSA binding
+ */
+export default async function encrypt(
+  policy: string,
+  kasInfo: KasPublicKeyInfo,
+  ephemeralKeyPair: CryptoKeyPair,
+  iv: Uint8Array,
+  data: string | TypedArray | ArrayBuffer,
+  ecdsaBinding: boolean = DefaultParams.ecdsaBinding
+): Promise<ArrayBuffer> {
+  // Generate a symmetric key.
+  if (!ephemeralKeyPair.privateKey) {
+    throw new ConfigurationError('incomplete ephemeral key');
+  }
+  const symmetricKey = await keyAgreement(
+    ephemeralKeyPair.privateKey,
+    await kasInfo.key,
+    // Get the hkdf salt params
+    await getHkdfSalt(DefaultParams.magicNumberVersion)
+  );
+
+  // Construct the kas locator
+  const kasResourceLocator = ResourceLocator.fromURL(kasInfo.url, kasInfo.kid);
+
+  // Auth tag length for policy and payload
+  const authTagLengthInBytes = authTagLengthForCipher(DefaultParams.symmetricCipher) / 8;
+
+  // Encrypt the policy
+  const policyIV = new Uint8Array(iv.length).fill(0);
+  const policyAsBuffer = new TextEncoder().encode(policy);
+  const encryptedPolicy = await cryptoEncrypt(
+    symmetricKey,
+    policyAsBuffer,
+    policyIV,
+    authTagLengthInBytes * 8
+  );
+
+  let policyBinding: Uint8Array;
+
+  // Calculate the policy binding.
+  if (ecdsaBinding) {
+    const curveName = await getCurveNameFromPrivateKey(ephemeralKeyPair.privateKey);
+    const ecdsaPrivateKey = await convertECDHToECDSA(ephemeralKeyPair.privateKey, curveName);
+    const ecdsaSignature = await computeECDSASig(ecdsaPrivateKey, new Uint8Array(encryptedPolicy));
+    const { r, s } = extractRSValuesFromSignature(new Uint8Array(ecdsaSignature));
+
+    const rLength = r.length;
+    const sLength = s.length;
+
+    policyBinding = new Uint8Array(1 + rLength + 1 + sLength);
+
+    // Set the lengths and values of r and s in policyBinding
+    policyBinding[0] = rLength;
+    policyBinding.set(r, 1);
+    policyBinding[1 + rLength] = sLength;
+    policyBinding.set(s, 1 + rLength + 1);
+  } else {
+    const signature = await digest('SHA-256', new Uint8Array(encryptedPolicy));
+    policyBinding = new Uint8Array(signature.slice(-GMAC_BINDING_LEN));
+  }
+
+  // Create embedded policy
+  const embeddedPolicy = new EmbeddedPolicy(
+    DefaultParams.policyType,
+    policyBinding,
+    new Uint8Array(encryptedPolicy)
+  );
+
+  if (!ephemeralKeyPair.publicKey) {
+    throw new ConfigurationError('incomplete ephemeral key');
+  }
+  // Create a header
+  const pubKeyAsArrayBuffer = await exportCryptoKey(ephemeralKeyPair.publicKey);
+
+  const header = new Header(
+    DefaultParams.magicNumberVersion,
+    kasResourceLocator,
+    ecdsaBinding,
+    DefaultParams.signatureCurveName,
+    DefaultParams.signature,
+    DefaultParams.signatureCurveName,
+    DefaultParams.symmetricCipher,
+    embeddedPolicy,
+    new Uint8Array(pubKeyAsArrayBuffer)
+  );
+
+  // Encrypt the payload
+  let payloadAsBuffer;
+  if (typeof data === 'string') {
+    payloadAsBuffer = new TextEncoder().encode(data);
+  } else {
+    payloadAsBuffer = data;
+  }
+
+  const encryptedPayload = await cryptoEncrypt(
+    symmetricKey,
+    new Uint8Array(payloadAsBuffer),
+    iv,
+    authTagLengthInBytes * 8
+  );
+
+  // Create payload
+  const payload = new Payload(
+    iv.slice(-3),
+    new Uint8Array(encryptedPayload.slice(0, -authTagLengthInBytes)),
+    new Uint8Array(encryptedPayload.slice(-authTagLengthInBytes))
+  );
+
+  // Create a nanotdf.
+  const nanoTDF = new NanoTDF(header, payload);
+  return nanoTDF.toBuffer();
+}
+
+/**
+ * Retrieves the curve name from a given ECDH private key.
+ *
+ * This function exports the provided ECDH private key in JWK format and extracts
+ * the curve name from the 'crv' property of the JWK.
+ *
+ * @param {CryptoKey} privateKey - The ECDH private key from which to retrieve the curve name.
+ * @returns {Promise<string>} - A promise that resolves to the curve name.
+ *
+ * @throws {Error} - Throws an error if the curve name is undefined.
+ *
+ */
+async function getCurveNameFromPrivateKey(privateKey: CryptoKey): Promise<string> {
+  // Export the private key
+  const keyData = await crypto.subtle.exportKey('jwk', privateKey);
+
+  // The curve name is stored in the 'crv' property of the JWK
+  if (!keyData.crv) {
+    throw new ConfigurationError('curve name is undefined (bad private key)');
+  }
+
+  return keyData.crv;
+}
+
+/**
+ * Converts an ECDH private key to an ECDSA private key.
+ *
+ * This function exports the given ECDH private key in PKCS#8 format and then
+ * imports it as an ECDSA private key using the specified curve name.
+ *
+ * @param {CryptoKey} key - The ECDH private key to be converted.
+ * @param {string} curveName - The name of the elliptic curve to be used for the ECDSA key.
+ * @returns {Promise<CryptoKey>} - A promise that resolves to the converted ECDSA private key.
+ *
+ * @throws {Error} - Throws an error if the key export or import fails.
+ */
+async function convertECDHToECDSA(key: CryptoKey, curveName: string): Promise<CryptoKey> {
+  // Export the ECDH private key
+  const ecdhPrivateKey = await crypto.subtle.exportKey('pkcs8', key);
+
+  // Import the ECDH private key as an ECDSA private key
+  const ecdsaPrivateKey = await crypto.subtle.importKey(
+    KeyFormat.Pkcs8,
+    ecdhPrivateKey,
+    {
+      name: AlgorithmName.ECDSA,
+      namedCurve: curveName,
+    },
+    true,
+    [KeyUsageType.Sign]
+  );
+
+  return ecdsaPrivateKey;
+}

package/src/nanotdf/enum/CipherEnum.ts

@@ -0,0 +1,10 @@
+enum CipherEnum {
+  AES_256_GCM_64, // Default cipher
+  AES_256_GCM_96,
+  AES_256_GCM_104,
+  AES_256_GCM_112,
+  AES_256_GCM_120,
+  AES_256_GCM_128,
+}
+
+export default CipherEnum;

package/src/nanotdf/enum/CurveNameEnum.ts

@@ -0,0 +1,12 @@
+/**
+ * The Signature ECC Mode is used to determine the length of the signature at the end of a nanotdf. This, in
+ * combination with the previous HAS_SIGNATURE section, describe the signature of the nanotdf. The following table
+ * describes the valid values and the associated ECC Params.
+ */
+enum CurveNameEnum {
+  SECP256R1,
+  SECP384R1,
+  SECP521R1,
+}
+
+export default CurveNameEnum;

package/src/nanotdf/enum/EncodingEnum.ts

@@ -0,0 +1,5 @@
+enum EncodingEnum {
+  Base64 = 'base64',
+}
+
+export default EncodingEnum;

package/src/nanotdf/enum/PolicyTypeEnum.ts

@@ -0,0 +1,8 @@
+enum PolicyType {
+  Remote,
+  EmbeddedText,
+  EmbeddedEncrypted, // Default policy
+  EmbeddedEncryptedPKA, // Todo: Not implemented
+}
+
+export default PolicyType;

package/src/nanotdf/enum/ProtocolEnum.ts

@@ -0,0 +1,7 @@
+enum ProtocolEnum {
+  Http = 0,
+  Https = 1,
+  SharedResourceDirectory = 0xf,
+}
+
+export default ProtocolEnum;

package/src/nanotdf/enum/ResourceLocatorIdentifierEnum.ts

@@ -0,0 +1,8 @@
+enum ResourceLocatorIdentifierEnum {
+  None = 0,
+  TwoBytes = 2,
+  EightBytes = 8,
+  ThirtyTwoBytes = 32,
+}
+
+export default ResourceLocatorIdentifierEnum;

package/src/nanotdf/helpers/calculateByCurve.ts

@@ -0,0 +1,26 @@
+import CurveNameEnum from '../enum/CurveNameEnum.js';
+import { getCurveLength } from '../models/EcCurves.js';
+
+/**
+ * Length of public key
+ *
+ * @param curveName CurveNameEnum
+ * @returns number length of the public key
+ */
+export function lengthOfPublicKey(curveName: CurveNameEnum): number | never {
+  return Math.ceil(getCurveLength(curveName) / 8);
+}
+
+/**
+ * Length of signature
+ *
+ * ECDSA signatures are 2 times longer than the signer's private key for the curve used during the signing process.
+ * For example, for 256-bit elliptic curves (like secp256k1 ) the ECDSA signature is 512 bits (64 bytes) and for 521-bit
+ * curves (like secp521r1 ) the signature is 1042 bits.
+ *
+ * @param curveName CurveNameEnum
+ * @returns number length of the signature
+ */
+export function lengthOfSignature(curveName: CurveNameEnum): number | never {
+  return Math.ceil((getCurveLength(curveName) * 2) / 8);
+}

package/src/nanotdf/helpers/getHkdfSalt.ts

@@ -0,0 +1,15 @@
+import { TypedArray } from '../../tdf/index.js';
+
+import { digest, enums } from '../../nanotdf-crypto/index.js';
+
+interface HkdfSalt {
+  hkdfSalt: ArrayBuffer;
+  hkdfHash: enums.HashType;
+}
+
+export default async function getHkdfSalt(buffer: TypedArray | ArrayBuffer): Promise<HkdfSalt> {
+  return {
+    hkdfSalt: await digest(enums.HashType.Sha256, buffer),
+    hkdfHash: enums.HashType.Sha256,
+  };
+}

package/src/nanotdf/index.ts

@@ -0,0 +1,10 @@
+// Don't export named values or the enduser will
+// have to call `const NanoTDF = require('nanotdf').default`
+export { default as Client } from './Client.js';
+export { default as Header } from './models/Header.js';
+export { default as NanoTDF } from './NanoTDF.js';
+export { default as decrypt } from './decrypt.js';
+export { default as encrypt } from './encrypt.js';
+export { default as encryptDataset } from './encrypt-dataset.js';
+export { default as getHkdfSalt } from './helpers/getHkdfSalt.js';
+export { default as DefaultParams } from './models/DefaultParams.js';

package/src/nanotdf/interfaces/PolicyInterface.ts

@@ -0,0 +1,27 @@
+import PolicyTypeEnum from '../enum/PolicyTypeEnum.js';
+import ResourceLocator from '../models/ResourceLocator.js';
+
+export default interface PolicyInterface {
+  type: PolicyTypeEnum;
+  binding: Uint8Array;
+
+  // Remote policy
+  remotePolicy?: ResourceLocator;
+
+  // Embedded policy
+  content?: Uint8Array;
+
+  // Return the content of policy
+  toBuffer(): Uint8Array | never;
+
+  // Return the length of the policy
+  getLength(): number;
+}
+
+export interface RemotePolicyInterface extends PolicyInterface {
+  remotePoilcy?: ResourceLocator;
+}
+
+export interface EmbeddedPolicyInterface extends PolicyInterface {
+  content: Uint8Array;
+}

package/src/nanotdf/models/Ciphers.ts

@@ -0,0 +1,67 @@
+import CipherEnum from '../enum/CipherEnum.js';
+import { UnsupportedFeatureError } from '../../errors.js';
+
+interface CipherInterface {
+  name: CipherEnum;
+  length: number;
+}
+
+export const Aes256Gcm64: CipherInterface = {
+  name: CipherEnum.AES_256_GCM_64,
+  length: 64,
+};
+
+export const Aes256Gcm96: CipherInterface = {
+  name: CipherEnum.AES_256_GCM_96,
+  length: 96,
+};
+
+export const Aes256Gcm104: CipherInterface = {
+  name: CipherEnum.AES_256_GCM_104,
+  length: 104,
+};
+
+export const Aes256Gcm112: CipherInterface = {
+  name: CipherEnum.AES_256_GCM_112,
+  length: 112,
+};
+
+export const Aes256Gcm120: CipherInterface = {
+  name: CipherEnum.AES_256_GCM_120,
+  length: 120,
+};
+
+export const Aes256Gcm128: CipherInterface = {
+  name: CipherEnum.AES_256_GCM_128,
+  length: 128,
+};
+
+export function getBitLength(cipher: CipherEnum): number {
+  switch (cipher) {
+    case CipherEnum.AES_256_GCM_64:
+      return Aes256Gcm64.length;
+    case CipherEnum.AES_256_GCM_96:
+      return Aes256Gcm96.length;
+    case CipherEnum.AES_256_GCM_104:
+      return Aes256Gcm104.length;
+    case CipherEnum.AES_256_GCM_112:
+      return Aes256Gcm112.length;
+    case CipherEnum.AES_256_GCM_120:
+      return Aes256Gcm120.length;
+    case CipherEnum.AES_256_GCM_128:
+      return Aes256Gcm128.length;
+    default:
+      throw new UnsupportedFeatureError(`unsupported cipher enum value: [${cipher}]`);
+  }
+}
+
+// export default {
+//   Aes256Gcm64,
+//   Aes256Gcm96,
+//   Aes256Gcm104,
+//   Aes256Gcm112,
+//   Aes256Gcm120,
+//   Aes256Gcm128,
+
+//   getBitLength,
+// };

package/src/nanotdf/models/DefaultParams.ts

@@ -0,0 +1,24 @@
+import CipherEnum from '../enum/CipherEnum.js';
+import CurveNameEnum from '../enum/CurveNameEnum.js';
+import PolicyTypeEnum from '../enum/PolicyTypeEnum.js';
+
+const enc = new TextEncoder();
+
+/**
+ * Default encrypt param builders
+ *
+ * @link https://github.com/virtru/tdf3-cpp/blob/develop/tdf3-src/lib/src/nanotdf_builder_impl.h
+ */
+const DefaultParams = {
+  ecdsaBinding: false,
+  ephemeralCurveName: CurveNameEnum.SECP256R1,
+  magicNumberVersion: enc.encode('L1L'),
+  offlineMode: false,
+  policyType: PolicyTypeEnum.EmbeddedEncrypted,
+  signature: false,
+  signatureCurveName: CurveNameEnum.SECP256R1,
+  symmetricCipher: CipherEnum.AES_256_GCM_96,
+  defaultECAlgorithm: 'ec:secp256r1',
+};
+
+export default DefaultParams;

package/src/nanotdf/models/EcCurves.ts

@@ -0,0 +1,40 @@
+import CurveNameEnum from '../enum/CurveNameEnum.js';
+import { UnsupportedFeatureError } from '../../errors.js';
+
+export interface CurveInterface {
+  name: CurveNameEnum;
+  length: number;
+}
+
+export const Secp256R1: CurveInterface = {
+  name: CurveNameEnum.SECP256R1,
+  length: 256,
+};
+
+export const Secp384R1: CurveInterface = {
+  name: CurveNameEnum.SECP384R1,
+  length: 384,
+};
+
+export const Secp521R1: CurveInterface = {
+  name: CurveNameEnum.SECP521R1,
+  length: 521,
+};
+
+/**
+ * Get size from Curve
+ *
+ * @param curveName CurveNameEnum name of the curve
+ */
+export function getCurveLength(curveName: CurveNameEnum): number {
+  switch (curveName) {
+    case Secp256R1.name:
+      return Secp256R1.length;
+    case Secp384R1.name:
+      return Secp384R1.length;
+    case Secp521R1.name:
+      return Secp521R1.length;
+    default:
+      throw new UnsupportedFeatureError(`unsupported curve name: ${curveName}`);
+  }
+}