age-plugin-argon2 0.2.0

Argon2id recipient/identity plugin for the age encryption format
Documentation 
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

# age-plugin-argon2

An [age](https://age-encryption.org/) plugin that encrypts file keys using
[Argon2id](https://en.wikipedia.org/wiki/Argon2) — a memory-hard password
hashing function. Recipients encode the KDF parameters directly, so any
compatible age client can derive the file key from a passphrase without a
separate config file.

The plugin implements the age IPC plugin protocol and works with any
age-compatible client: [rage](https://github.com/str4d/rage),
[passage](https://github.com/FiloSottile/passage), and others.

## Why Argon2id?

age ships built-in passphrase encryption using
[scrypt](https://en.wikipedia.org/wiki/Scrypt). Argon2id is an alternative KDF
with a few practical advantages:

- **Harder to crack in parallel.** Each Argon2id instance must hold the full
  memory cost in RAM simultaneously. Parallelising a brute-force attack requires
  proportionally more memory per thread, which raises the cost of GPU and ASIC
  cracking — important when ciphertext is publicly accessible.
- **Three tunable axes.** Memory cost (`--m-cost`), time cost (`--t-cost`), and
  parallelism (`--p-cost`) are independently configurable, so you can fit
  hardness to your hardware.
- **PHC winner.** Argon2id won the
  [Password Hashing Competition](https://www.password-hashing.net/) in 2015 and
  is the recommended choice for new systems (RFC 9106).
- **Encoded in the recipient.** Parameters travel with the ciphertext — no side
  channel needed to share KDF settings.

## Installation

```
cargo install age-plugin-argon2
```

The binary must be named `age-plugin-argon2` and be on your `$PATH` so age
clients can discover it automatically.

## Usage

### Generate an identity

```
age-plugin-argon2 --generate [-o OUTPUT] [--m-cost KiB] [--t-cost N] [--p-cost N]
```

Defaults: `--m-cost 65536` (64 MiB), `--t-cost 3`, `--p-cost 4`.

The identity is written to `OUTPUT` (or stdout). The corresponding recipient is
printed to stderr.

```
$ age-plugin-argon2 --generate -o key.txt
# Recipient: age1argon2...
```

### Encrypt

Pass the recipient string directly with `-r`, or point at an identity file with
`-R`:

```
rage -r age1argon2... -o secret.age plaintext.txt
rage -R key.txt -o secret.age plaintext.txt
```

The age client will prompt for a passphrase.

### Decrypt

```
rage -d -i key.txt -o plaintext.txt secret.age
```

The age client discovers the plugin via `$PATH`, handles the passphrase prompt,
and calls back into the plugin to unwrap the file key.

### List recipients

Extract the recipient strings from an identity file:

```
age-plugin-argon2 --list -i key.txt
```

## License

Licensed under [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE), at your
option.

## Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.

### Pre-commit hooks

Consider installing the commit hooks before your first commit:

```sh
git config core.hooksPath .githooks
```

The pre-commit hook runs `cargo fmt` and `prettier` on Markdown files. You'll
need [Node.js](https://nodejs.org) available for the latter.