@@ -9,17 +9,19 @@ SafeBox can help you [migrate](docs/MIGRATION.md) easily using the same `SharedP
9
9
10
10
## Why SafeBox?
11
11
12
- | Feature | SafeBox | EncryptedSharedPreferences |
12
+ | Feature | SafeBox v1.1.0 | EncryptedSharedPreferences |
13
13
| ---------------------| -----------------------------------| -------------------------------------------|
14
- | Initialization Time | ** 0.35ms ** (* 110x faster* ) | 38.7ms |
14
+ | Initialization Time | ** 0.38ms ** (* 100x faster* ) | 38.7ms |
15
15
| Storage Format | Memory-mapped binary file | XML-based per-entry |
16
16
| Encryption Method | ChaCha20-Poly1305 (keys & values) | AES-SIV for keys, AES-GCM for values |
17
17
| Key Security | Android Keystore-backed AES-GCM | Android Keystore MasterKey (* deprecated* ) |
18
- | Customization | Pluggable cipher/key providers | Tightly coupled |
18
+ | Customization | Pluggable cipher providers | Tightly coupled |
19
19
20
20
SafeBox uses ** deterministic encryption** for reference keys (for fast lookup) and ** non-deterministic encryption** for values (for strong security). Both powered by a single ChaCha20 key protected via AES-GCM and stored securely.
21
21
22
- ### SafeBox Key Derivation & Encryption Flow
22
+ <details >
23
+
24
+ <summary >🔑 SafeBox Key Derivation & Encryption Flow</summary >
23
25
24
26
```
25
27
[Android Keystore-backed AES-GCM Key]
@@ -41,40 +43,6 @@ Compared to EncryptedSharedPreferences:
41
43
42
44
```
43
45
44
- ## Performance Benchmarks
45
-
46
- Average times measured over ** 100 samples** on an emulator:
47
-
48
- ![ Read Performance] ( docs/charts/read_performance_chart.png )
49
-
50
- ![ Write Performance] ( docs/charts/write_performance_chart.png )
51
-
52
- ![ Write then Commit Performance] ( docs/charts/write_commit_performance_chart.png )
53
-
54
- <details >
55
-
56
- <summary >📊 Comparison Tables</summary >
57
-
58
- | Operation | SafeBox | EncryptedSharedPreferences |
59
- | ------------------------------| ------------| ----------------------------|
60
- | Write 1 entry then commit | ** 0.55ms** | 1.31ms (* 138% slower* ) |
61
- | Read 1 entry | ** 0.39ms** | 0.50ms (* 28% slower* ) |
62
- | Write 3 entries then commit | ** 1.25ms** | 2.16ms (* 73% slower* ) |
63
- | Read 3 entries | ** 0.94ms** | 1.27ms (* 35% slower* ) |
64
- | Write 5 entries then commit | ** 2.33ms** | 3.32ms (* 42% slower* ) |
65
- | Read 5 entries | ** 1.37ms** | 2.25ms (* 64% slower* ) |
66
- | Write 10 entries then commit | ** 4.73ms** | 6.28ms (* 33% slower* ) |
67
- | Read 10 entries | ** 3.29ms** | 4.07ms (* 24% slower* ) |
68
-
69
- Even on ** multiple single commits** , SafeBox remains faster:
70
-
71
- | Operation | SafeBox | EncryptedSharedPreferences |
72
- | ------------------------------| -------------| ----------------------------|
73
- | Write and commit 3 entries | ** 1.94ms** | 4.9ms (* 152% slower* ) |
74
- | Write and commit 5 entries | ** 2.84ms** | 6.91ms (* 143% slower* ) |
75
- | Write and commit 10 entries | ** 5.47ms** | 11.27ms (* 106% slower* ) |
76
- | Write and commit 100 entries | ** 33.19ms** | 71.34ms (* 115% slower* ) |
77
-
78
46
</details >
79
47
80
48
## Installation
@@ -175,10 +143,10 @@ Manually add listeners by file name:
175
143
``` kotlin
176
144
val listener = SafeBoxStateListener { state ->
177
145
when (state) {
178
- STARTING -> trackStart() // Loading data into memory
179
- IDLE -> trackIdle() // No active operations
180
- WRITING -> trackWrite() // Writing to disk
181
- CLOSED -> trackClose() // Instance is no longer usable
146
+ STARTING -> doSomething() // Loading data into memory
147
+ IDLE -> doSomething() // No active operations
148
+ WRITING -> doSomething() // Writing to disk
149
+ CLOSED -> doSomething() // Instance is no longer usable
182
150
}
183
151
}
184
152
SafeBoxGlobalStateObserver .addListener(PREF_FILE_NAME , listener)
@@ -202,6 +170,75 @@ SafeBox is a drop-in replacement for `EncryptedSharedPreferences`.
202
170
203
171
➡️ [ Read the Migration Guide] ( docs/MIGRATION.md )
204
172
173
+ ## Performance Benchmarks
174
+
175
+ Average times measured over ** 100 samples** on an emulator:
176
+
177
+ <details open >
178
+
179
+ <summary >📊 v1.1.0 Benchmark</summary >
180
+
181
+ ![ Get Performance] ( docs/charts/v1_1_get_performance_chart.png )
182
+
183
+ ![ Put Performance] ( docs/charts/v1_1_put_performance_chart.png )
184
+
185
+ ![ Put then Commit Performance] ( docs/charts/v1_1_put_and_commit_performance_chart.png )
186
+
187
+ | Operation | SafeBox v1.1.0 | EncryptedSharedPreferences |
188
+ | -----------------------------| ----------------| ----------------------------|
189
+ | Initialization | ** 0.38ms** | 38.7ms (* 10,079% slower* ) |
190
+ | Get 1 entry | ** 0.33ms** | 0.50ms (* 52% slower* ) |
191
+ | Get 3 entries | ** 0.94ms** | 1.27ms (* 35% slower* ) |
192
+ | Get 5 entries | ** 1.56ms** | 2.25ms (* 44% slower* ) |
193
+ | Get 10 entries | ** 3.06ms** | 4.07ms (* 33% slower* ) |
194
+ | Put 1 entry, then commit | ** 0.49ms** | 1.31ms (* 167% slower* ) |
195
+ | Put 3 entries, then commit | ** 1.34ms** | 2.16ms (* 61% slower* ) |
196
+ | Put 5 entries, then commit | ** 2.36ms** | 3.32ms (* 41% slower* ) |
197
+ | Put 10 entries, then commit | ** 4.20ms** | 6.28ms (* 50% slower* ) |
198
+
199
+ Even on ** multiple single commits** , SafeBox remains faster:
200
+
201
+ | Operation | SafeBox v1.1.0 | EncryptedSharedPreferences |
202
+ | ------------------------------| ----------------| ----------------------------|
203
+ | Commit 3 single entries | ** 1.50ms** | 4.90ms (* 227% slower* ) |
204
+ | Commit 5 single entries | ** 2.39ms** | 6.91ms (* 189% slower* ) |
205
+ | Commit 10 single entries | ** 5.07ms** | 11.27ms (* 122% slower* ) |
206
+ | Commit 100 single entries | ** 38.12ms** | 71.34ms (* 87% slower* ) |
207
+
208
+ </details >
209
+
210
+ <details >
211
+
212
+ <summary >📊 v1.0.0 Benchmark</summary >
213
+
214
+ ![ Get Performance] ( docs/charts/read_performance_chart.png )
215
+
216
+ ![ Put Performance] ( docs/charts/write_performance_chart.png )
217
+
218
+ ![ Put then Commit Performance] ( docs/charts/write_commit_performance_chart.png )
219
+
220
+ | Operation | SafeBox v1.0.0 | EncryptedSharedPreferences |
221
+ | -----------------------------| ----------------| ----------------------------|
222
+ | Get 1 entry | ** 0.39ms** | 0.50ms (* 28% slower* ) |
223
+ | Get 3 entries | ** 0.94ms** | 1.27ms (* 35% slower* ) |
224
+ | Get 5 entries | ** 1.37ms** | 2.25ms (* 64% slower* ) |
225
+ | Get 10 entries | ** 3.29ms** | 4.07ms (* 24% slower* ) |
226
+ | Put 1 entry, then commit | ** 0.55ms** | 1.31ms (* 138% slower* ) |
227
+ | Put 3 entries, then commit | ** 1.25ms** | 2.16ms (* 73% slower* ) |
228
+ | Put 5 entries, then commit | ** 2.33ms** | 3.32ms (* 42% slower* ) |
229
+ | Put 10 entries, then commit | ** 4.73ms** | 6.28ms (* 33% slower* ) |
230
+
231
+ Even on ** multiple single commits** , SafeBox remains faster:
232
+
233
+ | Operation | SafeBox v1.0.0 | EncryptedSharedPreferences |
234
+ | ------------------------------| ----------------| ----------------------------|
235
+ | Commit 3 single entries | ** 1.94ms** | 4.90ms (* 152% slower* ) |
236
+ | Commit 5 single entries | ** 2.84ms** | 6.91ms (* 143% slower* ) |
237
+ | Commit 10 single entries | ** 5.47ms** | 11.27ms (* 106% slower* ) |
238
+ | Commit 100 single entries | ** 33.19ms** | 71.34ms (* 115% slower* ) |
239
+
240
+ </details >
241
+
205
242
## Contributing
206
243
207
244
See [ CONTRIBUTING.md] ( CONTRIBUTING.md ) for setup, formatting, testing, and PR guidelines.
0 commit comments