Function: ztdfEncrypt(encryptParams: ZtdfEncryptParameters)

The ztdfEncrypt function performs symmetric encryption of data using the Zero Trust Data Format (ZTDF).

Description

This function takes a ZtdfEncryptParameters object as input, which contains the encryption parameters.

Parameters

sdsdkEncryptParameters: object containing encryption parameters.

data

• Type: Uint8Array
• Max Length: 10Mo
• Description: Data to be encrypted.

mimeType

• Type: string
• Description: MIME type of the data.

dataAttributes

• Type: array
• Description: Array of attributes related to the data to be encrypted. Can be an empty array.

Data attributes are used during the decryption process to enforce Attribute-Based Access Control (ABAC). These attributes enable granular authorization decisions by verifying that the requesting user or system meets the defined security policies before granting access to encrypted data. For more information, please refer to the page How ABAC work in stormshield encryption platform and Decryption workflow

kas.baseKasUrl

• Type: string
• Description: Base URL of the KAS.

kas.tenantId

• Type: string
• Description: Tenant ID of the KAS.

kas.keyAccessProtocol

• Type: string
• Description: Key access protocol (currently only "symmetric_kas" is supported).

kas.authentication.mode

• Type: string
• Description: Authentication mode ("basic" or "bearer"). For more information refer to Authentication setup.

kas.authentication.value

• Type: string
• Description: Authentication value (API key or JWT value). For more information refer to Authentication setup.

assertions (optional)

• Type: array
• Description: Assertions are verifiable statements about the ZTDF or its payload. An assertion must follow the following pattern. A large number of attributes can cause slowdowns or errors. The SDSDK verifies the syntactic integrity of an assertion but does not verify that the assertions follow a standard (e.g., ACP-240).

Property	Type	Description
id	(string)	The assertion's identifier. This value is free and must be unique within the manifest (two different assertions cannot have the same id in the same manifest).
type	(string)	"handling" or "other".
scope	(string)	"tdo" or "payload", defines what the assertion relates to.
appliesToState	(optional string)	"encrypted" or "unencrypted", indicates if the "statement" applies to the encrypted or plaintext data. The "appliesToState" property should only be used under the following conditions: The assertion type is "handling" AND the assertion scope is "payload".
statement	(object)	An object that contains the assertion's value
statement.format	(string)	"string" or "object", indicates how the statement.value property is provided.
statement.schema	(string)	A URI referencing the schema used for the statement.value property.
statement.value	(string or object)	The actual value of the assertion, its type depends on the statement.format.

Return

Promise containing an SdsdkZtdf object representing the encrypted ZTDF container.

Example

const { ztdfEncrypt } = require('sdsdk');

const encryptParams = {
  data: new TextEncoder().encode('Data to be encrypted'),
  mimeType: 'application/octet-stream',
  dataAttributes: [{ attribute: 'value' }],
  kas: {
    baseKasUrl: 'https://cse.mysds.io',
    tenantId: '26fc18f0-9ac3-4c20-b2a5-fcfe5a81eb1b',
    keyAccessProtocol: 'symmetric_kas',
    authentication: {
      mode: 'basic',
      value: 'dGVzdEFwaUtleTpvY2dZ...L0x4Vw==',
    },
    assertions: [
      {
        id: 'assertion1',
        scope: 'payload',
        type: 'handling',
        appliesToState: 'unencrypted',
        statement: {
          format: 'string',
          schema: 'uri:test',
          value: 'assertion1 value',
        },
      },
    ],
  },
};

ztdfEncrypt(encryptParams).then((result) => {
  console.log(result.manifest);
  console.log(result.payload);
});