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:
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:
- Select decryption operation
- Choose your encrypted file or specify shares directory
- Let Fractum automatically detect and use the required shares
Expected interactive session
=== 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.
Expected output
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
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:
# 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",
"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 valuethreshold
: The minimum number of shares needed (K value)total_shares
: The total number of shares created (N value)
Manual Entry Commands¶
Expected interactive session
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
docker run --rm -it \
--network=none \
-v "$(pwd)/data:/data" \
fractum-secure decrypt /data/MY_FILE.txt.enc -m -v
Expected interactive session
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¶
- Insufficient shares: Ensure you have at least K shares from the same encryption operation
- Incorrect shares: Check that shares are from the same encryption operation and are not corrupted
- Permission errors: Verify you have read access to share files and write access to output location
- 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.
- Test shares periodically with non-sensitive test data to ensure they're still valid
- Use clean, isolated systems for decryption when possible
- Verify output after decryption to ensure successful reconstruction
- Clear sensitive data from the system after use
- Document your threshold so you know how many shares you need