Entity Capabilities

Overview

This page compares SST capabilities across the entity APIs so you can choose the right implementation path and translate concepts between C, C++, Node.js, and Python.

SST exposes the same core ideas through different entity APIs, but the language support and design paradigms vary across platforms. Use this map to choose the right API surface and to translate concepts between C, C++, Node.js, and Python.

Main secure communication capabilities

Responsibility	C API	C++ API	Node.js API	Python API
Load entity config	init_SST()	SST_API(config_path)	new SecureCommClient(config), new SecureCommServer(config)	IoTAuthContext.from_config(config)
Initialize runtime state	init_SST()	SST_API(config_path)	initialize()	IoTAuthContext.from_config()
Request session keys	get_session_key()	SST_API::get_session_key()	getSessionKeysForCaching(n) or implicit via provideInput('serverHostPort', ...)	ctx.request_session_keys()
Client secure handshake	secure_connect_to_server()	SST_API::secure_connect_to_server()	provideInput('serverHostPort', {host, port})	SecureClient.connect()
Server secure handshake	server_secure_comm_setup()	SST_API::server_secure_comm_setup()	initialize() plus setOutputHandler('received', ...)	SecureServer.serve_once()
Send encrypted data	send_secure_message()	SST_Session::send_secure_message()	provideInput('toSend', Buffer)	channel.send(payload)
Receive decrypted data	read_secure_message()	SST_Session::read_secure_message()	setOutputHandler('received', handler)	channel.recv()
Threaded receive loop	receive_thread_read_one_each() with pthread_create	SST_Session::receive_loop() in an application-owned thread	Not needed — Node.js is event-driven	Synchronous channel.recv(); application-managed threads if needed
Encrypt/decrypt buffers without socket	encrypt_buf_with_session_key(), _without_malloc variants	SST_API::encrypt/decrypt_buf_with_session_key()	No direct equivalent	symmetric_encrypt_authenticate() / symmetric_decrypt_authenticate() in iotauth.crypto
Cache session keys	session_key_list_t + get_session_key()	SessionKeyList	getSessionKeysForCaching() / getSessionKeysForFutureClients()	Internal SessionKeyCache inside IoTAuthContext
Persist session keys to disk	save_session_key_list(), _with_password variants	No public save/load API	Not documented	Not documented / runtime-oriented
Free runtime resources	close() socket, then free_session_ctx(), free_session_key_list_t(), free_SST_ctx_t()	RAII; shut down sessions and join receiver threads before destruction	JavaScript garbage collection; close connections via provideInput	Context managers (with SecureClient(ctx):, channel.close())

Repository example configuration tooling

Responsibility	Source
Define example Auths and entities	.graph file
Generate example credentials	examples/credentialGenerator.js via generateAll.sh
Generate example Auth properties	examples/authConfigGenerator.js via generateAll.sh
Generate example Auth databases	examples/authDBGenerator.js via generateAll.sh
Generate Node.js example configs	examples/entityConfigGenerator.js via generateAll.sh
Provide Python example configs	No dedicated generator. Use the checked-in Python properties fixtures, adapt a C properties fixture, or use a generated Node JSON config.
Provide C/C++ example configs	Checked-in properties fixtures under the C example directories; C++ examples reuse them.

Advanced capability support

Capability	C	C++	Node.js	Python
Direct secure client/server communication	Yes	Yes (SST_API, SST_Session)	Yes	Yes (SecureClient, SecureServer)
Publisher/subscriber accessors	Not a primary path	No direct equivalent	Yes (SecurePublisher, SecureSubscriber)	No direct equivalent
Delegation and privilege operations	Not a primary path	No direct equivalent	Yes (performPrivilege, getSessionKeyIdForGrantAccess)	Not currently documented
Migration to backup Auth	Not a primary path	No direct equivalent	Yes (migrateToTrustedAuth, migrationEnabled parameter)	Not currently documented
Per-resource session key requests	Not a primary path	No dedicated accessor	Yes (provideInputResource)	Not currently documented
Block-based file encryption	Yes (examples/file_block_encrypt_example/)	Yes (cpp/examples/file_block_encrypt_example/)	No direct equivalent	No direct equivalent
IPFS file encryption/upload/download	Yes (src/ipfs.h, examples/ipfs_examples/)	Yes (sst::ipfs, cpp/examples/ipfs_examples/)	No direct equivalent	Secure File System Manager in examples/file_sharing/; no IPFS client helpers in the package
Session key persistence to disk	Yes (save_session_key_list, load_session_key_list)	No public save/load API	Not documented	Not documented
Password-protected key storage	Yes (save/load_session_key_list_with_password)	No public save/load API	Not documented	Not documented

Practical guidance

• Use C when building embedded or native entities, when you need explicit socket and memory control, or when you need file and IPFS encryption capabilities. Source: sst-c-api.
• Use C++ for native C++17 entities with automatic resource cleanup, session classes, and IPFS helpers. See the C++ Guide.
• Use Node.js when building gateways, scripts, demonstrations, or services where event callbacks are natural; or when you need publish/subscribe, delegation, or automatic Auth migration. Source: entity/node/ in iotauth/iotauth.
• Use Python when building servers, clients, scripts, or services using modern object-oriented Python wrappers (SecureClient, SecureServer, and IoTAuthContext), or for File System Manager workflows. Source: entity/python/ in iotauth/iotauth.
• For the repository examples, use the .graph file and generateAll.sh to generate credentials, Auth configuration, Auth databases, and Node entity configs.
• For the repository Python examples, choose a checked-in or adapted properties config or a generated Node JSON config, then verify its credential paths.