File Block Encryption

Overview

This page describes the file block encryption example, which shows how to use SST session keys to encrypt and decrypt large data sets in fixed-size blocks — without a network connection between entities.

Source: examples/file_block_encrypt_example/ in iotauth/sst-c-api.

What this demonstrates

• A writer requests multiple session keys from Auth, generates random key-value pairs, packs them into 32 KB blocks, encrypts each block with a distinct session key, and writes the encrypted blocks to files.
• A reader loads the writer's metadata, requests the exact session keys needed (by ID) from Auth, reads the encrypted files, decrypts each block, and verifies the result against the original plaintext.

This pattern is applicable to any scenario where data must be encrypted at write time and decrypted later — databases, log archives, sensor recordings, and similar offline use cases.

Key constants

Constant	Value	Meaning
MAX_PLAINTEXT_BLOCK_SIZE	32768 (32 KB)	Maximum bytes per encrypted block.
TOTAL_BLOCK_NUM	10	Number of blocks written per run.
TOTAL_FILE_NUM	3	Number of output files.
MIN_KEY_VALUE_SIZE	56	Minimum size of a single key-value entry.
MAX_KEY_VALUE_SIZE	144	Maximum size of a single key-value entry.

Prerequisites

• Auth is running (see Quick Start).
• The sst-c-api library is built (see C Guide).

Build

cd sst-c-api/examples/file_block_encrypt_example
mkdir -p build && cd build
cmake ../
make

This produces:

• block_writer — encrypts and writes blocks
• block_reader — decrypts and verifies blocks
• block_reader_load_s_key_list — reader variant that loads keys from a previously saved key list file

Run

1. Start Auth

cd auth/auth-server    # inside iotauth/iotauth
java -jar target/auth-server-jar-with-dependencies.jar -p ../properties/exampleAuth101.properties

2. Run the writer

cd sst-c-api/examples/file_block_encrypt_example/build
./block_writer ../block_writer.config

The writer:

1. Requests N session keys from Auth (controlled by numkey in the config).
2. Generates random key-value pairs and packs them into 32 KB blocks.
3. Zero-pads the final block to the full block size.
4. Encrypts each block with a unique session key.
5. Writes encrypted blocks to files and plaintext blocks for later comparison.
6. Saves block metadata (key IDs, file positions, block lengths) to binary metadata files.

3. Run the reader

cd sst-c-api/examples/file_block_encrypt_example/build
./block_reader ../block_reader.config

The reader:

1. Loads block metadata saved by the writer.
2. For each block, requests the corresponding session key by ID from Auth.
3. Reads and decrypts the encrypted block.
4. Compares the decrypted output against the saved plaintext to verify correctness.

To test key persistence, run the reader variant that loads keys from disk:

./block_reader_load_s_key_list

This reloads session keys that were saved to disk by the writer instead of re-requesting them from Auth.

Implementation walkthrough

Writer flow

// Request N session keys
SST_ctx_t* ctx = init_SST(config_path);
session_key_list_t* keys = get_session_key(ctx, NULL);

// Save key list for the reader to load later (optional)
save_session_key_list(keys, "saved_keys.bin");

// For each block i:
//   - Fill a 32 KB buffer with random key-value pairs
//   - Encrypt with keys->s_key[i]
//   - Write encrypted block to file
encrypt_buf_with_session_key(&keys->s_key[i], plaintext, block_len,
                             &encrypted, &enc_len);
fwrite(encrypted, 1, enc_len, out_file);
free(encrypted);

// Save metadata: key ID, file offset, block length

Reader flow

// Load metadata from writer
// For each block: look up the session key by its ID from Auth
session_key_t* key = get_session_key_by_ID(key_id, ctx, key_list);

// Decrypt the block
decrypt_buf_with_session_key(key, ciphertext, enc_len,
                             &plaintext, &plain_len);

// Compare with saved plaintext to verify

Key persistence variant

The writer saves its session key list with:

save_session_key_list(keys, "saved_keys.bin");

The block_reader_load_s_key_list variant uses:

session_key_list_t* loaded = init_empty_session_key_list();
load_session_key_list(loaded, "saved_keys.bin");

This avoids contacting Auth again and is useful for offline decryption scenarios. Password-protected persistence is available via save_session_key_list_with_password / load_session_key_list_with_password.

Config files

File	Purpose
block_writer.config	Writer entity config: Auth coordinates, entity credentials, number of keys.
block_reader.config	Reader entity config: Auth coordinates, entity credentials.

Next steps

• See C API Reference for full function documentation including encrypt_buf_with_session_key and save_session_key_list.
• See Server/Client Example for a socket-based secure communication example.
• See IPFS File Sharing for file encryption combined with IPFS storage and Auth-managed key distribution.