Stormshield SDK v5.0.0

Environment Setup ​

Install package ​

Content ​

The archive (sdsdk-deliverable.tgz) provided by Stormshield contains:

  • sdsdk.tgz: Contains the SDSDK package in 3 builds: an ESM build and a CJS build (both with externalized dependencies) for npm-based environments, and a standalone ESM bundle (with all dependencies included) for static HTML pages.
  • 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. In a folder containing the archive and the SHA256 hash, execute the following command:

bash
sha256sum -c sdsdk_sha256.txt

Compatibility ​

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

PlatformVersion
Node.js20+
Firefox146+
Chromium145+

Installation in Node.js (via npm) ​

Install the package with npm:

bash
npm install ./sdsdk.tgz

Then you can use the SDK in your code as follows.

ESM ​

javascript
import { Sdsdk } from 'sdsdk';

const sdsdk = new Sdsdk(/* ... */); // see "Class: Sdsdk" page

CJS ​

javascript
const { Sdsdk } = require('sdsdk');

const sdsdk = new Sdsdk(/* ... */); // see "Class: Sdsdk" page

Installation in a web application (via a bundler) ​

This is the recommended approach for modern web applications built with tools like Vite, webpack, esbuild, Rollup, or frameworks such as Next.js, Nuxt, SvelteKit or Astro. The bundler will resolve and bundle the SDK's dependencies automatically, and handle deduplication, tree-shaking, and upgrades.

Install the package with npm in your web project:

bash
npm install ./sdsdk.tgz

Then import the SDK directly in your source code:

javascript
import { Sdsdk } from 'sdsdk';

const sdsdk = new Sdsdk(/* ... */); // see "Class: Sdsdk" page

Your bundler will automatically pick the correct build from the package's exports map and include the necessary dependencies in your final application bundle.

Note: When using a bundler, the SDK's runtime dependencies are resolved from your project's node_modules and can be updated independently of the SDK. This allows you to apply security patches to these dependencies without waiting for a new SDSDK release.

Installation in a static HTML page (standalone bundle) ​

This approach is intended for environments where running a bundler is not possible or desirable, such as:

  • A static HTML page served without any build step
  • An air-gapped environment without access to a package registry
  • A quick prototype, demo, or educational context

The standalone build is a single self-contained ESM file that includes all runtime dependencies. It can be loaded directly by a modern browser via a <script type="module"> tag.

Unpack the SDK archive:

bash
tar -xzf sdsdk.tgz
# This creates a "package/" directory containing the SDK

Important: The standalone bundle is an ES module and must be served over HTTP(S). It cannot be loaded via the file:// protocol (i.e. by opening your HTML file directly in the browser) due to browser CORS restrictions on ES modules. See MDN — JavaScript modules for details.

Then reference the standalone bundle from your HTML page, using a path relative to your HTTP server root:

html
<!doctype html>
<html>
  <head>
    <script type="module">
      import { Sdsdk } from './package/dist/standalone.mjs';

      const sdsdk = new Sdsdk(/* ... */); // see "Class: Sdsdk" page
      // Make it available globally if needed:
      window.sdsdk = sdsdk;
    </script>
  </head>
  <body></body>
</html>

Important: The standalone bundle includes pinned versions of all dependencies. Unlike the bundler-based installation, you cannot independently update these dependencies — you must wait for a new SDSDK release to receive security patches. For this reason, the bundler-based approach is strongly recommended when feasible.

KAS ​

The Key Access Server (KAS) is the server that enables you to securely store your keys.

KAS module provided by Stormshield SaaS ​

The easiest way to set up a tenant with a KAS module is through the SaaS solution provided by Stormshield.

To set up your own tenant, contact us.

On-premise deployment ​

The SDSDK is compatible with Stormshield KMaaS 4.5, refer to the KMaaS documentation for more information.

Network ​

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

Egress traffic URL:

DeploymentURL
On-premiseURL of the server hosting the service (refer to KMaaS documentation for more information)
SaaShttps://cse.mysds.io

HTTP endpoints:

EndpointDescription
https://<kmaas-url>/api/v1/<tenant-id>/kas/encryptKMaaS KAS encrypt endpoint
https://<kmaas-url>/api/v1/<tenant-id>/kas/decryptKMaaS KAS decrypt endpoint
https://<kmaas-url>/api/v1/<tenant-id>/kas/rewrapKMaaS KAS rewrap endpoint

HTTP methods:

MethodDescription
POSTUsed to contact the KAS endpoints
OPTIONSUsed for Cross-Origin Resource Sharing (CORS) preflight requests, in web environment

Authentication setup ​

To communicate with the KMaaS, you must choose between two authentication method:

  • JWT Token (recommended)
  • API Key (basic mode)

For more information on authentication, refer to the KMaaS documentation.

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

For 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:

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