rsecure 0.7.0

A simple file encryption and decryption tool using AES-GCM.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167

# rsecure

`rsecure` is a simple and secure command-line tool for AES-256-GCM file encryption and decryption, built in pure Rust. You can use either a 32-byte key file (default) or a passphrase (Argon2id) as the credential. Each file is then encrypted under a unique per-file subkey derived via HKDF-SHA256, eliminating any practical risk of nonce collision across files. Ideal for protecting sensitive files, backups, and personal data.

`rsecure` uses `stream` encryption and `rayon` parallelism. The speed of the encryption also depends of your hardware specs (disk speed, CPU speed and number of cores).

<p align="center" >
    <a href="https://github.com/containerscrew/rsecure/actions/workflows/ci-cd.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/containerscrew/rsecure/ci-cd.yml?branch=main&label=CI"></a>
    <a href="./CHANGELOG.md"><img alt="Changelog" src="https://img.shields.io/badge/changelog-md-blue"></a>
    <img alt="GitHub code size in bytes" src="https://img.shields.io/github/languages/code-size/containerscrew/rsecure">
    <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/containerscrew/rsecure">
    <img alt="GitHub issues" src="https://img.shields.io/github/issues/containerscrew/rsecure">
    <img alt="GitHub pull requests" src="https://img.shields.io/github/issues-pr/containerscrew/rsecure">
    <img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/containerscrew/rsecure?style=social">
    <img alt="GitHub watchers" src="https://img.shields.io/github/watchers/containerscrew/rsecure?style=social">
    <img alt="License" src="https://img.shields.io/badge/License-GPLv3-blue.svg">
    <img alt="Crates.io" src="https://img.shields.io/crates/v/rsecure">
    <img alt="AUR Version" src="https://img.shields.io/aur/version/rsecure">
    <img alt="Crates.io Total Downloads"
     src="https://img.shields.io/crates/d/rsecure?label=crates.io%20downloads">
    <img alt="GitHub Releases Downloads"
        src="https://img.shields.io/github/downloads/containerscrew/rsecure/total?label=github%20downloads">
</p>

---

![rsecure CLI demo: generating a key, encrypting and decrypting files with a progress bar](./demo.gif)

---

## Quickstart

```bash
# 1. Install
curl --proto '=https' --tlsv1.2 -sSfL https://raw.githubusercontent.com/containerscrew/rsecure/main/install.sh | sh

# 2. Generate a demo key (for real use, store the key on a USB drive or password manager!)
rsecure create-key -o /tmp/rsecure.key

# 3. Create a test file
echo "hello rsecure" > /tmp/secret.txt

# 4. Encrypt it (-r removes the plaintext after encryption)
rsecure encrypt -p /tmp/rsecure.key -s /tmp/secret.txt -r

# 5. Decrypt it back
rsecure decrypt -p /tmp/rsecure.key -s /tmp/secret.txt.enc
```

> [!WARNING]
> If you lose the key, the encrypted data is unrecoverable. Read the [Security](#security) section before storing real data.

## Installation

### Universal install script

```shell
curl --proto '=https' --tlsv1.2 -sSfL https://raw.githubusercontent.com/containerscrew/rsecure/main/install.sh | sh
```

Pin a specific release by appending `-s -- -v <version>`:

```shell
curl --proto '=https' --tlsv1.2 -sSfL https://raw.githubusercontent.com/containerscrew/rsecure/main/install.sh | sh -s -- -v <version>
```

> [!NOTE]
> The installation script automatically detects your `OS` and `ARCH` and installs the correct binary (rpm, deb, apk, or just a binary in `/usr/local/bin`). On Alpine, install `apk add gcompat` since the binary is built with `glibc` and Alpine uses `musl`.

### AUR (Arch Linux)

```bash
paru -S rsecure # or yay -S rsecure
```

### Homebrew

```bash
brew install containerscrew/tap/rsecure
```

> [!NOTE]
> If you installed an older version via `brew install --cask rsecure`, run `brew uninstall --cask rsecure` first — `rsecure` is now distributed as a Homebrew formula, which avoids the macOS Gatekeeper quarantine that affected the cask.

### Using [`cargo`](https://rustup.rs/)

```bash
cargo install rsecure
cargo install rsecure --version <version>   # pin a specific release
```

### Local build

```bash
git clone https://github.com/containerscrew/rsecure.git
cd rsecure
cargo build --release
sudo cp ./target/release/rsecure /usr/local/bin/
```

## Usage

### Commands

| Command                                                                                  | Description                                                          |
| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `rsecure create-key -o /mnt/myusb/rsecure.key`                                           | Generate a new AES-256 key and save it to a file                     |
| `openssl rand -out /mnt/myusb/rsecure.key 32`                                            | Alternative: generate a random 256-bit key using OpenSSL             |
| `rsecure encrypt -p /mnt/myusb/rsecure.key -s /home/mydirectory/text_to_encrypt.txt`     | Encrypt a single file (`.enc` file is created in the same directory) |
| `rsecure encrypt -p /mnt/myusb/rsecure.key -s /home/mydirectory/files/`                  | Encrypt all files in a directory                                     |
| `rsecure decrypt -p /mnt/myusb/rsecure.key -s /home/mydirectory/text_to_encrypt.txt.enc` | Decrypt a single encrypted file                                      |
| `rsecure decrypt -p /mnt/myusb/rsecure.key -s /home/mydirectory/files/`                  | Decrypt all files in a directory                                     |
| `rsecure encrypt -r -p /mnt/myusb/rsecure.key -s /home/rsecure/dirtoencrypt/`            | Encrypt and **remove** original files (plain text)                   |
| `rsecure encrypt -p /mnt/myusb/rsecure.key -s /home/rsecure/dirtoencrypt -e '.git'`      | Encrypt all files in a directory excluding `.git/` files             |
| `rsecure encrypt --passphrase -s /home/mydirectory/text_to_encrypt.txt`                  | Encrypt with a passphrase (Argon2id), no key file needed             |
| `rsecure decrypt -s /home/mydirectory/text_to_encrypt.txt.enc`                           | Decrypt a passphrase-encrypted file (auto-detected, prompts for it)  |

> [!WARNING]
> Saving the key in the same local filesystem where you save the encrypted files is not a good idea.
> Save the key in a secure location, like a `USB drive` or a password manager.
> Or just save it in a `root owned directory` with strict permissions (will require sudo to use it).

Something like:

```bash
sudo rsecure encrypt -p /root/rsecure.key -s /home/dcr/Documents/PrivateDocuments -r
```

> `rsecure` must be in a PATH directory where `root` user can execute it. Which means, if you installed it using `cargo`, you need to add `~/.cargo/bin` to the `PATH` variable in the `root` user environment. Or just copy the binary to `/usr/local/bin/` or any other directory in the `PATH`.

> [!IMPORTANT]
> By default, `rsecure` will not delete the source plain files after encryption to avoid data loss.
> If you want to delete the source files after encryption, use `-r` flag.

## Security

`rsecure` encrypts file contents with **AES-256-GCM** via the audited [`aes-gcm`](https://crates.io/crates/aes-gcm) crate from [RustCrypto](https://github.com/RustCrypto), using the STREAM construction (`EncryptorBE32`) over 128 KiB chunks. For each file, a 32-byte random salt is generated and a unique AES-256 subkey is derived from the master key via [HKDF-SHA256](https://crates.io/crates/hkdf), so the `(key, nonce)` pair is globally unique and nonce-collision attacks against AES-GCM are not a concern in practice. Files written by rsecure ≤ 0.5.0 (no HKDF, 7-byte random nonce, no header) are still decrypted transparently — the `RSEC` magic header in new files distinguishes the two formats. The crate forbids `unsafe` code at the root (`#![forbid(unsafe_code)]`), and the dependency tree is continuously checked against the [RustSec Advisory Database](https://rustsec.org/) by `cargo-audit` and `cargo-deny` in CI.

Read [`SECURITY.md`](./SECURITY.md) for the full threat model — what `rsecure` does and does not protect against, the exact cryptographic parameters, and key custody guidance.

To report a vulnerability, please use [GitHub Security Advisories](https://github.com/containerscrew/rsecure/security/advisories/new) — do **not** open a public issue.

## Local dev

Testing encryption and decryption:

```bash
git clone https://github.com/containerscrew/rsecure.git
cd rsecure
sh scripts/fake_data.sh # will generate 17gb of fake data in /var/tmp/dummy_files/
rsecure encrypt -p /var/tmp/rsecure.key -s /var/tmp/dummy_files/
rsecure decrypt -p /var/tmp/rsecure.key -s /var/tmp/dummy_files/
```

> Edit the `fake_data.sh` script to create different types of files and directories for testing.

### Benchmark (hyperfine)

```bash
cargo install hyperfine
hyperfine --runs 5 'rsecure encrypt -p /var/tmp/rsecure.key -s /var/tmp/dummy_files/'
hyperfine --runs 5 'rsecure decrypt -p /var/tmp/rsecure.key -s /var/tmp/dummy_files/'
```

## License

`rsecure` is distributed under the terms of the [GPLv3](./LICENSE) license.