IPFS File Sharing

Overview

This page describes the SST IPFS file sharing example, which combines Auth-managed access control with encrypted files stored in IPFS. File content is never stored in Auth — Auth manages only the session keying material used to encrypt and decrypt the file.

Publication: Yeongbin Jo, Yunsang Cho, and Hokeun Kim, "Secure and Lightweight Access Control for Highly Decentralized and Distributed File Systems," in Proc. 1st International Workshop on Middleware for the Computing Continuum (Mid4CC '23), ACM, Bologna, Italy, December 11, 2023. DOI: 10.1145/3631309.3632832

Relevant sources:

• C IPFS helpers: include/ipfs.h in iotauth/sst-c-api
• C IPFS example: examples/ipfs_examples/ in iotauth/sst-c-api
• File sharing graph and scripts: examples/file_sharing/ in iotauth/iotauth

Architecture

The system consists of four services:

Service	Role
Auth	Issues and manages session keys; handles add-reader requests.
IPFS daemon	Stores and serves encrypted file content by content identifier (CID).
File System Manager	Stores file metadata (CID, session key ID, purpose); acts as an index between uploader and downloader.
Uploader / Downloader	C entities that encrypt, upload, download, and decrypt files.

High-level flow

1. The uploader encrypts a local file with an SST session key obtained from Auth.
2. The encrypted file is added to IPFS via the local CLI (ipfs add); IPFS returns a content identifier (CID).
3. The uploader registers the CID and session key ID with the File System Manager.
4. The uploader sends an add-reader request to Auth, authorizing specific readers to obtain the session key.
5. A downloader queries the File System Manager for the CID and session key ID.
6. The downloader requests the session key from Auth (Auth verifies the reader has been authorized).
7. The downloader fetches the encrypted file from IPFS and decrypts it.

File System Manager role

The File System Manager bridges the IPFS content layer and the SST key layer. It stores:

• the IPFS CID of the encrypted file;
• the session key ID used to encrypt it;
• the purpose string so downloaders can request the right key.

A secure variant of the File System Manager protects its own metadata with SST session keys:

Prerequisites

• Auth is running with the file sharing policy.
• IPFS CLI is installed and the IPFS daemon is running.
• The File System Manager is running.
• The sst-c-api library is built (see C Guide).

Install IPFS:

# macOS
brew install ipfs

# Ubuntu
snap install ipfs

Initialize and start the IPFS daemon:

ipfs init
ipfs daemon

Generate file sharing configs

cd examples    # inside iotauth/iotauth
./cleanAll.sh
./generateAll.sh -g configs/file_sharing.graph

This creates Auth databases, credentials, and entity configs for the file sharing topology.

Build the example

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

This produces entity_uploader and entity_downloader (and secure variants).

Start the File System Manager

cd examples/file_sharing    # inside iotauth/iotauth
python3 file_system_manager.py

Run the uploader

cd sst-c-api/examples/ipfs_examples/build
./entity_uploader ../uploader.config plain_text addReader.txt

Arguments:

1. Config file path.
2. Path to the plaintext file to encrypt and upload.
3. Path to a file listing the readers to authorize (one entity name per line).

The uploader:

1. Requests a session key from Auth for the file sharing purpose.
2. Calls file_encrypt_upload() to encrypt the file and ipfs add it.
3. Calls upload_to_file_system_manager() to register the CID and key ID.
4. Calls send_add_reader_req_via_TCP() to authorize the readers listed in addReader.txt.

Then prints: "Waiting for client..." until the downloader connects.

Run the downloader

In a separate terminal, after the uploader is waiting:

cd sst-c-api/examples/ipfs_examples/build
./entity_downloader ../downloader.config

The downloader:

1. Calls receive_data_and_download_file() to fetch the CID and key ID from the File System Manager.
2. Requests the session key from Auth (requires having been authorized by the uploader).
3. Downloads the encrypted file from IPFS.
4. Calls file_decrypt_save() to decrypt and save the file locally.

C IPFS API reference

file_encrypt_upload

int file_encrypt_upload(session_key_t* s_key,
                        SST_ctx_t* ctx,
                        char* my_file_path,
                        unsigned char* hash_value,
                        estimate_time_t* estimate_time);

Encrypts the file at my_file_path using s_key, runs ipfs add on the result, and writes the IPFS CID into hash_value. Returns 0 on success, -1 on failure.

upload_to_file_system_manager

int upload_to_file_system_manager(session_key_t* s_key,
                                  SST_ctx_t* ctx,
                                  unsigned char* hash_value,
                                  int hash_value_len);

Sends the CID and session key ID to the File System Manager over TCP. Returns 0 on success, -1 on failure.

send_add_reader_req_via_TCP

int send_add_reader_req_via_TCP(SST_ctx_t* ctx, char* add_reader_path);

Sends an add-reader request to Auth. add_reader_path is the path to a file listing the entity names to authorize. Returns 0 on success, -1 on failure.

receive_data_and_download_file

int receive_data_and_download_file(unsigned char* skey_id_in_str,
                                   SST_ctx_t* ctx,
                                   char* file_name,
                                   estimate_time_t* estimate_time);

Connects to the File System Manager, receives the CID and session key ID, downloads the encrypted file from IPFS via ipfs get, and writes the result to file_name. Returns 0 on success, -1 on failure.

file_decrypt_save

int file_decrypt_save(session_key_t s_key, char* file_name);

Decrypts the downloaded encrypted file using s_key and writes the plaintext to disk. Returns 0 on success, -1 on failure.

Configuration fields

File sharing configs include File System Manager coordinates:

Field	Example value
file_system_manager_ip_addr	127.0.0.1
file_system_manager_port_num	21800

The generated graph, Auth database, entity configs, and File System Manager config must all agree on these values.

Common pitfalls

• IPFS commands fail if the daemon is not running (ipfs daemon).
• Add-reader requests require a file path, not a raw reader name string.
• File sharing examples require the file_sharing.graph, not the default graph.
• The File System Manager must be running before uploader or downloader entities that contact it.
• Generated file paths are relative to the example working directory; run commands from the correct directories.

Next steps

• See C API Reference for full function documentation.
• See File Block Encryption for offline block-level encryption without IPFS.
• See Server/Client Example for basic secure socket communication.