README.md


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

# file-encryption

A simple file encryption tool using memory-mapped I/O and XOR operation.

<img src = "encryption.png" />

## Description

`file-encryption` modifies a binary file **in-place** by applying a bitwise XOR
operation using a user-provided numeric key. It efficiently processes large
files in memory page-sized blocks using `mmap`, avoiding explicit read/write
loops.

This method can be used for lightweight encryption and decryption, as XOR is
symmetric: applying the same key twice restores the original file.

## Features

-  Fast in-place encryption using memory mapping (`mmap`)
-  Page-aligned memory processing for better performance
-  Supports partial blocks at the end of the file (byte-accurate)
-  Symmetric encryption: same operation encrypts and decrypts
-  No third-party dependencies, written in pure C

## Usage

```bash
git clone https://git.scratko.xyz/file-encryption
cd file-encryption
gcc -Wall encryption.c -o encryption
./encryption <filename> <key>
```

`<filename>` — path to the target file
`<key>` — numeric key used for encryption (unsigned integer)

### Example

```bash
./encryption secret.bin 12345
```
This will XOR every 4-byte word of `secret.bin` with `12345`. Running the same
command again will restore the original content.

### How it works

- The file is opened with `O_RDWR` and memory-mapped using `mmap()`.
- The numeric key is bitwise-inverted: `~key`.
- The file is processed block-by-block in chunks of `4096` bytes (aligned to
system page size).
- For each 4-byte block in the mapped memory, a XOR with the key is applied.
- If the file ends with fewer than 4 bytes remaining, only those bytes are
XORed.

### Limitations

- Works only on POSIX-compatible systems (Linux, macOS)
- Assumes int is 4 bytes and little-endian architecture
- The file is modified in-place — no backups or safety checks