Environment Setup

Install package

Content

The archive provided by stromshield 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 you separately with the file sdsdk_sha256.txt, which contains the SHA256 hash of the archive.

Check integrity

It is recommended to check the integrity of the archive prior to manipulation:

sha256sum -c sdsdk_sha256.txt

Compatibility

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

Platform	Version
Node.js	20
Firefox	139
Chromium	138

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. You must configure a Crypto API application in your KMaaS. For more information, refer to the KMaaS documentation section 7.

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>/crypto/encrypt	KMaaS Crypto API encrypt endpoint
https://<kmaas-url>/api/v1/<tenant-id>/crypto/decrypt	KMaaS Crypto API decrypt endpoint

HTTP methods:

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

Authentication setup

To communicate with KMaaS, you must use one of the two authentication methods: JWT Token (recommended) or Api Key (basic mode). For more information on authentication, refer to section 7.2.2.1 of the KMaaS documentation.

If you have chosen the JWT option, you must obtain a token from your provider before using the encryption or decryption functions.

For the API key you need to form the API key with the values provided in your configuration. To generate the API key from the information entered in the crypto API configuration of your KMaaS you must form the following string: base64(<your-api-key-name>:<your-api-key-value>)

In bash:

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