Method: Sdsdk.encrypt

Description

The encrypt method performs symmetric or asymmetric encryption of data using the Zero Trust Data Format (ZTDF).

Protocol.SymmetricKas (symmetric_kas): Online encryption. Online decryption.

Requires communication with the RemoteKas to wrap the DEK. A RemoteKasConfiguration with authentication is required. Supports ABAC through dataAttributes.

Encryption workflow overview

Protocol.Kas (kas): Offline encryption. Online decryption.

The DEK is wrapped locally using a provided public key. A RemoteKasConfiguration with PublicKey is required. Supports ABAC through dataAttributes.

Encryption workflow overview

Protocol.LocalSymmetricKas (local_symmetric_kas): Offline encryption. Offline decryption.

The DEK is wrapped locally with the provided KEK. A LocalKasConfiguration is required. Does not support ABAC through dataAttributes.

Encryption workflow overview

MultiKas encryption

The encrypt method enables multi-KAS encryption of the DEK. If the kasList contains several KAS, then the DEK generated by the SDSDK can be encrypted by multiple KAS.

The KAS selection process depends on the presence of a mapping configured on the SDSDK instance:

Without mapping

If no mapping is configured:

• The KAS used for encryption are all the KAS configured in the kasList that support the requested Protocol.
• If no KAS supports the requested Protocol, an explicit error will be thrown during encryption.

With a mapping

If a mapping is configured:

• The KAS used for encryption are a selection of the KAS configured in the kasList. This selection is computed based on the mapping and the dataAttributes.
• If at least one KAS in the computed selection does not support the requested Protocol, an explicit error is thrown during encryption.
• If no KAS matches, an explicit error will be thrown during encryption

Parameters

encryptParameters: The encryptParameters object contains the following properties:

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”).
  • The effective limit depends on the maximum Uint8Array size supported by the runtime environment (Node.js, browser, etc.).
• Description: Data to be encrypted.

protocol (optional)

• Type: Protocol
• Description: Protocol used to wrap the Data Encryption Key (DEK).
• Default: Protocol.Kas (kas)

mimeType (optional)

• Type: string
• Description: MIME type of the data.
• Default: application/octet-stream

dataAttributes (optional)

• Type: array
• Description: Array of attributes related to the data to be encrypted. Can be an empty array. If not set, will default to empty array.

Each DataAttribute can be any value. It is generally recommended to use simple objects containing simple key value pairs.

ABAC based on dataAttributes

Data attributes are embedded in the manifest during encryption, and 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 works in the Stormshield Encryption Platform and Decryption workflow.

KAS selection based on dataAttributes

If a mapping is configured on the SDK instance, dataAttributes are evaluated during the encryption process to dynamically select some KAS of the kaslist.

Mapping rules for KAS selection

The dataAttributes that match the following rules will be considered as MapperDataAttribute used for KAS selection resolution:

• Must be an object (no array, no class instance, ...).
• The object must have a top-level key matching the mapping.attributeName. The value should be a string matching the mapping.attributeValues[].value. If the key matches, but the value does not exist in a mapping.attributeValues, an error will be thrown during encryption.
• The object may have non matching keys or nested keys. They will be ignored by the KAS selection algorithm.
• If several top-level keys of an object match with the mapping, they will all be evaluated by the KAS selection algorithm.

For an example of KAS selection resolution based on mapping, see Sdsdk configuration example

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 validates assertion syntax but does not verify compliance with external standards (e.g., ACP-240).

Property	Type	Description
id	(string)	The assertion 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 must be used only if the assertion type is "handling" AND the assertion scope is "payload".
statement	(object)	An object that contains the assertion 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

Returns a Promise resolving to a Ztdf object.

Examples

const encryptParams = {
  // Data to encrypt
  data: new TextEncoder().encode('Data to be encrypted'),
  // Data attributes used for kas selection or ABAC
  dataAttributes: [{ releasbleTo: 'FR' }],
  // Assertions values
  assertions: [
    {
      id: 'assertion1',
      scope: 'payload',
      type: 'handling',
      appliesToState: 'unencrypted',
      statement: {
        format: 'xml-structured',
        schema: 'uri:test',
        value: 'xml-structured value',
      },
    },
  ],
  // Protocol used for wrap Data Encryption Key (DEK)
  protocol: Protocol.Kas,
};

// sdsdkInstance is an instance of the Sdsdk class
const result = await sdsdkInstance.encrypt(encryptParams);

console.log(result.manifest);
console.log(result.payload);
console.log(result.toZip()); // Uint8Array
//encrypted data can be persisted in a file, or other