Function: ztdfEncrypt(encryptParams: ZtdfEncryptParameters)

The ztdfEncrypt function performs symmetric or asymmetric encryption of data using the Zero Trust Data Format (ZTDF). Two keyAccessProtocols are supported for DEK wrapping:

• symmetric_kas: Online encryption. Requires communication with the KAS to wrap the DEK.
• kas: Offline encryption. The DEK is wrapped locally using a provided public key.

Description

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

symmetric_kas(Online encryption)

kas (Offline encryption)

Parameters

sdsdkEncryptParameters: object containing encryption parameters.

data

• Type: Uint8Array
• Max Length: No hard functional limit in the API. When data exceeds 10 MB, the SDK automatically splits it into segments (“chunks”) to optimize memory usage and transfer performance. However, The maximum size of a Uint8Array supported by the user’s runtime environment (Node.js, browser, or other platform) is an effective limit.
• 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, refer to pages 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. Supported values are: symmetric_kas | kas.

kas.authentication.mode

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

kas.authentication.value

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

kas.publicKey.kid

• Type: string
• Description: Unique identifier of the asymmetric key in the remote KAS.
• Required when using keyAccessProtocol kas.

kas.publicKey.value

• Type: string
• Description: Value of the public key KEK. Must be in PEM spki format.
• Required when using keyAccessProtocol kas.

assertions (optional)

• Type: array
• Description: Assertions are verifiable statements about the ZTDF or its payload. Assertions must follow the pattern described in the table below. Note that adding a large number of attributes can cause slowdowns or errors. The SDSDK verifies the assertion syntax but does not verify if the assertions complies to standards (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)	Indicates how the statement.value property is provided. If the property value is “string” or “object”, then the type of the statement.value field must match.
statement.schema	(string)	A URI referencing the schema used for the statement.value property.
statement.value	unknown	The actual value of the assertion, its type depends on the statement.format.

Return

Promise containing an SdsdkZtdf object representing the encrypted ZTDF container.

Examples

With keyAccessProtocol symmetric_kas

import { ztdfEncrypt } from 'sdsdk';

const encryptParams = {
  data: new TextEncoder().encode('Data to be encrypted'),
  mimeType: 'application/octet-stream',
  dataAttributes: [{ attribute: 'value' }],
  kas: {
    keyAccessProtocol: 'symmetric_kas',
    baseKasUrl: 'https://cse.mysds.io',
    tenantId: '26fc18f0-9ac3-4c20-b2a5-fcfe5a81eb1b',
    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);
});

With keyAccessProtocol kas

import { ztdfEncrypt } from 'sdsdk';

const encryptParams = {
  data: new TextEncoder().encode('Data to be encrypted'),
  mimeType: 'application/octet-stream',
  dataAttributes: [{ attribute: 'value' }],
  kas: {
    keyAccessProtocol: 'kas',
    baseKasUrl: 'https://cse.mysds.io',
    tenantId: '26fc18f0-9ac3-4c20-b2a5-fcfe5a81eb1b',
    publicKey: {
      kid: 'c1286dbf-4e0b-4457-a713-249d476a2d2e',
      value: `-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAlG9PuYhipZmIT3CMmmZY
PsjPY3HngEt6DUiIGimhHnRsXz0AiUmdjzu0Trz/zB0gHXKSps1LlLbVr0xlDYs6
ATCcKvIECpD7cpUCzm3zUrM9lfDmdO+5bRoVnVMdm3lfuQo3kImZgF2KQHKlNckH
PniHNSD2AfNiIg5fATA2C3bOBbUM5irzfPsZcAG2FQXTY7Ehsy+6pzlFirkW6K75
5ri70LmVEk606fR/WhLhf9holtHTbjxxP7TicExmySOxkd+E62DfRxf2j1jnnk10
AqGcuiQroe3prIqrrGqvTxdyYt8uI5Z4p9KxAShMqc5OW0m+Shb0yksBcjkspsr3
iLWQa7kbfu4orU/s2paWfLskOHyXR4rMswQlmtQw28rUs0PngvUtUUTKG4bkVuYn
qTTPKDuT7YLzAI8DqnhQcCvTV2CZ/BFYtofo01rjDSs3//XiQvhTlZtWL8xjJTEl
eY2LoXdLCCayKovzGBtxrmI0fSpR1puuycYf/6/BzMpaEhZMOA1cWmKWO5ndrdPV
iDu2/iiLTyAeNZT5zSc53UZRdyWtBLGDbQEe+bV1Pzn2iDfLlzeUnKulLv0bpywK
RhwvMI4HZSwM6iKIv1+4Bbo2uPt8qdFsoJOX9TJqizGmYPQ91etNVFhIc8Qu3C4c
ff5LSaOn+qG9S0rzo61dP6kCAwEAAQ==
-----END PUBLIC KEY-----`,
    },
  },
  assertions: [
    {
      id: 'assertion1',
      scope: 'payload',
      type: 'handling',
      appliesToState: 'unencrypted',
      statement: {
        format: 'xml-structured',
        schema: 'uri:test',
        value: 'xml-structured value',
      },
    },
  ],
};

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