Skip to main content

C API Reference

Overview​

This page documents the public C API declared in the iotauth/sst-c-api repository. After installation the main header is available as:

#include <sst-c-api/c_api.h>   // installed
#include "c_api.h"             // when building inside the repo

The public header and supporting headers are in src/. CMake installs the public c_api.h; lower-level headers remain in the source tree for applications using those helpers.

Supporting headers:

  • c_crypto.h — low-level AES and RSA helpers
  • c_secure_comm.h — handshake and session-level helpers
  • c_common.h — message types, buffer utilities, socket helpers
  • load_config.h — config file parser
  • ipfs.h — IPFS file encryption and sharing helpers

For the C++ classes in cpp/, see the C++ API Reference.

Key types and constants​

ConstantValueMeaning
MAX_SESSION_KEY10Maximum keys in a cached key list.
MAX_ENTITY_NAME_LENGTH32Entity name string length limit.
MAX_PURPOSE_LENGTH64Purpose string length limit.
MAX_PAYLOAD_LENGTH1024Maximum plaintext payload sent in one secure message.
MAX_SECURE_COMM_MSG_LENGTH1091Maximum SST-framed message size in bytes.

AES_encryption_mode_t — Selects AES cipher mode:

ConstantMode
AES_128_CBCAES-128 Cipher Block Chaining
AES_128_CTRAES-128 Counter Mode
AES_128_GCMAES-128 Galois/Counter Mode

hmac_mode_t — Controls HMAC authentication: USE_HMAC enables it, NO_HMAC disables it.

perm_dist_key_mode_t — USE_PERMANENT_DIST_KEY uses a pre-shared symmetric distribution key; NO_PERMANENT_DIST_KEY uses RSA/PKI-based distribution.

Context and initialization​

init_SST​

SST_ctx_t* init_SST(const char* config_path);

Loads the entity config file, entity private key, Auth public key, and distribution key settings. Returns an initialized SST_ctx_t* or NULL on failure.

free_SST_ctx_t​

void free_SST_ctx_t(SST_ctx_t* ctx);

Frees the SST context and its loaded cryptographic keys.

Session key lists​

init_empty_session_key_list​

session_key_list_t* init_empty_session_key_list(void);

Allocates an empty session key list with capacity for MAX_SESSION_KEY entries.

get_session_key​

session_key_list_t* get_session_key(SST_ctx_t* ctx,
                                    session_key_list_t* existing_s_key_list);

Requests session keys from Auth according to entityInfo.number_key and entityInfo.purpose in the config. If existing_s_key_list is non-NULL, new keys are appended to it; otherwise a fresh list is returned. If the existing list cannot accept the requested keys, it is returned unchanged without contacting Auth.

get_session_key_with_index​

session_key_list_t* get_session_key_with_index(
    SST_ctx_t* ctx, int purpose_index,
    session_key_list_t* existing_s_key_list);

Requests keys for the selected configured purpose. The config supports up to two entityInfo.purpose entries; use an index for an existing entry (0 or 1). List allocation and append behavior match get_session_key().

get_session_key_by_ID​

session_key_t* get_session_key_by_ID(unsigned char* target_session_key_id,
                                     SST_ctx_t* ctx,
                                     session_key_list_t* existing_s_key_list);

Looks up a session key by its 8-byte ID in existing_s_key_list. If not found, requests it from Auth. Returns a pointer into the list, or NULL on failure.

free_session_key_list_t​

void free_session_key_list_t(session_key_list_t* session_key_list);

Frees a session key list and its dynamically allocated key storage.

Session key persistence​

save_session_key_list​

int save_session_key_list(session_key_list_t* session_key_list,
                          const char* file_path);

Saves a session key list to a binary file. Returns 0 on success, -1 on failure.

load_session_key_list​

int load_session_key_list(session_key_list_t* session_key_list,
                          const char* file_path);

Loads a previously saved session key list. Returns 0 on success, -1 on failure.

save_session_key_list_with_password​

int save_session_key_list_with_password(session_key_list_t* session_key_list,
                                        const char* file_path,
                                        const char* password,
                                        unsigned int password_len,
                                        const char* salt,
                                        unsigned int salt_len);

Encrypts and saves a session key list using a password-derived key and salt. Returns 0 on success, -1 on failure.

load_session_key_list_with_password​

int load_session_key_list_with_password(session_key_list_t* session_key_list,
                                        const char* file_path,
                                        const char* password,
                                        unsigned int password_len,
                                        const char* salt,
                                        unsigned int salt_len);

Loads and decrypts a password-protected session key list. Returns 0 on success, -1 on failure.

Secure communication setup​

secure_connect_to_server​

SST_session_ctx_t* secure_connect_to_server(session_key_t* s_key,
                                            SST_ctx_t* ctx);

Connects a TCP socket to the server at ctx->config.entity_server_ip_addr/entity_server_port_num and completes the three-way SST session-key handshake. Returns a SST_session_ctx_t* ready for messaging, or NULL on failure.

secure_connect_to_server_with_socket​

SST_session_ctx_t* secure_connect_to_server_with_socket(session_key_t* s_key,
                                                        int sock);

Performs the client-side SST handshake on an already-connected socket. Useful when the application manages its own TCP connection.

server_secure_comm_setup​

SST_session_ctx_t* server_secure_comm_setup(SST_ctx_t* ctx,
                                            int clnt_sock,
                                            session_key_list_t* existing_s_key_list);

Receives and validates the incoming client handshake on clnt_sock. Looks up the session key in existing_s_key_list; if not found, requests it from Auth. Returns a SST_session_ctx_t* or NULL on failure.

free_session_ctx​

void free_session_ctx(SST_session_ctx_t* session_ctx);

Frees the session context only. The application must call close(session_ctx->sock) before freeing it, after any threads using the session have stopped.

Secure messages​

send_secure_message​

int send_secure_message(char* msg, unsigned int msg_length,
                        SST_session_ctx_t* session_ctx);

Encrypts msg, prepends an 8-byte sequence number and type header, and writes the framed message to session_ctx->sock. The plaintext length must not exceed MAX_PAYLOAD_LENGTH (1024). Returns 0 on success or -1 on failure.

read_secure_message​

int read_secure_message(unsigned char* plaintext,
                        SST_session_ctx_t* session_ctx);

Reads a framed SST message from session_ctx->sock, verifies the sequence number and MAC, and decrypts into plaintext (provide a buffer of MAX_SECURE_COMM_MSG_LENGTH bytes). Returns the plaintext length, 0 when the peer closes the connection, or -1 on failure.

receive_thread_read_one_each​

void* receive_thread_read_one_each(void* SST_session_ctx);

Convenience pthread function. Calls read_secure_message and logs decrypted output until the peer closes the connection or a read fails. Intended for use with pthread_create:

pthread_t t;
pthread_create(&t, NULL, receive_thread_read_one_each, (void*)session);
// ...
shutdown(session->sock, SHUT_RDWR);
pthread_join(t, NULL);

Buffer encryption helpers​

encrypt_buf_with_session_key​

int encrypt_buf_with_session_key(session_key_t* s_key,
                                 unsigned char* plaintext,
                                 unsigned int plaintext_length,
                                 unsigned char** encrypted,
                                 unsigned int* encrypted_length);

Encrypts plaintext using the session key's cipher and MAC. Allocates and writes the result into *encrypted; caller must free() it. Returns 0 on success, -1 on failure.

decrypt_buf_with_session_key​

int decrypt_buf_with_session_key(session_key_t* s_key,
                                 unsigned char* encrypted,
                                 unsigned int encrypted_length,
                                 unsigned char** decrypted,
                                 unsigned int* decrypted_length);

Decrypts and verifies encrypted. Allocates and writes the plaintext into *decrypted; caller must free() it. Returns 0 on success, -1 on failure.

encrypt_buf_with_session_key_without_malloc​

int encrypt_buf_with_session_key_without_malloc(session_key_t* s_key,
                                                unsigned char* plaintext,
                                                unsigned int plaintext_length,
                                                unsigned char* encrypted,
                                                unsigned int* encrypted_length);

Encrypts into a caller-provided encrypted buffer. Size it using get_expected_encrypted_total_length() from c_crypto.h; the function does not allocate the output buffer. Returns 0 on success, -1 on failure.

decrypt_buf_with_session_key_without_malloc​

int decrypt_buf_with_session_key_without_malloc(session_key_t* s_key,
                                                unsigned char* encrypted,
                                                unsigned int encrypted_length,
                                                unsigned char* decrypted,
                                                unsigned int* decrypted_length);

Decrypts into a caller-provided decrypted buffer. Size it using get_expected_decrypted_maximum_length() from c_crypto.h; the function does not allocate the output buffer. Returns 0 on success, -1 on failure.

Utility helpers​

convert_skid_buf_to_int​

unsigned int convert_skid_buf_to_int(unsigned char* buf, int byte_length);

Converts a big-endian session-key ID byte buffer to an unsigned integer.

generate_random_nonce​

int generate_random_nonce(int length, unsigned char* buf);

Fills buf with length bytes of cryptographically secure random data using OpenSSL. Returns 0 on success, -1 on failure.

secure_rand​

int secure_rand(int min, int max);

Returns a cryptographically secure random integer in the inclusive range [min, max]. Returns -1 on error.

Logging​

The library provides printf-style formatted logging functions:

SST_print_debug(const char* fmt, ...);   // debug builds only
SST_print_log(const char* fmt, ...);     // always printed
SST_print_error(const char* fmt, ...);   // always printed to stderr
SST_print_error_exit(const char* fmt, ...); // prints to stderr and calls exit(1)

Debug output (SST_print_debug) is compiled out in release builds (no -DDEBUG=1 flag).

FileContents
src/c_api.hPublic API declarations (context, session keys, communication, persistence).
src/c_crypto.hLow-level AES, RSA, HMAC, and key-loading helpers.
src/c_secure_comm.hHandshake implementation and session-key list management.
src/c_common.hMessage type constants, buffer utilities, and socket helpers.
src/load_config.hConfig file parser (load_config).
src/ipfs.hIPFS file encrypt/upload/download/add-reader helpers.
examples/server_client_example/Basic client-server secure communication example.
examples/file_block_encrypt_example/Block-based file encryption example.
examples/ipfs_examples/IPFS file sharing example (C and C++).