@opentdf/sdk 0.1.0-beta.1701

package/src/nanotdf/models/Header.ts

@@ -0,0 +1,322 @@
+// Models
+import { getBitLength } from './Ciphers.js';
+import ResourceLocator from './ResourceLocator.js';
+import PolicyFactory from './Policy/PolicyFactory.js';
+// Interfaces
+import PolicyInterface from '../interfaces/PolicyInterface.js';
+// Enum
+import CipherEnum from '../enum/CipherEnum.js';
+import CurveNameEnum from '../enum/CurveNameEnum.js';
+// Helpers
+import { lengthOfPublicKey } from '../helpers/calculateByCurve.js';
+import DefaultParams from './DefaultParams.js';
+import { ConfigurationError, InvalidFileError } from '../../errors.js';
+import { rstrip } from '../../utils.js';
+
+/**
+ * NanoTDF Header
+ *
+ * The header section is intended to be sent to a KAS and is used by the KAS to derive the decryption key that can
+ * decrypts the nanotdf's payload. The Header is structured as follows:
+ *
+ * | Section                | Minimum Length (B) | Maximum Length (B) |
+ * |------------------------|--------------------|--------------------|
+ * | Magic Number + Version | 3                  | 3                  |
+ * | KAS (resource locator) | 3                  | 257                |
+ * | ECC Mode               | 1                  | 1                  |
+ * | Payload + Sig Mode     | 1                  | 1                  |
+ * | Policy                 | 3                  | 257                |
+ * | Ephemeral Key          | 33                 | 67                 |
+ *
+ */
+export default class Header {
+  // Magic Number & Version
+  static readonly MAGIC_NUMBER_VERSION_BYTE_OFF = 0;
+  static readonly MAGIC_NUMBER_VERSION_BYTE_LEN = 3;
+  static readonly MAGIC_NUMBER_OFFSET = 0;
+  static readonly MAGIC_NUMBER_LENGTH = 18;
+
+  // ECC & Binding Mode
+  static readonly ECC_BINDING_MODE_BYTE_LEN = 1;
+  static readonly USE_ECDSA_BINDING_BIT_OFF = 0;
+  static readonly EPHEMERAL_ECC_CURVE_NAME_BIT_OFF = -3;
+
+  // Symmetric & Payload Config
+  static readonly SYMMETRIC_PAYLOAD_CONFIG_BYTE_LEN = 1;
+  static readonly HAS_SIGNATURE_BIT_OFF = 1;
+  static readonly HAS_SIGNATURE_BIT_LEN = 1;
+  static readonly SIGNATURE_ECC_CURVE_NAME_BIT_OFF = 1;
+  static readonly SIGNATURE_ECC_CURVE_NAME_BIT_LEN = 3;
+  static readonly SYMMETRIC_CIPHER_BIT_OFF = 4;
+  static readonly SYMMETRIC_CIPHER_BIT_LEN = 4;
+
+  // Magic Number & Version
+  public magicNumberVersion: Uint8Array = DefaultParams.magicNumberVersion;
+
+  // KAS Resource Locator
+  public kas: ResourceLocator;
+
+  // ECC & Binding Mode
+  public useECDSABinding: boolean = DefaultParams.ecdsaBinding;
+  public ephemeralCurveName: CurveNameEnum = DefaultParams.ephemeralCurveName;
+
+  // Symmetric & Payload Config
+  public hasSignature: boolean = DefaultParams.signature;
+  public signatureCurveName: CurveNameEnum = DefaultParams.signatureCurveName;
+  public symmetricCipher: CipherEnum = DefaultParams.symmetricCipher;
+  // Auth tag length (in bits) is not part of the spec, but is needed for decrypt
+  public authTagLength: number;
+
+  // Policy
+  public policy: PolicyInterface;
+
+  // Ephemeral Public Key
+  public ephemeralPublicKey: Uint8Array;
+
+  static parse(buff: Uint8Array) {
+    let offset = 0;
+
+    /**
+     * Magic number and version
+     *
+     * @link https://github.com/virtru/nanotdf/blob/master/spec/index.md#3311-magic-number--version
+     */
+    // Convert to ascii
+    const magicNumberVersion = buff.subarray(
+      Header.MAGIC_NUMBER_VERSION_BYTE_OFF,
+      Header.MAGIC_NUMBER_VERSION_BYTE_LEN
+    );
+    offset += Header.MAGIC_NUMBER_VERSION_BYTE_LEN;
+
+    /**
+     * KAS Resource Locator
+     *
+     * KAS is a typeof Resource Locator
+     *
+     * @link https://github.com/virtru/nanotdf/blob/master/spec/index.md#3312-kas
+     * @link https://github.com/virtru/nanotdf/blob/master/spec/index.md#341-resource-locator
+     */
+    const kas = ResourceLocator.parse(buff.subarray(offset));
+    offset += kas.length;
+
+    /**
+     * ECC & Binding Mode
+     *
+     * This section contains a 1-byte bitfield describing the ECC Params and Policy binding strategy to use.
+     * The Policy Binding strategy is either using a 64-bit GMAC (using AES-256-GCM) tag or an ECDSA signature.
+     * The signature size depends on the size of ECC Params used. The nanotdf at this time only supports methods that
+     * involve Elliptic Curve Cryptography. The fields are structured as follows:
+     *
+     * | Section                   | Bit Length | Bit start index |
+     * |---------------------------|------------|-----------------|
+     * | USE_ECDSA_BINDING         | 1          | 7               |
+     * | UNUSED                    | 4          | 3               |
+     * | Ephemeral ECC Params Enum | 3          | 0               |
+     *
+     * @link https://github.com/virtru/nanotdf/blob/master/spec/index.md#3313-ecc-and-binding-mode
+     */
+    const eccBindingModeDV = buff.subarray(offset, offset + Header.ECC_BINDING_MODE_BYTE_LEN);
+    const useECDSABinding = eccBindingModeDV[0] >> 7 === 1; // Last bit
+    const ephemeralCurveName = eccBindingModeDV[0] & 0x7; // First 3 bits
+    offset += Header.ECC_BINDING_MODE_BYTE_LEN;
+
+    /**
+     * Symmetric & payload config
+     *
+     * This section contains a 1 byte data structure composed of bitfields that describe the symmetric ciphers for
+     * encrypted payloads. This cipher applies to both the Payload and the Policy of the nanotdf. The fields are as
+     * follows:
+     *
+     * | Section               | Bit Length | Bit start index |
+     * |-----------------------|------------|-----------------|
+     * | HAS_SIGNATURE         | 1          | 7               |
+     * | Signature ECC Mode    | 3          | 4               |
+     * | Symmetric Cipher Enum | 4          | 0               |
+     *
+     * @link https://github.com/virtru/nanotdf/blob/master/spec/index.md#3314-symmetric-and-payload-config
+     */
+    const symmetricPayloadDV = buff.subarray(offset, offset + Header.ECC_BINDING_MODE_BYTE_LEN);
+    const hasSignature = symmetricPayloadDV[0] >> 7 === 1; // Last bit
+    const signatureCurveName = (symmetricPayloadDV[0] >> 4) & 0x7; // Middle 3 bits
+    const symmetricCipher = symmetricPayloadDV[0] & 0xf; // First 4 bits
+    offset += Header.SYMMETRIC_PAYLOAD_CONFIG_BYTE_LEN;
+
+    /**
+     * Policy
+     *
+     * This section contains a Policy object. The data contained in the Policy allows for definition flexible
+     * definitions of a policy including a policy by reference, or an embedded policy. Refer to the Policy object's
+     * definition in Section 3.4.2
+     *
+     * The structure of the Policy is as follows:
+     *
+     * | Section   | Minimum Length (B) | Maximum Length (B) |
+     * |-----------|--------------------|--------------------|
+     * | Type Enum | 1                  | 1                  |
+     * | Body      | 3                  | 257                |
+     * | Binding   | 8                  | 132                |
+     *
+     * @link https://github.com/virtru/nanotdf/blob/master/spec/index.md#3315-policy
+     * @link https://github.com/virtru/nanotdf/blob/master/spec/index.md#342-policy
+     */
+    const { policy, offset: nextOffset } = PolicyFactory.parse(
+      buff.subarray(offset),
+      useECDSABinding,
+      ephemeralCurveName
+    );
+    offset += nextOffset;
+
+    /**
+     * Ephemeral public key
+     *
+     * This section contains a Key object. The size of the key is determined by the Encryption Method Section.
+     *
+     * @link https://github.com/virtru/nanotdf/blob/master/spec/index.md#3316-key
+     */
+    // TODO: Resolve where offset isn't adding 1 byte
+    const ephemeralPublicKeyLength = lengthOfPublicKey(ephemeralCurveName) + 1;
+    const ephemeralPublicKey = buff.subarray(offset, offset + ephemeralPublicKeyLength);
+    offset += ephemeralPublicKeyLength;
+
+    // Check if the ephemeral public key length is not the same length
+    if (ephemeralPublicKey.byteLength !== ephemeralPublicKeyLength) {
+      throw new InvalidFileError('nanotdf parse failure: public key read failure');
+    }
+
+    const header = new Header(
+      magicNumberVersion,
+      kas,
+      useECDSABinding,
+      ephemeralCurveName,
+      hasSignature,
+      signatureCurveName,
+      symmetricCipher,
+      policy,
+      ephemeralPublicKey
+    );
+
+    return {
+      header,
+      offset,
+    };
+  }
+
+  //Ephemeral Public Key
+  // protected _ephemeralPublicKey: string | null = null;
+
+  constructor(
+    magicNumberVersion: Uint8Array,
+    kas: ResourceLocator,
+    useECDSABinding: boolean,
+    ephemeralCurveName: CurveNameEnum,
+    hasSignature: boolean,
+    signatureCurveName: CurveNameEnum,
+    symmetricCipher: CipherEnum,
+    policy: PolicyInterface,
+    ephemeralPublicKey: Uint8Array
+  ) {
+    this.magicNumberVersion = magicNumberVersion;
+    this.kas = kas;
+    this.useECDSABinding = useECDSABinding;
+    this.ephemeralCurveName = ephemeralCurveName;
+    this.hasSignature = hasSignature;
+    this.signatureCurveName = signatureCurveName;
+    this.symmetricCipher = symmetricCipher;
+    this.policy = policy;
+    this.ephemeralPublicKey = ephemeralPublicKey;
+
+    // Auth tag length in bits (i.e. AES GCM 64 bit)
+    this.authTagLength = getBitLength(this.symmetricCipher);
+  }
+
+  /**
+   * Copy the contents of the header to buffer
+   */
+  copyToBuffer(target: Uint8Array): void {
+    if (this.length > target.length) {
+      throw new InvalidFileError('invalid buffer size to copy tdf header');
+    }
+
+    let offset = 0;
+
+    // Write Magic number and version
+    target.set(this.magicNumberVersion, 0);
+    offset += this.magicNumberVersion.length;
+
+    // Write kas resource locator
+    const kasResourceLocatorBuf = this.kas.toBuffer();
+    target.set(kasResourceLocatorBuf, offset);
+    offset += kasResourceLocatorBuf.length;
+
+    // Write ECC & Binding Mode
+    const ecdsaBinding = this.useECDSABinding ? 1 : 0;
+    const eccBingingMode = (ecdsaBinding << 7) | this.ephemeralCurveName;
+    const eccBingingModeAsByte = new Uint8Array(1);
+    eccBingingModeAsByte[0] = eccBingingMode;
+    target.set(eccBingingModeAsByte, offset);
+    offset += eccBingingModeAsByte.length;
+
+    // Write symmetric & payload config
+    const isSignatureEnable = this.hasSignature ? 1 : 0;
+    const symmetricPayloadConfig =
+      (isSignatureEnable << 7) | this.signatureCurveName | this.symmetricCipher;
+    const symmetricPayloadConfigAsByte = new Uint8Array(1);
+    symmetricPayloadConfigAsByte[0] = symmetricPayloadConfig;
+    target.set(symmetricPayloadConfigAsByte, offset);
+    offset += symmetricPayloadConfigAsByte.length;
+
+    // Write the policy
+    const policyBuffer = this.policy.toBuffer();
+    target.set(policyBuffer, offset);
+    offset += policyBuffer.length;
+
+    // Write the ephemeral public key
+    target.set(this.ephemeralPublicKey, offset);
+  }
+
+  /**
+   * Length
+   *
+   * @returns { number } Length of header
+   */
+  get length(): number {
+    return (
+      // Length of the magic number and version
+      this.magicNumberVersion.length +
+      // Length of the KAS resource locator
+      this.kas.length +
+      // ECC & Binding Mode - 1 Bytes
+      1 +
+      // symmetric & payload config - 1 Bytes
+      1 +
+      // Length of the policy
+      this.policy.getLength() +
+      // Length of the ephemeral public key
+      this.ephemeralPublicKey.length
+    );
+  }
+
+  /**
+   * Return nanoTDF header as buffer
+   *
+   * Warning: This method will allocate memory of length of the header, use
+   * copyToBuffer() when copy is not needed.
+   */
+  toBuffer(): ArrayBuffer {
+    const arrayBuffer = new ArrayBuffer(this.length);
+    const target = new Uint8Array(arrayBuffer);
+    this.copyToBuffer(target);
+    return arrayBuffer;
+  }
+
+  /**
+   * Get KAS Rewrap URL
+   */
+  getKasRewrapUrl(): string {
+    try {
+      return `${rstrip(this.kas.url, '/')}/v2/rewrap`;
+    } catch (e) {
+      throw new ConfigurationError(`cannot construct KAS Rewrap URL: ${e.message}`);
+    }
+  }
+}

package/src/nanotdf/models/Payload.ts

@@ -0,0 +1,196 @@
+import Header from './Header.js';
+import { getBitLength } from './Ciphers.js';
+import { ConfigurationError, InvalidFileError } from '../../errors.js';
+
+/**
+ * Payload
+ *
+ * The payload section of the nanotdf contains the ciphertext that is protected by the policy defined in the Header.
+ * The structure of the Payload is as follows:
+ *
+ * | Section               | Minimum Length (B) | Maximum Length (B) |
+ * |-----------------------|--------------------|--------------------|
+ * | Length                | 3                  | 3                  |
+ * | IV                    | 3                  | 3                  |
+ * | Ciphertext            | 0                  | 16777204           |
+ * | Payload MAC (AuthTag) | 8                  | 32                 |
+ */
+export default class Payload {
+  static LENGTH_LEN = 3;
+  static IV_LEN = 3;
+  static MIN_LENGTH = 11;
+  static MAX_NANO_TDF_ENCRYPT_PAYLOAD_SIZE = 16777216; // 3 bytes unsigned int.
+
+  public iv: Uint8Array;
+  public ciphertext: Uint8Array;
+  public authTag: Uint8Array;
+  public ciphertextWithAuthTag: Uint8Array;
+
+  /**
+   * Parse the payload
+   *
+   * Returns a new Payload object and the next offset
+   *
+   * @param buff Uint8Array
+   */
+  static parse(
+    header: Header,
+    buff: Uint8Array,
+    legacyTDF = false
+  ): { payload: Payload; offset: number } {
+    let offset = 0;
+    const authTagByteLength = getBitLength(header.symmetricCipher) / 8;
+
+    /**
+     * Length
+     *
+     * This 3 byte unsigned integer dictates the length of the subsequent ciphertext section.
+     *
+     * NOTE: it includes the IV + Ciphertext + Auth Tag. To get the Auth Tag length you have to subtract the other
+     * lengths
+     */
+    // TODO: This will not work in Big Endian host environments
+    const length = (buff[offset] << 16) + (buff[offset + 1] << 8) + buff[offset + 2];
+    const ciphertextLength = length - Payload.IV_LEN - authTagByteLength;
+    offset += Payload.LENGTH_LEN;
+
+    const inRange = length >= this.MIN_LENGTH && length <= this.MAX_NANO_TDF_ENCRYPT_PAYLOAD_SIZE;
+
+    if (!inRange) {
+      throw new InvalidFileError('nanotdf parse failure: Payload Length Out Of Range');
+    }
+
+    /**
+     * Parse IV
+     *
+     * The IV used for encryption. This value is a byte array containing the IV. This IV must never be reused with the
+     * same symmetric key. Also, to support an extremely compacted version of the nanotdf the IV value 00 00 00 is
+     * reserved for use with an encrypted policy.
+     */
+    let iv = buff.subarray(offset, offset + Payload.IV_LEN);
+    offset += Payload.IV_LEN;
+
+    if (iv.byteLength != 3) {
+      throw new InvalidFileError('nanotdf parse failure: Invalid Payload Length');
+    }
+
+    if (!legacyTDF) {
+      const actuallIV = new Uint8Array(12).fill(0);
+
+      // The the iv from payload to lower-order bits
+      actuallIV.set(iv, 9);
+
+      // update the iv
+      iv = actuallIV;
+    }
+
+    /**
+     * Parse Ciphertext w/ Auth Tag
+     */
+    const ciphertextWithAuthTag = buff.subarray(
+      offset,
+      offset + ciphertextLength + authTagByteLength
+    );
+
+    if (ciphertextWithAuthTag.byteLength + Payload.LENGTH_LEN !== length) {
+      throw new InvalidFileError('nanotdf parse failure: Invalid Payload Length');
+    }
+
+    /**
+     * Parse Ciphertext
+     *
+     * The byte array of the ciphertext that is protected in the nanotdf. The encryption method used to create or decrypt
+     * the ciphertext is defined in the Key Access object in the header.
+     */
+    const ciphertext = buff.subarray(offset, offset + ciphertextLength);
+    offset += ciphertextLength;
+
+    /**
+     * Auth Tag
+     *
+     * GMAC = 8 byte
+     * ECDSA = size of curve
+     *
+     * The MAC of the payload. The Size of this MAC is determined by the Encryption Method Enum used in the Symmetric and
+     * Payload Config object in the header.
+     *
+     * @link https://github.com/virtru/nanotdf/blob/master/spec/index.md#3314-symmetric-and-payload-config
+     */
+    const authTag = buff.subarray(offset, offset + authTagByteLength);
+    offset += authTagByteLength;
+
+    return {
+      payload: new Payload(iv, ciphertext, authTag, ciphertextWithAuthTag),
+      offset,
+    };
+  }
+
+  constructor(
+    iv: Uint8Array,
+    ciphertext: Uint8Array,
+    authTag: Uint8Array,
+    ciphertextWithAuthTag?: Uint8Array
+  ) {
+    this.iv = iv;
+    this.ciphertext = ciphertext;
+    this.authTag = authTag;
+
+    // If ciphertextWithAuthTag is not set then combine it
+    // Ideally it is set so an additional buffer is not needed
+    if (ciphertextWithAuthTag === undefined) {
+      this.ciphertextWithAuthTag = new Uint8Array(ciphertext.length + authTag.length);
+      this.ciphertextWithAuthTag.set(ciphertext);
+      this.ciphertextWithAuthTag.set(authTag, ciphertext.length);
+    } else {
+      this.ciphertextWithAuthTag = ciphertextWithAuthTag;
+    }
+  }
+
+  /**
+   * Length
+   *
+   * @returns { number } Length of signature
+   */
+  get length(): number {
+    return (
+      // Bytes(3) to hold the length of the payload
+      3 +
+      // Length of the IV
+      this.iv.length +
+      // Length of the ciphertext
+      this.ciphertext.length +
+      // Length of the auth tag
+      this.authTag.length
+    );
+  }
+
+  /**
+   * Copy the contents of the signature to buffer
+   */
+  copyToBuffer(target: Uint8Array): void {
+    if (this.length > target.length) {
+      throw new Error('internal: invalid buffer size to copy payload');
+    }
+
+    const lengthOfEncryptedPayload = this.iv.length + this.ciphertext.length + this.authTag.length;
+    if (lengthOfEncryptedPayload > Payload.MAX_NANO_TDF_ENCRYPT_PAYLOAD_SIZE) {
+      throw new ConfigurationError("TDF encrypted payload can't be more that 2^24");
+    }
+
+    const lengthAsUint32 = new Uint32Array(1);
+    lengthAsUint32[0] = lengthOfEncryptedPayload;
+
+    const lengthAsUint24 = new Uint8Array(lengthAsUint32.buffer);
+
+    // NOTE: We are only interested in only first 3 bytes.
+    const payloadSizeAsBg = new Uint8Array(3);
+    payloadSizeAsBg[0] = lengthAsUint24[2];
+    payloadSizeAsBg[1] = lengthAsUint24[1];
+    payloadSizeAsBg[2] = lengthAsUint24[0];
+
+    target.set(payloadSizeAsBg, 0);
+    target.set(this.iv, payloadSizeAsBg.length);
+    target.set(this.ciphertext, payloadSizeAsBg.length + this.iv.length);
+    target.set(this.authTag, payloadSizeAsBg.length + this.iv.length + this.ciphertext.length);
+  }
+}

package/src/nanotdf/models/Policy/AbstractPolicy.ts

@@ -0,0 +1,90 @@
+import PolicyInterface from '../../interfaces/PolicyInterface.js';
+import PolicyType from '../../enum/PolicyTypeEnum.js';
+import { ConfigurationError } from '../../../errors.js';
+
+abstract class AbstractPolicy implements PolicyInterface {
+  static readonly TYPE_BYTE_OFF = 0;
+  static readonly TYPE_BYTE_LEN = 1;
+  static readonly BODY_BYTE_OFF = 1;
+  static readonly BODY_BYTE_MIN_LEN = 3;
+  static readonly BODY_BYTE_MAX_LEN = 257;
+  static readonly BINDING_BYTE_MIN_LEN = 8;
+  static readonly BINDING_BYTE_MAX_LEN = 132;
+  static readonly SIZE_OF_LENGTH_FIELD = 1; // 1 byte for each length field (R and S)
+  static readonly GMAC_BINDING_LEN = 8;
+
+  readonly type: PolicyType;
+  readonly binding: Uint8Array;
+
+  // Static methods can't be defined in an interface
+  static parse(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    buff: Uint8Array,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    useECDSABinding: boolean,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    type?: PolicyType
+  ): { policy: PolicyInterface; offset: number } {
+    throw new ConfigurationError('parsePolicy was not implemented');
+  }
+
+  constructor(type: PolicyType, binding: Uint8Array) {
+    this.type = type;
+    this.binding = binding;
+  }
+
+  /**
+   * Length of policy
+   */
+  getLength(): number | never {
+    throw new ConfigurationError('length was not implemented');
+  }
+
+  /**
+   * Return the content of the policy
+   */
+  toBuffer(): Uint8Array | never {
+    throw new ConfigurationError('toBuffer() was not implemented');
+  }
+
+  /**
+   * Parses an ECDSA binding from a given buffer.
+   *
+   * @param {Uint8Array} buff - The buffer containing the ECDSA binding.
+   * @returns {{ bindingLength: number; binding: Uint8Array }} - An object containing the binding length and the binding subarray.
+   */
+  static parseECDSABinding(buff: Uint8Array): { bindingLength: number; binding: Uint8Array } {
+    const lengthOfR = buff[0];
+    const lengthOfS = buff[this.SIZE_OF_LENGTH_FIELD + lengthOfR];
+
+    const bindingLength =
+      this.SIZE_OF_LENGTH_FIELD + lengthOfR + this.SIZE_OF_LENGTH_FIELD + lengthOfS;
+    const binding = buff.subarray(0, bindingLength);
+
+    return { bindingLength, binding };
+  }
+
+  /**
+   * Parses a binding from a given buffer based on the specified binding type.
+   *
+   * @param {Uint8Array} buff - The buffer containing the binding.
+   * @param {boolean} useEcdsaBinding - Flag indicating whether to use ECDSA binding.
+   * @param {number} offset - The starting offset in the buffer.
+   * @returns {{ binding: Uint8Array; newOffset: number }} - An object containing the binding and the new offset.
+   */
+  static parseBinding(
+    buff: Uint8Array,
+    useEcdsaBinding: boolean,
+    offset: number
+  ): { binding: Uint8Array; newOffset: number } {
+    if (useEcdsaBinding) {
+      const ecdsaBinding = this.parseECDSABinding(buff.subarray(offset));
+      return { binding: ecdsaBinding.binding, newOffset: offset + ecdsaBinding.bindingLength };
+    } else {
+      const binding = buff.subarray(offset, offset + this.GMAC_BINDING_LEN);
+      return { binding, newOffset: offset + this.GMAC_BINDING_LEN };
+    }
+  }
+}
+
+export default AbstractPolicy;