Skip to content

# 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 Dstack-TEE 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.

Linux/macOS Windows (PowerShell)
Bash

    # 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/

PowerShell

    # 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

Linux/macOS Windows (PowerShell)
Bash

    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

Expected output:

Text Only

    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

PowerShell

    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

Expected output:

Text Only

    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

Linux/macOS Windows (PowerShell)
Bash

    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

PowerShell

    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:

Bash

    # 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:

JSON

    {
      "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

Linux/macOS Windows (PowerShell)
Bash

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

Expected interactive session:

Text Only

    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

PowerShell

    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

Argument | Purpose
--- | ---
`--rm` | Automatically remove the container when it exits
`-it` | Interactive mode with a terminal
`--network=none` | Completely isolate from all networks
`-v "$(pwd)/data:/data"` | Mount local data directory into container
`-v "$(pwd)/shares:/app/shares"` | Mount local shares directory into container

## 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

Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Help us improve by opening an issue.