Environment Setup

Install package

Content

The archive provided by Stormshield contains:

• sdsdk.tgz: Contains the SDSDK package in 3 formats: UMD, MJS and CJS for Node and Web platforms. Theses platforms are different in terms of use and installation.
• sbom: Folder containing Software Bill of Materials (SBOM)
  • sbom-all.json: Complete SBOM - Software Bill of Materials - This file includes a comprehensive list of all dependencies, covering both production and development dependencies, providing a full overview of the software components.
  • sbom-prod.json: Production SBOM - Software Bill of Materials - This file lists only the production dependencies.

Stormshield provides the sdsdk_sha256.txt file separately. It contains the SHA256 hash of the archive

Check integrity

It is recommended to check the integrity of the archive before use:

sha256sum -c sdsdk_sha256.txt

Compatibility

Stormshield guarantees the correct functioning of the SDK on the following versions:

Platform	Version
Node.js	20
Firefox	142
Chromium	141

Installation in Node.js environments (via npm)

Install package with npm

npm install ./sdsdk.tgz

Then, you can use sdsdk in your code as follows:

import { ztdfEncrypt } from 'sdsdk';

const ztdf = await ztdfEncrypt(...)

Installation in Web environments (HTML)

## Unpack SDK
tar -xzf sdsdk.tgz

To use the UMD format, add the following tag:

<script src="./path-to-sdsk/sdsdk/dist/sdsdk.js"></script>

To use the ESM format, add the following tag:

<script type="module">
  // Import exemple
  import { ztdfEncrypt, ztdfDecrypt } from './path-to-sdsk/sdsdk/dist/sdsdk.mjs';
  ztdfEncrypt(...)
</script>

KAS setup

The Key Access Server (KAS) is the server that enables you to securely store your keys. The SDSDK is compatible with Stormshield KMaaS 4.5, refer to the KMaaS documentation for more information.

• If you want to use the 'symmetric_kas' protocol you must provide symmetric KEKs.
• If you want to use the 'kas' protocol you must provide asymmetric KEKs.

For more information on generating KEKs refer to the KMaaS documentation.

Network

To ensure communication, the SDSDK must be able to contact the KAS server via HTTPS.

Egress traffic URL:

Deployment	URL
On-premise	URL of the server hosting the service (refer to KMaaS documentation for more information)
SaaS	https://cse.mysds.io

HTTP endpoint:

Endpoint	Description
https://<kmaas-url>/api/v1/<tenant-id>/kas/encrypt	KMaaS KAS encrypt endpoint
https://<kmaas-url>/api/v1/<tenant-id>/kas/decrypt	KMaaS KAS decrypt endpoint
https://<kmaas-url>/api/v1/<tenant-id>/kas/rewrap	KMaaS KAS rewrap endpoint

HTTP methods:

Method	Description
POST	Used to contact the KAS endpoints
OPTIONS	Used for Cross-Origin Resource Sharing (CORS) preflight requests, in web environment

Authentication setup

To communicate with the KMaaS, you must choose an authentication method: either JWT Token (recommended), or API Key (basic mode). For more information on authentication, refer to the KMaaS documentation.

With the JWT option, you must obtain a token from your provider before using the encrypt or decrypt functions.

With the API key option, you must generate the API key based on the information provided in the KAS configuration of your KMaaS. You must provide the following string: base64(<your-api-key-name>:<your-api-key-value>)

In bash:

echo '<your-api-key-name>:<your-api-key-value>' | base64