Class: Sdsdk

The Sdsdk class is the central entry point of the SDK. It holds the KAS configuration and exposes the encrypt and decrypt methods.

An Sdsdk instance is stateful: its configuration impacts encryption and decryption behavior, DEK wrapping strategies, and access control enforcement.

Constructor

new Sdsdk(configuration: SdsdkConfiguration)

SdsdkConfiguration

Object containing Sdsdk configuration.

• defaultKasId (String) The default KAS identifier. It must match one of the kasList IDs and determines which KAS will be used for decryption.

• kasList (Array) List of KAS, where each KAS is a RemoteKas or a LocalKas.

  RemoteKas

  • id (String) Unique identifier for the KAS. Any non-empty string of your choice. Id must be unique in the kasList.
  • protocols (Array) List of protocols supported by the KAS ('kas' or 'symmetric_kas').
  • url (String) URL of the remote KAS.
  • authentication (Object) RemoteKas authentication. ⚠️ secret
    • type (String) 'bearer' | 'basic'
    • value (String) The raw JWT value for 'bearer' or the Base64(user:password) for 'basic' (see: RemoteKas authentication setup)
  • optional publicKey (Object) Public key used for DEK encryption. Required when protocols includes 'kas'. (see: RemoteKas setup)
    • kid (String) Unique identifier of the asymmetric key in the remote KAS.
    • value (String) Value of the public key in PEM format.
  LocalKas

  • id (String) Unique identifier for the KAS. Any non-empty string of your choice. Id must be unique in the kasList.
  • protocols (Array) List of protocols supported by the KAS ('local_symmetric_kas').
  • kek (Uint8Array) Key Encryption Key used for DEK wrapping. It must be a 32-byte Uint8Array generated with a true random number generator (TRNG). ⚠️ secret :::List of ⚠️ The kasList can only contain 1 LocalKas.

• optional mapping (Array) Configuration to dynamically select some KAS in the kasList depending on dataAttributes sent during encryption. List of MappingItem.

  MappingItem

  • attributeName (String) Name of the attribute. Will match dataAttributes with top-level key matching the referenced value.
  • type (String) Only supported value is MappingItemType.Permissive ('permissive') that applies the logical gate 'OR' to KAS selection resolution.
  • attributeValues (Array) List of AttributeValues.
    • value (String) Value of the dataAttributes to map. Will match the top-level keys of dataAttributes objects.
    • kasIds[] (Array) List of KAS IDs. Each id must exist in the kasList.

---

Examples

Minimal configuration - single RemoteKas - Protocol kas

import { Sdsdk, SdsdkConfiguration, Protocol } from 'sdsdk';

const config: SdsdkConfiguration = {
  defaultKasId: 'kas-1',
  kasList: [
    {
      id: 'kas-1',
      protocols: [Protocol.Kas],
      url: 'https://kas.example.com/api/v1/kas',
      publicKey: {
        kid: 'my-kid',
        value: '-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----',
      },
      authentication: { // <- can be ommitted when using only encryption, but required for decryption
        type: 'bearer',
        value: 'my-jwt-token', // ⚠️ **secret**
      },
    },
  ],
};

const sdsdk = new Sdsdk(config);

Minimal configuration - single RemoteKas - Protocol symmetric_kas

import { Sdsdk, SdsdkConfiguration, Protocol } from 'sdsdk';

const config: SdsdkConfiguration = {
  defaultKasId: 'kas-1',
  kasList: [
    {
      id: 'kas-1',
      protocols: [Protocol.SymmetricKas],
      url: 'https://kas.example.com/api/v1/kas',
      authentication: {
        type: 'bearer',
        value: 'my-jwt-token', // ⚠️ **secret**
      },
    },
  ],
};

const sdsdk = new Sdsdk(config);

Minimal configuration - single LocalKas

import { Sdsdk, SdsdkConfiguration, Protocol } from 'sdsdk';

const kek = crypto.getRandomValues(new Uint8Array(32));

const config: SdsdkConfiguration = {
  defaultKasId: 'local-kas',
  kasList: [
    {
      id: 'local-kas',
      protocols: [Protocol.LocalSymmetricKas],
      kek, // ⚠️ **secret**
    },
  ],
};

const sdsdk = new Sdsdk(config);

Advanced multiKas configuration with mapping

import { MappingItemType, Sdsdk, SdsdkConfiguration, Protocol } from 'sdsdk';

const config: SdsdkConfiguration = {
  defaultKasId: 'kas-1',
  kasList: [
    {
      id: 'kas-1',
      protocols: [Protocol.Kas, Protocol.SymmetricKas], // <- RemoteKas can support both protocols
      url: 'https://kas-1.example.com/api/v1/cb724d79-51e8-4816-b200-c0e88751bf89/kas',
      publicKey: {
        kid: 'my-kid',
        value: '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqh[...]IBCgKCAQEA\n-----END PUBLIC KEY-----',
      },
      authentication: {
        type: 'basic',
        value: 'my-api-key', // ⚠️ **secret**
      },
    },
    {
      id: 'kas-2',
      protocols: [Protocol.Kas], // <- ... Or only one
      url: 'https://kas-2.example.com/api/v1/0f076525-684d-4289-9e09-3b2b105a6295/kas',
      publicKey: {
        kid: 'my-kid',
        value:
          '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQ[...]EFAAOCAQ8AMIIBCgKCAQEA\n-----END PUBLIC KEY-----',
      },
      authentication: {
        type: 'bearer',
        value: 'my-jwt-token', // ⚠️ **secret**
      },
    }
  ],
  /** **optional** for dynamic KAS selection based on dataAttributes
   *  In this example mappingConfiguration, when using the instance to encrypt data:
   * - when dataAttributes are [{releasableTo: 'FRA'}] -> sdk will encrypt for KASs 'kas1' and 'kas2'
   * - when dataAttributes are [{releasableTo: 'EN'}] -> sdk will encrypt for KAS with id 'kas2'
   * - when dataAttributes are [{releasableTo: 'FRA'}, {releasableTo: 'EN'}] -> sdk will encrypt for KASs 'kas1' and 'kas2'
   * - when dataAttributes are [{releasableTo: 'FRA'}, {releasableTo: 'ITA'}] -> sdk with throw SdsdkError (the value 'ITA' is not present in the mappingConfiguration)
   * - when dataAttributes are [{releasableTo: 'FRA'}, {anyOtherKey: 'anyValue'}] -> sdk will encrypt for KASs 'kas1' and 'kas2'
   * - when dataAttributes are [] or [{keyNotInMapping: 'anyValue'}] -> sdk with throw SdsdkError (no mappable key in dataAttributes)
   *  
   * */
  mapping: [
    {
      attributeName: 'releasableTo', // <- maps to dataAttributes with key: 'releasableTo'
      type: MappingItemType.Permissive,
      attributeValues: [
        {
          value: 'FRA', // <- maps to dataAttributes with key 'releasableTo' and value: 'FRA'
          kasIds: ['kas-1', 'kas-2'], // <- refers to ids in the KasList
        },
        {
          value: 'EN',
          kasIds: ['kas-2'],
        },
      ],
    },
  ],
};