rusty_paseto 0.10.0

A type-driven, ergonomic alternative to JWT for secure stateless PASETO tokens.
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

export const metadata = {
  title: 'Installation',
  description:
    'Learn how to install rusty_paseto and configure feature flags for your project.',
}

# Installation

rusty_paseto uses Cargo feature flags to let you include only the PASETO versions and purposes you need, minimizing compile time and binary size. {{ className: 'lead' }}

## Basic Installation

Add rusty_paseto to your `Cargo.toml`:

```bash
cargo add rusty_paseto
```

By default, no features are enabled. You must enable at least one version/purpose combination.

---

## Feature Flags

### Version and Purpose Features

Each PASETO version and purpose has its own feature flag:

<Properties>
  <Property name="v1_local">
    V1 Local (symmetric encryption with AES-256-CTR + HMAC-SHA384)
  </Property>
  <Property name="v1_public_insecure">
    V1 Public (asymmetric signing with RSA-PSS). **Deprecated** - use V4 instead.
  </Property>
  <Property name="v2_local">
    V2 Local (symmetric encryption with XChaCha20-Poly1305)
  </Property>
  <Property name="v2_public">
    V2 Public (asymmetric signing with Ed25519)
  </Property>
  <Property name="v3_local">
    V3 Local (symmetric encryption with AES-256-CTR + HMAC-SHA384)
  </Property>
  <Property name="v3_public">
    V3 Public (asymmetric signing with P-384 ECDSA)
  </Property>
  <Property name="v4_local">
    V4 Local (symmetric encryption with XChaCha20 + BLAKE2b). **Recommended**
  </Property>
  <Property name="v4_public">
    V4 Public (asymmetric signing with Ed25519). **Recommended**
  </Property>
</Properties>

### API Layer Features

<Properties>
  <Property name="core">
    Low-level API for maximum control. Enabled automatically with any version feature.
  </Property>
  <Property name="generic">
    Mid-level API with claim types and validation. Requires `core`.
  </Property>
  <Property name="prelude">
    High-level fluent API with `PasetoBuilder` and `PasetoParser`. Requires `generic`.
  </Property>
</Properties>

---

## Recommended Configurations

### Most Applications

For most applications, use V4 Local with the prelude layer:

```toml
[dependencies]
rusty_paseto = { version = "0.9", features = ["v4_local", "prelude"] }
```

### Public Tokens (Asymmetric)

For tokens that need to be verified without the signing key:

```toml
[dependencies]
rusty_paseto = { version = "0.9", features = ["v4_public", "prelude"] }
```

### Multiple Versions

If you need to support multiple versions (e.g., during migration):

```toml
[dependencies]
rusty_paseto = { version = "0.9", features = ["v3_local", "v4_local", "prelude"] }
```

### Core API Only

For low-level control without the builder/parser abstractions:

```toml
[dependencies]
rusty_paseto = { version = "0.9", features = ["v4_local"] }
```

---

## Version Selection Guide

<Note>
  **New projects should use V4.** V4 offers the best security and performance
  with modern cryptographic algorithms.
</Note>

| Version | Local Encryption | Public Signing | Notes |
|---------|------------------|----------------|-------|
| V1 | AES-256-CTR | RSA-PSS | Legacy, V1 Public deprecated |
| V2 | XChaCha20 | Ed25519 | Good, but V4 preferred |
| V3 | AES-256-CTR | P-384 ECDSA | NIST compliance |
| V4 | XChaCha20 + BLAKE2b | Ed25519 | **Recommended** |