Skip to content

Decrypting Files

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

Fractum Decryption Diagram

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.

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

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