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, 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, Node.js, and Python.

Main secure communication capabilities

Responsibility	C API	Node.js API	Python API
Load entity config	init_SST()	new SecureCommClient(config), new SecureCommServer(config)	IoTAuthContext.from_config(config)
Initialize runtime state	init_SST()	initialize()	IoTAuthContext.from_config()
Request session keys	get_session_key()	getSessionKeysForCaching(n) or implicit via provideInput('serverHostPort', ...)	ctx.request_session_keys()
Client secure handshake	secure_connect_to_server()	provideInput('serverHostPort', {host, port})	SecureClient.connect()
Server secure handshake	server_secure_comm_setup()	initialize() plus setOutputHandler('received', ...)	SecureServer.serve_once()
Send encrypted data	send_secure_message()	provideInput('toSend', Buffer)	channel.send(payload)
Receive decrypted data	read_secure_message()	setOutputHandler('received', handler)	channel.recv()
Threaded receive loop	receive_thread_read_one_each() with pthread_create	Not needed — Node.js is event-driven	Not needed — standard Python threads or async loops
Encrypt/decrypt buffers without socket	encrypt_buf_with_session_key(), _without_malloc variants	No direct equivalent	Crypto.encrypt_payload() / Crypto.decrypt_payload()
Cache session keys	session_key_list_t + get_session_key()	getSessionKeysForCaching() / getSessionKeysForFutureClients()	Internal SessionKeyCache inside IoTAuthContext
Persist session keys to disk	save_session_key_list(), _with_password variants	Not documented	Not documented / runtime-oriented
Free runtime resources	free_session_ctx(), free_session_key_list_t(), free_SST_ctx_t()	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 example configs	Checked-in properties fixtures under the C example directories.

Advanced capability support

Capability	C	Node.js	Python
Direct secure client/server communication	Yes	Yes	Yes (SecureClient, SecureServer)
Publisher/subscriber accessors	Not a primary path	Yes (SecurePublisher, SecureSubscriber)	No direct equivalent
Delegation and privilege operations	Not a primary path	Yes (performPrivilege, getSessionKeyIdForGrantAccess)	Not currently documented
Migration to backup Auth	Not a primary path	Yes (migrateToTrustedAuth, migrationEnabled parameter)	Not currently documented
Per-resource session key requests	Not a primary path	Yes (provideInputResource)	Not currently documented
Block-based file encryption	Yes (examples/file_block_encrypt_example/)	No direct equivalent	No direct equivalent
IPFS file encryption/upload/download	Yes (include/ipfs.h, examples/ipfs_examples/)	No direct equivalent	File System Manager / File Sharing examples
Session key persistence to disk	Yes (save_session_key_list, load_session_key_list)	Not documented	Not documented
Password-protected key storage	Yes (save/load_session_key_list_with_password)	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 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.