Docker Usage¶

For ultra-secure operations, Fractum can run in a completely network-isolated Docker container. The primary benefit of this approach is that the --network=none flag provides users with confidence that the Fractum code cannot exfiltrate their secrets through any network connection. Additionally, this Docker setup can work inside a TEE using tools like Enclaver.io for even more advanced security scenarios.

Setup¶

1. Clone the repository:

   Bash

   git clone https://github.com/katvio/fractum.git
   cd fractum
   git checkout tags/v1.3.0
   

2. Build the Docker image:

   Bash

   docker build -t fractum-secure .
   

3. Create data folders:

   Bash

   mkdir -p data
   

4. Place the file to be encrypted in the data folder:

This step is essential as the Docker container can only access files within the mounted data directory.

# Move a file to the data directory
mv /path/to/your/file.txt data/

# Or copy if you want to keep the original
cp /path/to/your/file.txt data/

# Move a file to the data directory
Move-Item "C:\path\to\your\file.txt" data\

# Or copy if you want to keep the original
Copy-Item "C:\path\to\your\file.txt" data\

Usage Examples¶

Encrypting a file¶

docker run --rm -it \
  --network=none \
  -v "$(pwd)/data:/data" \
  -v "$(pwd)/shares:/app/shares" \
  fractum-secure encrypt /data/YOUR_FILE \
  --threshold 3 \
  --shares 5 \
  --label "descriptive-name" \
  -v

Using label: descriptive-name
Using existing shares directory
Generated share set ID: 708c547f308b39a9
Generated shares: 5
Encrypted file: /data/YOUR_FILE.enc
Created archive: /app/shares/share_1.zip
Created archive: /app/shares/share_2.zip
Created archive: /app/shares/share_3.zip
Created archive: /app/shares/share_4.zip
Created archive: /app/shares/share_5.zip

docker run --rm -it `
  --network=none `
  -v "${PWD}\data:/data" `
  -v "${PWD}\shares:/app/shares" `
  fractum-secure encrypt /data/YOUR_FILE `
  --threshold 3 `
  --shares 5 `
  --label "descriptive-name" `
  -v

Using label: descriptive-name
Using existing shares directory
Generated share set ID: 708c547f308b39a9
Generated shares: 5
Encrypted file: /data/YOUR_FILE.enc
Created archive: /app/shares/share_1.zip
Created archive: /app/shares/share_2.zip
Created archive: /app/shares/share_3.zip
Created archive: /app/shares/share_4.zip
Created archive: /app/shares/share_5.zip

Decrypting a file¶

docker run --rm -it \
  --network=none \
  -v "$(pwd)/data:/data" \
  -v "$(pwd)/shares:/app/shares" \
  fractum-secure decrypt /data/YOUR_FILE.enc \
  --shares-dir /app/shares

docker run --rm -it `
  --network=none `
  -v "${PWD}\data:/data" `
  -v "${PWD}\shares:/app/shares" `
  fractum-secure decrypt /data/YOUR_FILE.enc `
  --shares-dir /app/shares

Manual Share Entry Mode¶

When you have share key values but not the actual share files, you can use manual entry mode. This is useful when share keys are stored using physical methods (such as printing on paper or engraving on metal) rather than keeping the digital ZIP archives.

Extracting Share Keys¶

Each share ZIP archive contains a share file with the share key value:

# Extract and view share key from ZIP archive
unzip -q shares/share_2.zip -d temp/
cat temp/share_2/share_2.txt

Example share file content:

{
  "share_index": 2,
  "share_key": "ADmi79NiutDoE2Iulgn8Q+YtOcdU/UbSo4C9LPUINJ4=", # Base64-encoded cryptographic share value
  "label": "my passwords",
  "threshold": 3,
  "total_shares": 5,
  "share_set_id": "41ded860ae32a908"
}

The share_key value is what you need for manual entry.

Manual Entry with Docker¶

docker run --rm -it \
  --network=none \
  -v "$(pwd)/data:/data" \
  fractum-secure decrypt /data/YOUR_FILE.enc -m -v

Manual share entry mode activated

=== Manual Share Entry ===
Threshold (minimum number of shares needed): 3
Total shares: 5
Enter share details when prompted. Enter 'done' when finished.
Share index (or 'done' to finish): 4
Share key value (Base64 or Hex encoded): "xqUAlWLByQae82a7wDeB7BirmwP6oscu59A+YngzyjQ="
Share 4 added successfully. Total shares: 1
Share index (or 'done' to finish): 3
Share key value (Base64 or Hex encoded): Wna3TMV0V2/qaI401nnSOS3RIZSBbovBlXMhMreTUr4=
Share 3 added successfully. Total shares: 2
Share index (or 'done' to finish): 2
Share key value (Base64 or Hex encoded): ADmi79NiutDoE2Iulgn8Q+YtOcdU/UbSo4C9LPUINJ4=
Share 2 added successfully. Total shares: 3
You have enough shares for reconstruction. Proceed with decryption? [y/n]: y
Collected 3 manual shares successfully
Using shares with parameters: threshold=3, total_shares=5
File successfully decrypted: /data/YOUR_FILE.txt

docker run --rm -it `
  --network=none `
  -v "${PWD}\data:/data" `
  fractum-secure decrypt /data/YOUR_FILE.enc -m -v

Note: Manual entry mode doesn't require mounting the shares directory (-v "$(pwd)/shares:/app/shares") since you're entering the keys directly.

Security Benefits¶

The Docker approach provides several security benefits:

1. Complete network isolation: The --network=none flag prevents any network access
2. Non-root execution: Container runs as a non-privileged user
3. Minimal attack surface: Only necessary files are included in the container
4. Read-only code: Application code cannot be modified during execution
5. Ephemeral environment: Container is destroyed after each use with --rm

For detailed technical information about Fractum's cryptographic implementation and security design, see our Security Architecture documentation.

Understanding Docker Arguments¶

Troubleshooting¶

If you encounter issues with the Docker setup:

1. Ensure Docker is properly installed and running
2. Verify that your user has permissions to run Docker commands
3. Check that the data and shares directories exist and are accessible
4. Confirm that the file you want to encrypt is in the data directory