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 and Node.js.
SST exposes the same core ideas through different entity APIs, but the language support is not identical. Use this map to choose the right API surface and to translate concepts between C and Node.js.
Main secure communication capabilities
| Responsibility | C API | Node.js API |
|---|---|---|
| Load generated config | init_SST() | new SecureCommClient(config), new SecureCommServer(config) |
| Initialize runtime state | init_SST() | initialize() |
| Request session keys | get_session_key() | getSessionKeysForCaching(n) or implicit via provideInput('serverHostPort', ...) |
| Client secure handshake | secure_connect_to_server() | provideInput('serverHostPort', {host, port}) |
| Server secure handshake | server_secure_comm_setup() | initialize() plus setOutputHandler('received', ...) |
| Send encrypted data | send_secure_message() | provideInput('toSend', Buffer) |
| Receive decrypted data | read_secure_message() | setOutputHandler('received', handler) |
| Threaded receive loop | receive_thread_read_one_each() with pthread_create | Not needed — Node.js is event-driven |
| Encrypt/decrypt buffers without socket | encrypt_buf_with_session_key(), _without_malloc variants | No direct equivalent |
| Cache session keys | session_key_list_t + get_session_key() | getSessionKeysForCaching() / getSessionKeysForFutureClients() |
| Persist session keys to disk | save_session_key_list(), _with_password variants | Not documented |
| Free runtime resources | free_session_ctx(), free_session_key_list_t(), free_SST_ctx_t() | JavaScript garbage collection; close connections via provideInput |
Configuration capabilities
| Responsibility | Source |
|---|---|
| Define Auths and entities | .graph file |
| Generate credentials | examples/credentialGenerator.js via generateAll.sh |
| Generate Auth properties | examples/authConfigGenerator.js via generateAll.sh |
| Generate Auth databases | examples/authDBGenerator.js via generateAll.sh |
| Generate Node.js configs | examples/entityConfigGenerator.js via generateAll.sh |
| Generate C example configs | generateAll.sh and C example fixtures |
Advanced capability support
| Capability | C | Node.js |
|---|---|---|
| Direct secure client/server communication | Yes | Yes |
| Publisher/subscriber accessors | Not a primary path | Yes (SecurePublisher, SecureSubscriber) |
| Delegation and privilege operations | Not a primary path | Yes (performPrivilege, getSessionKeyIdForGrantAccess) |
| Migration to backup Auth | Not a primary path | Yes (migrateToTrustedAuth, migrationEnabled parameter) |
| Per-resource session key requests | Not a primary path | Yes (provideInputResource) |
| Block-based file encryption | Yes (examples/file_block_encrypt_example/) | No direct equivalent |
| IPFS file encryption/upload/download | Yes (include/ipfs.h, examples/ipfs_examples/) | No direct equivalent |
| Session key persistence to disk | Yes (save_session_key_list, load_session_key_list) | Not documented |
| Password-protected key storage | Yes (save/load_session_key_list_with_password) | 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 the
.graphfile andgenerateAll.shto generate all credentials, configs, and databases rather than hand-writing them.