Skip to main content

C++ API Reference

Overview​

The public session API is declared in cpp/src/api.hpp. Its types live in namespace sst. Use the C++ Guide for builds, configuration, and runnable examples.

C conceptC++ equivalent
SST_ctx_t, init_SST(), free_SST_ctx_t()SST_API; credentials are released automatically.
session_key_list_tSessionKeyList; fixed storage for ten keys.
SST_session_ctx_t, free_session_ctx()SST_Session; destruction also closes its socket.
Client/server handshake functionsSST_API methods returning std::unique_ptr<SST_Session>.
receive_thread_read_one_each()SST_Session::receive_loop().
Buffer encryption without mallocStatic SST_API methods with caller-provided buffers.
ipfs.hcpp/src/ipfs.hpp, namespace sst::ipfs.

The C++ API shares the C wire protocol and properties config format. It does not currently expose equivalents of the C session-key save/load functions.

SST_API​

Construction​

explicit SST_API(const std::string& config_path);

Loads the entity config, private key, and Auth public key, or permanent distribution keys when enabled. Relative credential paths are resolved from the process working directory. Construction, key requests, and handshakes throw SST_Exception on failure. The context is neither copyable nor movable.

Request session keys​

SessionKeyList get_session_key();
void get_session_key(SessionKeyList& existing_s_key_list);
SessionKeyList get_session_key_with_index(int purpose_index);
void get_session_key_with_index(int purpose_index,
                                SessionKeyList& existing_s_key_list);
session_key_t* get_session_key_by_ID(
    const unsigned char* target_session_key_id,
    SessionKeyList& existing_s_key_list);

The no-list overload returns a new list. The list overload appends received keys, or skips the request with a warning if the list cannot accommodate them. The indexed overloads select one of up to two configured purposes (0 or 1). Key lookup accepts an eight-byte ID, checks the supplied list, and requests the key from Auth if needed. The returned pointer refers to storage inside the list; later changes to the list can replace that key.

Auth communication through one SST_API instance is serialized by an internal mutex. Applications must still coordinate their own direct access to shared key lists.

Establish a secure session​

std::unique_ptr<SST_Session> secure_connect_to_server(session_key_t& s_key);
static std::unique_ptr<SST_Session> secure_connect_to_server_with_socket(
    session_key_t& s_key, int sock);
std::unique_ptr<SST_Session> server_secure_comm_setup(
    int clnt_sock, SessionKeyList& existing_s_key_list);

The client method connects to the configured entity server and completes the handshake. The socket overload uses an already-connected descriptor. The server method takes an accepted client descriptor and looks up the client's session key in the supplied cache or requests it from Auth.

The returned session owns the socket. The handshake methods close the descriptor on failure, including caller-supplied descriptors. Do not also close an owned descriptor from application code.

Add a file reader​

void send_add_reader_req_via_TCP(const std::string& add_reader);

Sends a serialized request such as {"AddReader":"net1.Bob"} to Auth. The argument is the request text, not a filename. File-based reader lists are handled by the IPFS examples.

Encrypt or decrypt a buffer​

static int encrypt_buf_with_session_key(
    const session_key_t& s_key, const unsigned char* plaintext,
    unsigned int plaintext_length, unsigned char* encrypted,
    unsigned int* encrypted_length);
static int decrypt_buf_with_session_key(
    const session_key_t& s_key, const unsigned char* encrypted,
    unsigned int encrypted_length, unsigned char* decrypted,
    unsigned int* decrypted_length);

Both return 0 on success and -1 on an expired key or crypto failure. The caller supplies the output buffer. Size it with Crypto::get_expected_encrypted_total_length() or Crypto::get_expected_decrypted_maximum_length(), using the key's cipher and HMAC parameters. Output-length pointers receive the actual length; they do not communicate buffer capacity.

SessionKeyList​

SessionKeyList();
int size() const;
bool empty() const;
int find(uint64_t key_id) const;
int add(const session_key_t& key);
void append(const SessionKeyList& src);
bool addable(int requested_num_key);

s_key is a public std::array<session_key_t, MAX_SESSION_KEY> with ten slots. num_key tracks the count and rear_idx the next write position. find() returns an index or -1. add() returns the written index and overwrites the oldest key when full. addable() checks capacity and can drop expired oldest entries to make room.

SST_Session​

Send and receive​

int send_secure_message(const unsigned char* msg, unsigned int msg_length);
int send_secure_message(const std::string& msg);
int read_secure_message(unsigned char* plaintext,
                        unsigned int plaintext_capacity);
  • Send at most MAX_PAYLOAD_LENGTH (1024) plaintext bytes per message. A successful send returns the number of framed bytes written; failure returns -1. The C API's send function instead returns 0 on success.
  • Receive into a caller-provided buffer; MAX_SECURE_COMM_MSG_LENGTH (1091) bytes always suffice. Pass its capacity as the second argument. The result is the plaintext length, 0 on peer closure, or -1 on failure.
  • Sending and receiving have separate mutexes, allowing one thread to send while another receives.

Shutdown and inspection​

void receive_loop();
void shutdown();
int get_sock() const;
const session_key_t& get_session_key() const;
unsigned int get_sent_seq_num() const;
unsigned int get_received_seq_num() const;

receive_loop() reads and logs messages until closure or error. shutdown() shuts down both socket directions to release a blocked receiver. Join receiver threads before destroying the session. The destructor closes the socket; sessions are neither copyable nor movable and are normally managed through std::unique_ptr.

Supporting modules​

HeaderPurpose
crypto.hppStatic sst::Crypto RSA, AES-CBC/CTR/GCM, SHA-256, and HMAC helpers; sst::SignedData.
net/sockets.hppPOSIX socket wrappers: Socket, ClientSocket, ServerSocket, EndPointSocket.
ipfs.hppsst::ipfs file encryption, IPFS, and File System Manager helpers.
log/log_manager.hppspdlog-based LogManager and LOG_INF, LOG_ERR, and related macros.

Crypto operations use caller-provided output buffers and fixed-size internal byte buffers. OpenSSL still allocates its key and operation contexts internally; the entire library is not allocation-free. Raw EVP_PKEY* objects returned by crypto key loaders must be released with EVP_PKEY_free().