pwsec 0.5.2

Support for password-based encryption.
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
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

# `pwsec` - support for password-based encryption

[![Latest version](https://img.shields.io/crates/v/pwsec.svg)](https://crates.io/crates/pwsec)
[![Documentation](https://docs.rs/pwsec/badge.svg)](https://docs.rs/pwsec)
[![License](https://img.shields.io/crates/l/pwsec.svg)](https://github.com/emabee/pwsec)
[![Build](https://img.shields.io/github/actions/workflow/status/emabee/pwsec/ci_test.yml?branch=main)](https://github.com/emabee/pwsec/actions?query=workflow%3ACI)
[![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)

## Usage

Add `pwsec` to the dependencies section in your project's `Cargo.toml`:

```toml
[dependencies]
pwsec = "0.5"
```

## Capabilities

`pwsec` uses an (optionally authenticated) encryption scheme.

Two closely related variants are provided currently, `Chacha` and `ChachaB64`.

Alternative variants with similar API and based on other encryption algorithms can be added on demand.

## Example with `ChachaB64` and storage in a file

```rust
const PBKDF2_ROUNDS: u32 = 172_234; // Choose some awkward high number

// Usecase: you have some secret data that you want to encrypt,
// so that you can store it to a file and decrypt them later.
let secret = b"this is some serialized form of the secret data";

// You also have an authentication tag, which is not secret,
// it is used to verify the integrity of the stored data.
// It can be a hash of the data, or some other summary.
// In this example, we use a simple string as the auth tag.
let auth_tag = b"arbitrary, nonconfidential text";

// You use a password to encrypt and decrypt the data, and you have to remember it
let password = "LOIUo98zkjhB";
```

### Encryption

```rust
// Encrypt the secret and store the result
let storage = {
    let cipher = ChachaB64::with_pbkdf2_rounds(PBKDF2_ROUNDS)
        .encrypt_auth(secret, auth_tag, password)?
        .to_string();

    (cipher, auth_tag)
};
```

```mermaid
flowchart LR

A1{{Auth data}}
A2[/Auth data/]
C[/CipherB64:
salt+ciphertext+nonce/]
E[__ChachaB64::__
__encrypt_auth__
]
P{{Password}}
S{{Secret}}

style E fill:#AAf,stroke:#333,stroke-width:3px

subgraph File
    C
    A2
end

subgraph Application Data
    A1
    S
end
P

P --> E
S -- Serialization --> E
A1 -- Serialization --> E

E --> C
A1 -. Serialization .-> A2
```

### Decryption

```rust
// Read the cipher and the auth_tag from whereever you stored them
let (cipher, auth_tag) = storage;
let cipher_b64 = CipherB64::parse(&cipher).context("bad decrypt")?;

// Provide the password and decrypt the secret
let decrypted_secret = ChachaB64::with_pbkdf2_rounds(PBKDF2_ROUNDS)
    .decrypt_auth(cipher_b64, &auth_tag, password)?;

assert_eq!(*secret, *decrypted_secret);
```

```mermaid
flowchart RL

A1{{Auth data}}
A2[/Auth data/]
C[/CipherB64:
salt+ciphertext+nonce/]
D[__ChachaB64::
decrypt_auth__]
P{{Password}}
S{{Secret}}

style D fill:#AAf,stroke:#333,stroke-width:3px

subgraph File
    C
    A2
end

subgraph Application Data
    A1
    S
end
P

P --> D
D -- Deserialization --> S
A2 --> D

C --> D
A2 -. Deserialization .-> A1
```

## Versions

See the change log for more details.

## License

Licensed under either of:

- Apache License, Version 2.0
- MIT license

at your option.