Deployment Configuration

Overview

This page documents the JSON fields used by SST .graph files, including Auth definitions, entity definitions, trust relationships, assignments, and file sharing policy.

The .graph file is a JSON topology document consumed by the generator scripts in examples/. It describes Auth nodes, entity nodes, Auth trust relationships, entity-to-Auth assignment, and optional file sharing policy.

The default graph is:

examples/configs/default.graph

Top-level fields

Field	Type	Purpose
authList	array	Auth server definitions.
authTrusts	array	Trust relationships between Auth servers.
assignments	object	Maps entity names to their primary Auth ID.
entityList	array	Client, server, publisher, subscriber, and other entity definitions.
filesharingLists	array	Optional file sharing access-control definitions.

authList

Each object in authList defines one Auth instance.

{
  "id": 101,
  "entityHost": "localhost",
  "authHost": "localhost",
  "tcpPort": 21900,
  "udpPort": 21902,
  "authPort": 21901,
  "callbackPort": 21903,
  "dbProtectionMethod": 1,
  "backupEnabled": false,
  "contextualCallbackEnabled": true
}

Property	Meaning
id	Integer Auth ID used by assignments and generated configs.
entityHost	Hostname/IP used by entities to reach Auth.
authHost	Hostname/IP used for Auth-to-Auth communication.
tcpPort	TCP port for entity session key requests.
udpPort	UDP port for entity requests when UDP is used.
authPort	Port for trusted Auth communication.
callbackPort	Port for contextual callback handling.
dbProtectionMethod	Database protection mode used by Auth DB generation.
backupEnabled	Enables backup-related Auth behavior when supported by the graph and Auth config.
contextualCallbackEnabled	Enables contextual callback support for Auth.

authTrusts

authTrusts declares trusted relationships between Auth instances.

"authTrusts": [
  {
    "id1": 101,
    "id2": 102
  }
]

This allows policies and migration workflows that involve entities assigned to different Auth instances.

assignments

assignments maps an entity name to the Auth ID that owns the entity registration.

"assignments": {
  "net1.client": 101,
  "net1.server": 101,
  "net2.client": 102
}

Every entity in entityList should have a matching assignment unless the generator intentionally skips that entity type.

entityList

Each object in entityList defines an entity and its generated runtime configuration.

Common properties:

Property	Meaning
group	Logical group such as Clients, Servers, PtPublishers, or PtSubscribers.
name	Unique entity name, usually network.entityName.
distProtocol	Protocol used for distribution/session-key communication, usually TCP or UDP.
usePermanentDistKey	true for pre-shared permanent distribution keys; false for public/private key credentials.
distKeyValidityPeriod	Distribution key validity such as 1*hour or 365*day.
maxSessionKeysPerRequest	Maximum session keys Auth can return for one request.
netName	Network name used to place generated configs and credentials.
credentialPrefix	Prefix used when generating credential file names.
distributionCryptoSpec	Cipher/MAC settings for the Auth distribution channel.
sessionCryptoSpec	Cipher/MAC settings for entity-to-entity session traffic.
backupToAuthIds	Auth IDs that can be used for backup/migration-related behavior.
diffieHellman	Optional Diffie-Hellman curve or mode for specific safety-critical examples.

Server-like entities also include:

Property	Meaning
host	Hostname/IP where the entity listens.
port	Entity listening port for secure communication.

Example client:

{
  "group": "Clients",
  "name": "net1.client",
  "distProtocol": "TCP",
  "usePermanentDistKey": false,
  "distKeyValidityPeriod": "1*hour",
  "maxSessionKeysPerRequest": 5,
  "netName": "net1",
  "credentialPrefix": "Net1.Client",
  "distributionCryptoSpec": {
    "cipher": "AES-128-CBC",
    "mac": "SHA256"
  },
  "sessionCryptoSpec": {
    "cipher": "AES-128-CBC",
    "mac": "SHA256"
  },
  "backupToAuthIds": [102]
}

Example server:

{
  "group": "Servers",
  "name": "net1.server",
  "port": 21100,
  "distProtocol": "TCP",
  "usePermanentDistKey": false,
  "distKeyValidityPeriod": "1*hour",
  "maxSessionKeysPerRequest": 1,
  "netName": "net1",
  "credentialPrefix": "Net1.Server",
  "distributionCryptoSpec": {
    "cipher": "AES-128-CBC",
    "mac": "SHA256"
  },
  "sessionCryptoSpec": {
    "cipher": "AES-128-CBC",
    "mac": "SHA256"
  },
  "host": "localhost",
  "backupToAuthIds": [102]
}

filesharingLists

filesharingLists is used by file sharing/IPFS examples. Standard secure socket examples can leave this as an empty array.

When using file sharing examples, this section should match the file owner, reader, uploader, downloader, and File System Manager assumptions used by examples/file_sharing/.

Editing checklist

When adding a new entity:

1. Add an entity object to entityList.
2. Add an entry to assignments.
3. Ensure the entity has a unique name.
4. Ensure server-like entities have host and port.
5. Ensure credentialPrefix and netName match your intended output paths.
6. Regenerate with ./generateAll.sh -g configs/your.graph.

When adding a new Auth:

1. Add it to authList.
2. Add any required authTrusts.
3. Assign entities to the new Auth ID.
4. Ensure ports do not conflict.
5. Regenerate credentials, properties, and databases.