Auth Guide

Overview

Auth is the central component of SST. It is a local authentication and authorization service that sits near the entities it serves. Every entity in an SST network must contact Auth before communicating securely with another entity.

Auth is responsible for:

• authenticating registered entities using public-key or pre-shared distribution-key credentials;
• checking communication policy before issuing session keys;
• generating and distributing symmetric session keys to authorized entities;
• maintaining a SQLite database of registered entities, communication policies, trusted Auths, and cached session keys;
• communicating over HTTPS with other trusted Auth instances in multi-Auth deployments;
• optionally supporting backup, migration, delegation, and file-sharing workflows.

The Auth implementation lives under auth/ in the iotauth/iotauth repository.

Module layout

auth/
├── auth-server/            Main Auth server application (IntelliJ/Maven project)
│   └── src/main/
│       ├── java/org/iot/auth/
│       │   ├── AuthServer.java         Entry point and lifecycle
│       │   ├── AuthCommandLine.java    Interactive CLI handler
│       │   └── server/                 Request handlers and connection logic
│       └── resources/logback.xml       Logging configuration
├── library/                Shared library: database, crypto, config, messages
│   └── src/main/java/org/iot/auth/
│       ├── config/         AuthServerProperties and configuration constants
│       ├── crypto/         Cryptographic helpers
│       ├── db/             AuthDB, RegisteredEntity, CommunicationPolicy, TrustedAuth, SessionKeyPurpose
│       ├── exception/      Auth-specific exceptions
│       ├── io/             I/O helpers
│       ├── message/        Message types between Auth and entities
│       └── util/           Utility functions
├── example-auth-db-generator/   Generates example Auth SQLite databases from graph configs
├── migration-solver/       Optimization solver for migration plan generation (requires Gurobi)
├── credentials/            Auth keystores and certificates (generated)
├── databases/              SQLite databases (generated)
└── properties/             Auth runtime properties files (generated)

Prerequisites

• Java 11 or newer (IntelliJ IDEA recommended for development; VSCode with the Java and Maven extensions also works)
• Maven CLI (mvn)

On macOS:

brew install openjdk maven

On Ubuntu:

sudo apt-get install openjdk-17-jdk maven

Build

From auth/auth-server/:

mvn clean install

This produces a self-contained JAR at:

auth/auth-server/target/auth-server-jar-with-dependencies.jar

Alternatively, use the provided Makefile:

cd auth/auth-server
make

Start Auth

Auth requires a generated properties file. Properties and databases are created by the example generator (see Network Configuration):

cd examples
./generateAll.sh

Then start Auth from auth/auth-server/:

java -jar target/auth-server-jar-with-dependencies.jar -p ../properties/exampleAuth101.properties

Auth is ready when the interactive prompt appears:

Enter command (e.g., show re/cp/ta/sk/maps/dp/di, add/remove re/cp/dp...):

Command-line options

Flag	Long form	Required	Purpose
-p	--properties	Yes	Path to the Auth properties file.
-b	--base_path	No	Base directory for resolving relative file paths in the properties file.
-s	--password	No	Auth keystore password (not recommended for production; Auth will prompt interactively if omitted).
-d	--debug	No	Enable debug-level logging.

Running from IntelliJ IDEA

Open the project at $ROOT/auth in IntelliJ. Configure a Run/Debug configuration with:

• Main class: org.iot.auth.AuthServer
• Program arguments: -p ../properties/exampleAuth101.properties
• Working directory: $ROOT/auth/auth-server

Reference screenshots from auth/README.md show the expected configuration for Auth 101 and Auth 102.

Running from VSCode

Add a launch configuration to .vscode/launch.json:

{
  "type": "java",
  "name": "AuthServer",
  "request": "launch",
  "mainClass": "org.iot.auth.AuthServer",
  "args": "-p ../properties/exampleAuth101.properties"
}

CLI reference

Once Auth is running, the interactive prompt accepts the following commands.

Inspect state

Command	Description
show re	Print all registered entities and their configuration.
show cp	Print all communication policies.
show ta	Print all trusted Auth records.
show sk	Print all cached session keys.
show maps	Print internal maps for the UDP listener port.
show dp	Print all delegation privileges.
show di	Print all delegation info records.
help	List all available commands.

Manage session keys

Command	Description
clean sk	Remove expired session keys from the database.
reset sk	Delete all cached session keys.

Manage registered entities

Command	Description
add re	Interactively add a new registered entity to the database.
remove re	Interactively remove a registered entity.
reset re	Delete all entities that were backed up from other Auths.

Manage communication policies

Command	Description
add cp	Interactively add a new communication policy.
remove cp	Interactively remove a communication policy.

Manage delegation privileges

Command	Description
add dp	Interactively add a new delegation privilege record.
remove dp	Interactively remove a delegation privilege record.

Other operations

Command	Description
issue cert or ic	Issue a certificate for an entity.
backup	Back up registered entities to a trusted Auth.
quit	Shut down Auth and exit.

Properties file reference

Generated properties files live under auth/properties/. Each Auth instance has its own properties file.

Identity

Property	Type	Description
auth_id	integer	Unique Auth ID. Must match the id in the .graph file and entity configs.
host_name	string	Hostname or IP address for this Auth instance.

Ports

Property	Type	Description
entity_tcp_port	integer	TCP port that entities use to request session keys.
entity_tcp_port_timeout	long (ms)	TCP connection timeout.
entity_udp_port	integer	UDP port for entity requests when UDP distribution is used.
entity_udp_port_timeout	long (ms)	UDP socket timeout.
trusted_auth_port	integer	HTTPS port for Auth-to-Auth communication.
trusted_auth_port_idle_timeout	long (ms)	Idle timeout for trusted Auth connections.
contextual_callback_port	integer	Port for contextual callback handling.
contextual_callback_port_idle_timeout	long (ms)	Idle timeout for callback connections.
contextual_callback_enabled	boolean	Enable or disable contextual callback support.

Credentials

Property	Type	Description
entity_key_store_path	path	Keystore used for entity-facing TLS/credential operations.
internet_key_store_path	path	Keystore used for Auth-to-Auth HTTPS.
database_key_store_path	path	Keystore used for database protection.
database_encryption_key_path	path	Symmetric key used for database encryption (when protection method requires it).
trusted_ca_cert_paths	paths	Semicolon-separated paths to trusted CA certificates.

Database

Property	Type	Description
auth_database_dir	path	Directory containing the Auth SQLite database.
auth_db_protection_method	integer	Database protection mode (0 = none, 1 = encryption).

Optional features

Property	Type	Default	Description
backup_enabled	boolean	false	Enable backup of registered entities to trusted Auths.
bluetooth_enabled	boolean	false	Enable Bluetooth entity listening.
qps_throttling_enabled	boolean	false	Enable per-entity queries-per-second rate limiting.
qps_limit	float	—	Maximum session key requests per second per entity.
qps_calculation_bucket_size_in_sec	integer	—	Window size in seconds for QPS calculation.
cleanup_cycle_in_ms	long	—	How often Auth removes expired session keys and policies.

Database tables

Auth stores all runtime state in a SQLite database. The database is generated by example-auth-db-generator during the generateAll.sh step.

Table	Contents
RegisteredEntity	One row per registered entity: identity, crypto specs, distribution key material, active status, backup routing, and migration token.
CommunicationPolicy	One row per allowed communication relationship: requesting group, target type and name, session crypto spec, validity periods, expiration, and delegation flag.
TrustedAuth	One row per trusted Auth peer: host, ports, heartbeat settings, and PEM certificates.
CachedSessionKey	Symmetric session keys issued to entities, with ownership list, expiration, purpose, and crypto spec.
DelegationPrivilege	Delegation privilege records: privilege type, privileged group, subject, object, validity, and JSON metadata.
DelegationInfo	Delegation hierarchy: communication-policy-token ID, parent ID, delegation timestamp, and revocation timestamp.
FileSharingInfo	File-sharing access-control: owner entity, reader entity/group, and reader type.
MetaData	Auth-level String→String key/value metadata. Predefined keys: SessionKeyCount, EncryptedDatabaseKey, CommPolicyCount.

RegisteredEntity columns

Column	Type	Description
Name	String	Unique entity identifier, e.g. net1.client.
Group	String	Logical group such as Clients, Servers, PtPublishers, or PtSubscribers.
DistProtocol	String	Protocol Auth uses for the distribution channel: TCP or UDP.
UsePermanentDistKey	boolean	If true, Auth uses a pre-shared symmetric distribution key instead of public-key credentials.
DistKeyValidityPeriod	long	How long a freshly issued distribution key remains valid (ms).
PublicKeyValue	String	PEM-encoded entity public key (used when UsePermanentDistKey is false).
PublicKeyFile	String	Path to the entity's public key file (alternative to inline PublicKeyValue).
PublicKeyCryptoSpec	String	Public-key algorithm spec for the distribution channel setup handshake.
DistCryptoSpec	String	Symmetric cipher and MAC for the Auth-entity distribution channel.
DistKeyExpirationTime	long	Absolute expiration timestamp of the current distribution key (Unix ms).
DistKeyValue	byte[]	Current symmetric distribution key value (stored encrypted).
MaxSessionKeysPerRequest	int	Maximum session keys Auth will issue in a single request from this entity.
Active	boolean	Whether the entity registration is active.
BackupToAuthIDs	String	Comma-separated Auth IDs to which this entity record may be backed up.
BackupFromAuthID	int	Auth ID that originally owned this record (set when imported via backup).
MigrationToken	String	Token exchanged during entity migration workflows.

CommunicationPolicy columns

Column	Type	Description
ID	long	Auto-assigned policy identifier.
RequestingGroup	String	Entity group that may invoke this policy (e.g. Clients).
TargetType	String	Policy type: Group, PubTopic, SubTopic, or Delegation.
Target	String	Target group name, topic name, or entity name, depending on TargetType.
MaxNumSessionKeyOwners	int	Maximum entities that may simultaneously hold the same session key.
SessionCryptoSpec	String	Cipher and MAC for session keys issued under this policy.
AbsoluteValidity	long	Absolute validity duration for issued session keys (ms).
RelativeValidity	long	Relative validity from first use (ms).
Expiration	long	Timestamp after which this policy itself expires (Unix ms).
IsDelegated	int	Whether this policy was established via a delegation grant (0 = false, 1 = true).

TrustedAuth columns

Column	Type	Description
ID	int	Trusted Auth's integer identifier.
Host	String	Hostname for internet-facing Auth-to-Auth HTTPS.
EntityHost	String	Hostname that entities use to reach this Auth.
Port	int	Port for Auth-to-Auth communication.
HeartbeatPeriod	int	Interval (ms) for heartbeat messages sent to this peer.
FailureThreshold	int	Missed heartbeats before the peer is considered unavailable.
InternetCertificateValue	String	PEM certificate for internet-facing connections (inline).
EntityCertificateValue	String	PEM certificate for entity-facing connections (inline).
BackupCertificateValue	String	PEM certificate used in backup workflows (inline).
InternetCertificatePath	String	File path alternative to inline InternetCertificateValue.
EntityCertificatePath	String	File path alternative to inline EntityCertificateValue.

CachedSessionKey columns

Column	Type	Description
ID	long	Unique session key identifier issued by Auth.
Owners	String	Serialized list of entity names currently holding this key.
MaxNumOwners	int	Maximum number of concurrent owners allowed.
Purpose	String	Encoded purpose (requesting group and target group).
ExpirationTime	long	Absolute expiration timestamp (Unix ms).
RelValidity	long	Relative validity duration from first use (ms).
CryptoSpec	String	Cipher and MAC spec, e.g. AES-128-CBC:SHA256.
KeyVal	byte[]	Encrypted key material.
ExpectedOwnerGroups	String	Groups from which the key's owners are expected to come.

DelegationPrivilege columns

Column	Type	Description
PrivilegeType	String	Privilege category, e.g. DELEGATE or READ.
PrivilegedGroup	String	Entity group granted this privilege.
Subject	String	The granting entity or scope subject.
Object	String	The resource or target group this privilege applies to.
Validity	String	Duration or expiration for this privilege.
Info	JSONObject	JSON object with additional privilege metadata.

DelegationInfo columns

Column	Type	Description
CPTId	long	Communication-policy-token ID this delegation is associated with.
Parent	long	Parent delegation record ID (forms a delegation chain).
DelegatedTime	long	Unix timestamp (ms) when this delegation was granted.
RevokedTime	long	Unix timestamp (ms) when this delegation was revoked (0 if still active).

FileSharingInfo columns

Column	Type	Description
Owner	String	Entity that owns the file.
Reader	String	Entity name or group name authorized to read the file.
ReaderType	String	entity or group, indicating how Reader should be interpreted.

Registered entities

Each entity in the RegisteredEntity table has the attributes described in the database tables section above. Key concepts:

• Name / Group: Name uniquely identifies the entity; Group determines which communication policies apply.
• Distribution key: Auth and the entity share a symmetric distribution key used to encrypt session key responses. When UsePermanentDistKey is true, this key is fixed; otherwise Auth issues a fresh key each session.
• Public-key credentials: When UsePermanentDistKey is false, the entity authenticates with its RSA private key and Auth uses PublicKeyValue (or PublicKeyFile) to verify the signature.
• Backup / migration: BackupToAuthIDs controls which Auths receive copies of this record. BackupFromAuthID marks records imported from a peer, and MigrationToken is exchanged during live migration handoffs.

Communication policies

A communication policy in the CommunicationPolicy table grants a group of entities permission to obtain session keys for a specific target. Auth checks policy before issuing any session key. See the database tables section for the full column list.

Policy target types

TargetType	Meaning
Group	RequestingGroup may communicate with all entities in the Target group. Standard client/server use case.
PubTopic	RequestingGroup may publish to the Target topic.
SubTopic	RequestingGroup may subscribe to the Target topic.
Delegation	Access established via a delegation grant, verified against DelegationInfo records.

Session key request flow

This is the core interaction between an entity and Auth:

1. Entity connects to Auth's TCP (or UDP) port.
2. Entity sends a session key request authenticated with its distribution key or private key.
3. Auth validates the entity's nonce and signature/MAC.
4. Auth looks up the entity in RegisteredEntity and retrieves or refreshes its distribution key.
5. Auth evaluates the matching CommunicationPolicy for the requested target group or key ID.
6. If policy permits and the owner count limit is not exceeded, Auth generates or retrieves session keys from CachedSessionKey.
7. If the target entity belongs to a different (trusted) Auth, Auth forwards a request to that peer over HTTPS.
8. Auth encrypts the session keys with the entity's distribution key and sends the response.
9. Both the client and the server can now use the shared session key to establish an encrypted channel directly, without further Auth involvement.

Multi-Auth deployments

SST supports multiple Auth instances connected by trust relationships. Each Auth maintains a TrustedAuth table. See the database tables section for the full column list.

Auth instances exchange heartbeat messages to monitor peer availability. When an entity belonging to a remote Auth requests a session key for communicating with a local entity, Auth forwards the request to the remote Auth over HTTPS and relays the result.

Trust relationships are defined in the .graph file under authTrusts and are populated into the TrustedAuth table during database generation.

Backup and migration

When backup_enabled is set in the properties file, Auth periodically sends copies of its registered entity records to trusted Auth peers listed in each entity's BackupToAuthIDs field. This allows a backup Auth to serve entities whose primary Auth has failed.

The migration-solver module provides an optimization tool, built on the Gurobi optimizer, for computing optimal migration plans across a multi-Auth topology. It reads scenario JSON files and produces migration assignments that maximize availability. Gurobi requires a separate academic or commercial license; the gurobi.jar file must be obtained independently.

Testing

The Auth library has a unit test suite in auth/library/src/test/java/org/iot/auth/AppTest.java (865 lines, 17 test methods). The tests exercise every database table, the message-type constants, and the crypto helpers.

Running the tests

From auth/library/:

mvn test

Or from the repository root:

cd auth
mvn test

Maven compiles, then runs the JUnit suite. The tests create and destroy a temporary encrypted SQLite database in auth/library/src/test/test_files/databases/ and leave no persistent state.

Test file layout

auth/library/src/test/
├── java/org/iot/auth/AppTest.java       JUnit test class
└── test_files/
    ├── databases/                        Temporary test databases (created/deleted by tests)
    ├── entity_certs/                     PEM certificates for test entities
    ├── trusted_auth_certs/               PEM certificates for the trusted Auth under test (Auth 102)
    └── properties/                       Auth properties files used by tests

Test methods

All tests use ENCRYPT_CREDENTIALS as the database protection method, which exercises the full encrypted-SQLite code path.

Test method	What it covers
testConstant()	Validates C.AUTH_NONCE_SIZE equals 8.
testMessageType()	Verifies byte values and round-trip conversion for 39+ message-type enum entries.
testAuthHello()	Constructs an AuthHello message and checks its serialized form.
testRegEntityInsertionAndSelectAll()	Inserts 4 entities (Clients, PtClients, Servers, PtServers) and reads all back.
testCommPolicyInsertionAndSelectAll()	Inserts 8 policies covering Group, PubTopic, and SubTopic target types and reads all back.
testTrustedAuthInsertionAndSelectAll()	Inserts trusted Auth 102 with PEM certificates and reads it back.
testFileSharingTable()	Tests entity-level and group-level reader entries in file_sharing_info.
testCachedSessionKeyInsertionAndSelectAll()	Inserts 2 session keys (AES-128-CBC:SHA256) and reads all back.
testCachedSessionKeySelectById()	Retrieves a specific cached session key by its ID (42).
testCachedSessionKeySelectByPurpose()	Filters cached session keys by encoded purpose string.
testCachedSessionKeyAppendOwner()	Appends a new owner to a cached session key and verifies the owner list.
testCachedSessionKeyDeleteAll()	Deletes all cached session keys and verifies the table is empty.
testFileSharingInsertionAndSelectByOwner()	Retrieves file-sharing records filtered by owner entity name.
testDelegationPrivilegeInsertionAndSelectAll()	Inserts DELEGATE and READ privilege records; filters by privileged group.
testDelegationInfoInsertionAndGetChildren()	Inserts a 3-level delegation chain (IDs 100→101→102) and retrieves children by parent ID.
testMetaDataInsertionAndUpdate()	Inserts SessionKeyCount = "0", updates it to "5", and reads the updated value.

Setup and teardown are handled by createTestAuthDB() and destroyTestAuthDB(), which are called before and after the database-dependent tests.