Table of Contents

• OpaqueFiles
• Before you install
• Vulnerabilities
• Known Vulnerabilities
• Bug Reports Welcome!
• Quick start
• 0. Preparation
• 0.1 Password Management
• 0.1.1 Generate a password
• 0.1.2 Secure the password
• 1 Installation
• 1.1 Windows and Mac
• 1.1.0 Java
• 1.1.1 Download and Extraction
• 1.2 Linux
• 1.2.0 ALL DISTRIBUTIONS (Flatpak)
• 1.2.0.0 Preparation
• 1.2.0.1 Installation
• 1.2.0.2 Updating
• 1.2.0.3 Removal
• 1.2.1 Debian
• 1.2.1.1 Installation
• 1.2.1.2 Updating
• 1.2.1.3 Removal
• 1.2.2 ArchLinux
• 1.2.2.1 Installation
• 1.2.2.2 Updating
• 1.2.2.3 Removal
• 1.2.3 Gentoo
• 1.2.3.1 Installation
• 1.2.3.2 Updating
• 1.2.3.3 Removal
• 1.4 Troubleshooting
• 2 First run
• 2.1 Preparation
• 2.1.1 Create test files
• 2.2 Start OpaqueFiles
• 2.2.1 Windows/Mac
• 2.2.2 Linux
• 2.3 Enter password
• 2.4 Encrypt
• 2.4.1 Results
• 2.5 Encrypt more
• 2.5.1 Windows/Mac
• 2.5.2 Linux
• 2.5.3 Results
• 2.6 Decrypt
• 2.6.1 Windows/Mac
• 2.6.2 Linux
• 2.6.3 Result
• 3 Use OpaqueFiles
• Main features
• Overview
• 1 🔒 Encryption (Default: ChaCha20)
• 1.1 ChaCha20
• 1.2 AES256
• 2 🗜 Compression (Default: Zstd)
• 2.1 None
• 2.2 Zstd
• 2.3 gzip
• 2.4 XZ (LZMA2)
• 3 🩹 Error correction (Default: 10%)
• 4 🪨 Argon2id key derivation
• 5 ✅ Verification (Default: on)
• 6 🧽 Scrubbing
• 7 🚰 Unix Pipelines
• 8 🌡 Stress testing
• Who is OpaqueFiles for?
• Support the Project

OpaqueFiles

A free and open-source file encryption software for Linux, Windows and Mac that encrypts/decrypts files so they can be stored securely, utilizing compression (Zstd/gzip/LZMA2), Reed–Solomon Error Correction, encryption(ChaCha20/AES-GCM-SIV) and keys derived from the user's password with Argon2id.

Before you install

OpaqueFiles can be used to encrypt files before uploading them to a cloud provider for synchronization across multiple devices. This protects the contents in those files from the cloud provider and from hackers that might gain acess to your cloud account.
Before considering OpaqueFiles, you should check out Cryptomator, as it is more suitable to most users.
A comparison with other encryption software can be found in the Why OpaqueFiles? section of the wiki.

In cases where the encrypted files should be navigated and downloaded individually using a web GUI, OpaqueFiles is the most user friendly option (to my knowledge).

I wrote OpaqueFiles in my free time, and while it is neither perfect nor bug-free, it is good enough that i entrust my personal data to it.

Vulnerabilities

There is always the chance that my implementation is leaking or has a vulnerability.

Do not use OpaqueFiles to encrypt personal files and then store them in a completely untrusted location. This is an additional layer of security, not THE layer of security.

Known Vulnerabilities

Known vulnerabilities will be listed here. If you feel like you want to search for vulnerabilities, best start at the specification.

Bug Reports Welcome!

As OpaqueFiles has just been released, bugs are to be expected. If you encounter a bug, please open an issue.

Quick start

This quick start guide will instruct you step by step how to use OpaqueFiles on your computer.

0. Preparation

0.1 Password Management

Please follow the following instructions without skipping any step. If you lose your password(s), all your file's contents will be lost.

0.1.1 Generate a password

Use an open-source password manager like KeePassXC to generate a safe password with more than 6 characters. The password can use any Unicode characters. The longer the better. I recommend 30 characters.

0.1.2 Secure the password

Secure the password by writing it down and storing the paper in a safe, or better put it into your password manager and secure your password manger file in a fireproof and waterproof location.

If you lose your password, you lose your files.

This way you will not loose your password even if you forget it. Use a password manager to acess the password each time you need it.

1 Installation

1.1 Windows and Mac

1.1.0 Java

You need to install Java to run OpaqueFiles. You can find a step-by-step guide to installing Java in the wiki.

1.1.1 Download and Extraction

Download the newest version of OpaqueFiles from the RELEASES folder.

1.2 Linux

1.2.0 ALL DISTRIBUTIONS (Flatpak)

1.2.0.0 Preparation

The OpaqueFiles flatpak requires flatpak to be installed: Install flatpak

1.2.0.1 Installation

user $ flatpak install flathub page.codeberg.cozyowl.OpaqueFiles

1.2.0.2 Updating

user $ flatpak update

1.2.0.3 Removal

user $ flatpak remove page.codeberg.cozyowl.OpaqueFiles
user $ rm -r ~/.config/OpaqueFiles

1.2.1 Debian

1.2.1.1 Installation

user $ git clone https://codeberg.org/cozyOwl/OpaqueFiles.git
user $ cd OpaqueFiles/packaging/debian
user $ git checkout tags/v0.9.11.0
user $ ./packageDebian.sh 0.9.11.0
ROOT # apt install ./opaquefiles_0.9.11.0-1_amd64.deb

1.2.1.2 Updating

user $ cd OpaqueFiles/packaging/debian
user $ git fetch
user $ git checkout tags/v0.9.11.0
user $ ./packageDebian.sh 0.9.11.0
ROOT # apt install ./opaquefiles_0.9.11.0-1_amd64.deb

1.2.1.3 Removal

ROOT # apt remove opaquefiles
user $ rm -r ~/.config/OpaqueFiles

1.2.2 ArchLinux

1.2.2.1 Installation

user $ yay -S opquefiles

1.2.2.2 Updating

user $ yay -Syu

1.2.2.3 Removal

user $ yay -R opaquefiles
user $ rm -r ~/.config/OpaqueFiles

1.2.3 Gentoo

1.2.3.1 Installation

ROOT # eselect repository create cozyowl
ROOT # mkdir --parents /var/db/repos/cozyowl/app-crypt/opaquefiles
ROOT # cd /var/db/repos/cozyowl/app-crypt/opaquefiles
ROOT # wget https://codeberg.org/cozyOwl/OpaqueFiles/raw/branch/main/packaging/gentoo/opaquefiles-0.9.11.0-r0.ebuild
ROOT # emerge -av app-crypt/opaquefiles::cozyowl

1.2.3.2 Updating

ROOT # cd /var/db/repos/cozyowl/app-crypt/opaquefiles
ROOT # wget -N https://codeberg.org/cozyOwl/OpaqueFiles/raw/branch/main/packaging/gentoo/opaquefiles-0.9.11.0-r0.ebuild
ROOT # emerge -av app-crypt/opaquefiles::cozyowl

1.2.3.3 Removal

ROOT # emerge --deselect app-crypt/opaquefiles::cozyowl
user $ rm -r ~/.config/OpaqueFiles

1.4 Troubleshooting

You encountered an error while installing, updating or uninstalling? These instructions need to be changed? Please report this bug, so others may not encounter it.

2 First run

You are about to start OpaqueFiles for the first time. But before that, you need to set up a test environment so that you don't encrypt all of your files accidentially while testing around.

2.1 Preparation

Your desktop is the location where you usually copy your files around. For most people that should be the desktop, but if you have a different folder, replace desktop with whatever folder you are most comfortable with.

2.1.1 Create test files

On your desktop, create a folder called testing. Inside testing, create 3 text files named test1.txt, test2.txt and test3.txt.

2.2 Start OpaqueFiles

2.2.1 Windows/Mac

Now copy the OpaqueFiles.jar from the downloaded archive into testing.

Double click OpaqueFiles.jar. Click the folder icon next to scope and select test1.txt.

2.2.2 Linux

Right click the test1.txt file and select Open with > OpaqueFiles.

2.3 Enter password

Enter the password into the password field, by copying it from your password manager.

Please make sure the scope is set to test1.txt.

2.4 Encrypt

Click and hold the ENCRYPT button on the bottom to start the encryption process.

2.4.1 Results

As you can see, test1.txt was encrypted, while test2.txt and test3.txt remain unchanged.

2.5 Encrypt more

2.5.1 Windows/Mac

Run OpaqueFiles again, and in the scope selector, select test2.txt and test3.txt simultaneously. Encrypt.

2.5.2 Linux

Select test2.txt and test3.txt simultaneously in your file browser, then select Open with > OpaqueFiles. Encrypt.

2.5.3 Results

As you can see, you can encrypt multiple files simultaneously.

Now, take some larger files and COPY (not move) them into testing. Encrypt them too.

2.6 Decrypt

2.6.1 Windows/Mac

Start OpaqueFiles.jar, enter your password and hold the DECRYPT button. As you can see, if you do not select a scope yourself, OpaqueFiles uses the current directory as scope.

2.6.2 Linux

Select the testing folder in your file browser, then select Open with > OpaqueFiles. Enter your password and hold the DECRYPT button.

2.6.3 Result

As you can see, you can select folders as scopes, and encrypt or decrypt all files within simultaneously. And yes, you can select files and folders at the same time.

3 Use OpaqueFiles

Congratulations! You are now ready to use OpaqueFiles anywhere on your disk. Please do not use more than one password, because you will get confused which files were encrypted with which password. Also remember that you can come back and read the troubleshooting part of the wiki if you have any problems. If you want to use OpaqueFiles now, do it.

To make the process of encryption/decryption easier and faster, read the advanced features part of the wiki.

Main features

Overview

┌─────────────[HEADER]─────────────┐           >Helps distinguish OpaqueFiles from other files
│            IDENTIFIER            │             and distinguishes different versions from each other.
│             Version              │
└──────────────────────────────────┘
┌─────────────[ECC]────────────────┐           >Error Correction Code (ReedSolomon) protects from bit rot.
│                                  │
│ ┌────────[METADATA]──────────┐   │           >Stores important information for decryption.
│ │                            │   │
│ │ ┌──────[ENCRYPTION]──────┐ │   │           >Protects against spying eyes.
│ │ │                        │ │   │             AES256 or ChaCha20 (faster, default).
│ │ │ ┌────[COMPRESSION]───┐ │ │   │           >Keeps the file size in check,
│ │ │ │                    │ │ │   │             so uploading and storing is fast and cheap.
│ │ │ │ ┌────[HASHING]───┐ │ │ │   │           >Protects against data corruption during encryption,
│ │ │ │ │ ORIGINAL FILE  │ │ │ │   │              and makes sure that the decrypted file is unaltered.
│ │ │ │ └────────────────┘ │ │ │   │              SHA1 or SHA256 or SHA512 (default) or SHA3-512
│ │ │ │                    │ │ │   │
│ │ │ └────────────────────┘ │ │   │
│ │ │                        │ │   │
│ │ └────────────────────────┘ │   │
│ │                            │   │
│ └────────────────────────────┘   │
│                                  │
└──────────────────────────────────┘

1 🔒 Encryption (Default: ChaCha20)

OpaqueFiles supports two encryption algorithms. These are used to keep your data safe.

1.1 ChaCha20

ChaCha20 is more modern and faster than AES, but less well tested, and can therefore be seen as less secure.

1.2 AES256

AES-GCM-SIV can be enabled in the configuration file. AES256 is old and reliable, and the recommended option if you want the highest level of security.

2 🗜 Compression (Default: Zstd)

As OpaqueFiles is meant for archiving data without acessing the data frequently, keeping the file size small is more important than processing speed. OpaqueFiles supports multiple modern compression algorithms, including no compression. No compression should be used when compressing data that was already compressed efficiently like images, videos and audio.

2.1 None

Compression can be disabled to improve processing speed on already compressed data like videos, pictures and audio. Speed: 100%.

2.2 Zstd

Zstd is a very fast, modern compression algorithm. Compression: Decent. Speed: 80-110%.

2.3 gzip

Gzip, an old and reliable compression algorithm. Compression: Good. Speed: ~30%.

2.4 XZ (LZMA2)

LZMA2 offers the highest compression ratio. Compression: Great. Speed: ~4%.

3 🩹 Error correction (Default: 10%)

Reed–Solomon Error Correction (Error Correction Code, ECC) is used by OpaqueFiles to recover from bit rot. This helps if you plan to store the encrypted files on an external HDD or SSD, and you forget regular data scrubbing.

4 🪨 Argon2id key derivation

Argon2id is used to ensure even weak passwords generate somewhat strong keys. This helps to keep the data secure.

5 ✅ Verification (Default: on)

As long as verification is not disabled, each file that is encrypted is immediately decrypted afterwards to see if the encrypted file can be decrypted and contains the same data as the unencrypted file. This protects against data corruption, bugs during encryption and malicious manipulation. The same thing happens during decryption.

6 🧽 Scrubbing

OpaqueFiles can be instructed to scrub encrypted files for bit rot and resolve these errors automatically. This is called data scrubbing, and it does not even use a password. Scrubbing can not detect malicious manipulation.

7 🚰 Unix Pipelines

OpaqueFiles can be instructed to use Unix Pipelines for input and output.

8 🌡 Stress testing

OpaqueFiles can be used to test CPU/RAM stability. For me, it is faster in detecting errors than Prime95.

Who is OpaqueFiles for?

OpaqueFiles is for all users who want to store or archive files in the cloud while protecting the content of their files from the eyes of a cloud provider, hackers or other attackers that might have access to the files in the cloud. OpaqueFiles sacrifices some privacy for convenience by storing the names of files, their size and their modification date unencrypted.

OpaqueFiles is not for those users who want to change these files regularly. See Why OpaqueFiles? for more info.

Support the Project

If my program helped you in some way and you want to say 'Thank you!' for this program in a monetary way, click here.