Skip to content

# Decrypting Files

This guide explains how to reconstruct and decrypt your files using Fractum shares.

## Prerequisites

Before decrypting, you need:

- Fractum properly installed (manually or using docker)
- The file you want to decrypt ready (.enc file)
- At least K shares (where K is your threshold)

## Basic Decryption

### Interactive Mode

The simplest way to decrypt is using interactive mode:

Bash

    fractum -i

Interactive mode will:

• Display the current Fractum version
• Show available encrypted files and shares
• Prompt you to select the operation (encrypt/decrypt)
• Guide you through the decryption process

Follow the prompts to:

1. Select decryption operation
2. Choose your encrypted file or specify shares directory
3. Let Fractum automatically detect and use the required shares

Expected interactive session
Text Only

    === Fractum Interactive Mode ===

    What would you like to do?
    1. Encrypt a file
    2. Decrypt a file
    3. Verify shares
    4. Quit
    Your choice: 2

    === Decrypt a file ===
    Full path of the file to decrypt: /Users/alice/my_repos/fractum/MY_FILE.txt.enc
    Do you want to enter the share keys manually? If not, you will be asked to provide the path to the folder containing the necessary share files? [y/n]: n
    Full path of the directory containing shares: /Users/alice/my_repos/fractum/shares
    Using shares directory: /Users/alice/my_repos/fractum/shares
    Do you want to enable verbose mode? [y/n]: y

    Decryption parameters:
    File to decrypt: /Users/alice/my_repos/fractum/MY_FILE.txt.enc
    Shares directory: /Users/alice/my_repos/fractum/shares
    Verbose mode: Enabled
    Looking for shares in: /Users/alice/my_repos/fractum/shares
    Found share set ID in metadata: 41ded860ae32a908
    Found 5 ZIP archives
    Processing 5 share files/archives

    Found shares with set IDs: 41ded860ae32a908
    Found shares for 1 different labels
      - my_passwords: 5 shares (threshold: 3)
    Using shares with set ID: 41ded860ae32a908

    Using shares for label: my_passwords
    Found 5 shares (need 3)
    Key reconstructed from shares
    File successfully decrypted: /Users/alice/my_repos/fractum/MY_FILE.txt

    Operation completed successfully!

### Command Line Mode

You can decrypt files directly from the command line using either manual installation or Docker.

Manual Installation Docker Usage
Bash

    fractum decrypt MY_FILE.txt.enc --shares-dir ./shares -v

Expected output
Text Only

    Looking for shares in: /Users/alice/my_repos/fractum/shares
    Found share set ID in metadata: 41ded860ae32a908
    Found 5 ZIP archives
    Processing 5 share files/archives

    Found shares with set IDs: 41ded860ae32a908
    Found shares for 1 different labels
      - hi: 5 shares (threshold: 3)
    Using shares with set ID: 41ded860ae32a908

    Using shares for label: hi
    Found 5 shares (need 3)
    Key reconstructed from shares
    File successfully decrypted: /Users/alice/my_repos/fractum/MY_FILE.txt

First, ensure your encrypted file is in the `data` directory:

Bash

    # Move your encrypted file to the data directory
    mv MY_FILE.txt.enc data/

Then run the decryption command:

Bash

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

Expected output
Text Only

    File successfully decrypted: /data/MY_FILE.txt

### Manual Share Entry Mode

When you don't have access to the share files but have the share key values, you can use manual entry mode with the `-m` flag. 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 (e.g., `share_2.txt`) 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",
      "share_integrity_hash": "d5201c0d817c9960182aeda0f9abeb98c7c81dff99e8268c602739a851086cc0",
      "threshold": 3,
      "total_shares": 5,
      "tool_integrity": { ... },
      "python_version": "3.12.10",
      "share_set_id": "41ded860ae32a908"
    }

Critical values that you'll be asked for:

- `share_index`: The unique identifier for the given specific share (e.g., 2)
- `share_key`: The Base64-encoded cryptographic share value
- `threshold`: The minimum number of shares needed (K value)
- `total_shares`: The total number of shares created (N value)

#### Manual Entry Commands

Manual Installation Docker Usage
Bash

    fractum decrypt MY_FILE.txt.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): 2
    Share key value (Base64 or Hex encoded): "ADmi79NiutDoE2Iulgn8Q+YtOcdU/UbSo4C9LPUINJ4="
    Share 2 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): 4
    Share key value (Base64 or Hex encoded): "xqUAlWLByQae82a7wDeB7BirmwP6oscu59A+YngzyjQ="
    Share 4 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: /Users/alice/my_repos/fractum/data/MY_FILE.txt

Bash

    docker run --rm -it \
      --network=none \
      -v "$(pwd)/data:/data" \
      fractum-secure decrypt /data/MY_FILE.txt.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/MY_FILE.txt

Note: Manual entry mode doesn't require mounting the shares directory since you're entering the keys directly.

### Share Detection

Fractum automatically:

- Detects available shares in the specified directory
- Checks which shares are needed for your threshold
- Uses exactly K shares for reconstruction
- Handles share metadata and compatibility verification

## Troubleshooting

### Common Issues

1. Insufficient shares: Ensure you have at least K shares from the same encryption operation
2. Incorrect shares: Check that shares are from the same encryption operation and are not corrupted
3. Permission errors: Verify you have read access to share files and write access to output location
4. Corrupted shares: Individual share corruption will be detected during reconstruction

### Error Messages

"Insufficient shares for reconstruction"

- You have fewer than K shares
- Solution: Obtain additional shares from the same encryption

"Share verification failed"

- One or more shares are corrupted or from different encryptions
- Solution: Use different shares or obtain uncorrupted copies

"Cannot write output file"

- Permission or disk space issues
- Solution: Check output directory permissions and available disk space

## Security Notes

- Temporary files: Fractum doesn't create temporary unencrypted files during decryption
- Memory clearing: Sensitive data is automatically cleared from memory after use
- Integrity checking: File integrity is verified during reconstruction

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

## Best Practices

For comprehensive security guidance, see our Security Best Practices guide.

1. Test shares periodically with non-sensitive test data to ensure they're still valid
2. Use clean, isolated systems for decryption when possible
3. Verify output after decryption to ensure successful reconstruction
4. Clear sensitive data from the system after use
5. Document your threshold so you know how many shares you need

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