keyloom 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- keyloom/__init__.py +357 -0
- keyloom/_cli.py +481 -0
- keyloom/_envelope.py +338 -0
- keyloom/_errors.py +36 -0
- keyloom/_files.py +389 -0
- keyloom/_formats.py +235 -0
- keyloom/_metadata.py +30 -0
- keyloom/_tree.py +236 -0
- keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/icon/pdf/keyloom-icon-color-on-transparent-none.pdf +0 -0
- keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/icon/png/keyloom-icon-color-on-transparent-none-2048px.png +0 -0
- keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/icon/svg/keyloom-icon-color-on-transparent-none.svg +44 -0
- keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/logo-horizontal/pdf/keyloom-logo-horizontal-color-on-transparent-none.pdf +0 -0
- keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/logo-horizontal/png/keyloom-logo-horizontal-color-on-transparent-none-2048px.png +0 -0
- keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/logo-horizontal/svg/keyloom-logo-horizontal-color-on-transparent-none.svg +45 -0
- keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/manifest.json +174 -0
- keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/wordmark/pdf/keyloom-wordmark-color-on-transparent-none.pdf +0 -0
- keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/wordmark/png/keyloom-wordmark-color-on-transparent-none-2048px.png +0 -0
- keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/wordmark/svg/keyloom-wordmark-color-on-transparent-none.svg +8 -0
- keyloom-0.1.0.data/data/share/keyloom/source/ADLaMDisplay-Regular.ttf +0 -0
- keyloom-0.1.0.data/data/share/keyloom/source/icon.svg +45 -0
- keyloom-0.1.0.data/data/share/keyloom/source/logo.svg +239 -0
- keyloom-0.1.0.data/data/share/keyloom/source/wordmark.svg +64 -0
- keyloom-0.1.0.dist-info/METADATA +31 -0
- keyloom-0.1.0.dist-info/RECORD +28 -0
- keyloom-0.1.0.dist-info/WHEEL +4 -0
- keyloom-0.1.0.dist-info/entry_points.txt +2 -0
- keyloom-0.1.0.dist-info/licenses/LICENSES/Apache-2.0.txt +73 -0
- keyloom-0.1.0.dist-info/licenses/LICENSES/OFL-1.1.txt +43 -0
keyloom/__init__.py
ADDED
|
@@ -0,0 +1,357 @@
|
|
|
1
|
+
# ------------------------------------------------------------------------------
|
|
2
|
+
# SPDX-FileCopyrightText: 2026 SEANERGYS Partners <https://seanergys.eu>
|
|
3
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
4
|
+
# ------------------------------------------------------------------------------
|
|
5
|
+
"""Field-level encryption for configuration files.
|
|
6
|
+
|
|
7
|
+
A configuration file marks each secret value with a wrapper,
|
|
8
|
+
`{"__keyloom__": "secret", "value": ...}`. keyloom encrypts the value
|
|
9
|
+
in place and leaves the rest of the file readable. A wrapper whose value is
|
|
10
|
+
`__keyloom__secret__` is a placeholder, whose secret is entered when the
|
|
11
|
+
file is encrypted.
|
|
12
|
+
Applications read such a file with `load`; tools write one with `store` or
|
|
13
|
+
encrypt one with `encrypt_file`.
|
|
14
|
+
|
|
15
|
+
Everything listed in `__all__` is defined here and is the whole public API.
|
|
16
|
+
The modules whose names start with an underscore are the implementation.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
import typing as _typing
|
|
22
|
+
|
|
23
|
+
import keyloom._envelope as _envelope
|
|
24
|
+
import keyloom._files as _files
|
|
25
|
+
import keyloom._metadata as _metadata
|
|
26
|
+
import keyloom._tree as _tree
|
|
27
|
+
|
|
28
|
+
# The annotations name typing and pathlib rather than private aliases, so that
|
|
29
|
+
# the API reference reads naturally; they are never evaluated at run time.
|
|
30
|
+
if _typing.TYPE_CHECKING:
|
|
31
|
+
import pathlib
|
|
32
|
+
import typing
|
|
33
|
+
|
|
34
|
+
__version__ = _metadata.__version__
|
|
35
|
+
"""The version of the installed keyloom package."""
|
|
36
|
+
|
|
37
|
+
# ------------------------------------------------------------------------------
|
|
38
|
+
# Errors
|
|
39
|
+
# ------------------------------------------------------------------------------
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class KeyloomError(Exception):
|
|
43
|
+
"""Base class of every failure a user can cause or fix.
|
|
44
|
+
|
|
45
|
+
Any other exception raised by keyloom is a bug.
|
|
46
|
+
"""
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class PasswordError(KeyloomError):
|
|
50
|
+
"""The vault password is empty or was not confirmed."""
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class ParseError(KeyloomError):
|
|
54
|
+
"""A file is not valid TOML, YAML, JSON or UTF-8."""
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
class UnsupportedFormat(KeyloomError):
|
|
58
|
+
"""A file extension is not supported, or the format cannot hold the data."""
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
class InvalidSecret(KeyloomError):
|
|
62
|
+
"""A `__keyloom__` wrapper is not a valid secret."""
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
class PlaintextSecret(KeyloomError):
|
|
66
|
+
"""A secret that must be encrypted holds plaintext."""
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class MissingSecret(KeyloomError):
|
|
70
|
+
"""A secret is a placeholder, or no value was entered for it."""
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class MalformedEnvelope(KeyloomError):
|
|
74
|
+
"""An encrypted value is not a valid envelope."""
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
class UnsupportedAlgorithm(KeyloomError):
|
|
78
|
+
"""An algorithm name is not known to this version of keyloom."""
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
class DecryptionError(KeyloomError):
|
|
82
|
+
"""The password is wrong or the encrypted value was modified."""
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
class UnsafeOutput(KeyloomError):
|
|
86
|
+
"""Writing the output would replace the encrypted input with plaintext."""
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
# ------------------------------------------------------------------------------
|
|
90
|
+
# Configuration in applications
|
|
91
|
+
# ------------------------------------------------------------------------------
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def load(*, path: str | pathlib.Path, password: str) -> typing.Any:
|
|
95
|
+
"""Read a configuration file and return it with its secrets decrypted.
|
|
96
|
+
|
|
97
|
+
The result is made of plain dicts, lists and scalars, with every secret
|
|
98
|
+
wrapper replaced by its value.
|
|
99
|
+
|
|
100
|
+
@param path TOML, YAML or JSON file, chosen by its extension.
|
|
101
|
+
|
|
102
|
+
@param password The vault password.
|
|
103
|
+
|
|
104
|
+
@return The decrypted configuration.
|
|
105
|
+
|
|
106
|
+
@throws PlaintextSecret A secret in the file is not encrypted.
|
|
107
|
+
|
|
108
|
+
@throws MissingSecret A secret in the file is a placeholder.
|
|
109
|
+
|
|
110
|
+
@throws DecryptionError The password is wrong or a value was modified.
|
|
111
|
+
"""
|
|
112
|
+
return _files.load(path=path, password=password)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def store(
|
|
116
|
+
*,
|
|
117
|
+
path: str | pathlib.Path,
|
|
118
|
+
data: typing.Any,
|
|
119
|
+
password: str,
|
|
120
|
+
algorithm: str,
|
|
121
|
+
) -> int:
|
|
122
|
+
"""Write data to a configuration file with its secrets encrypted.
|
|
123
|
+
|
|
124
|
+
Mark each secret in `data` with `secret`. The file is written fresh and
|
|
125
|
+
atomically: comments of an existing file are not kept, but its
|
|
126
|
+
permissions are, and a new file gets mode 0600. `data` itself is not
|
|
127
|
+
changed.
|
|
128
|
+
|
|
129
|
+
@param path TOML, YAML or JSON file, chosen by its extension.
|
|
130
|
+
|
|
131
|
+
@param data Dicts, lists and scalars, with secrets marked by `secret`.
|
|
132
|
+
|
|
133
|
+
@param password The vault password.
|
|
134
|
+
|
|
135
|
+
@param algorithm The algorithm for the secrets, from `algorithms`.
|
|
136
|
+
|
|
137
|
+
@return The number of secrets encrypted.
|
|
138
|
+
|
|
139
|
+
@throws MissingSecret A secret in `data` is a placeholder.
|
|
140
|
+
|
|
141
|
+
@throws UnsupportedFormat The file format cannot hold the data.
|
|
142
|
+
"""
|
|
143
|
+
return _files.store(
|
|
144
|
+
path=path, data=data, password=password, algorithm=algorithm
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def secret(*, value: typing.Any) -> dict[str, typing.Any]:
|
|
149
|
+
"""Mark a value as a secret, for the data passed to `store`.
|
|
150
|
+
|
|
151
|
+
@param value A string, number, boolean or None.
|
|
152
|
+
|
|
153
|
+
@return The wrapper `{"__keyloom__": "secret", "value": value}`.
|
|
154
|
+
"""
|
|
155
|
+
return _tree.secret(value=value)
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
# ------------------------------------------------------------------------------
|
|
159
|
+
# Files
|
|
160
|
+
# ------------------------------------------------------------------------------
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def encrypt_file(
|
|
164
|
+
*,
|
|
165
|
+
input_path: str | pathlib.Path,
|
|
166
|
+
output_path: str | pathlib.Path,
|
|
167
|
+
password: str,
|
|
168
|
+
algorithm: str,
|
|
169
|
+
prompt: typing.Callable[[str], typing.Any] | None,
|
|
170
|
+
) -> int:
|
|
171
|
+
"""Encrypt the plaintext secrets and placeholders of a configuration file.
|
|
172
|
+
|
|
173
|
+
Pass the same path twice to encrypt in place. The output is written
|
|
174
|
+
atomically and keeps the permissions of a file it replaces. A file
|
|
175
|
+
without plaintext secrets or placeholders is not rewritten in place, so
|
|
176
|
+
its formatting stays exactly as it was. Existing envelopes keep their
|
|
177
|
+
algorithm.
|
|
178
|
+
|
|
179
|
+
Existing envelopes are checked against `password` before `prompt` is
|
|
180
|
+
called, and every value is encrypted only after all placeholders have
|
|
181
|
+
one, so nothing is written if any step fails.
|
|
182
|
+
|
|
183
|
+
@param input_path The file to read.
|
|
184
|
+
|
|
185
|
+
@param output_path The file to write; may be `input_path`.
|
|
186
|
+
|
|
187
|
+
@param password The vault password, also checked against existing
|
|
188
|
+
envelopes.
|
|
189
|
+
|
|
190
|
+
@param algorithm The algorithm for newly encrypted secrets.
|
|
191
|
+
|
|
192
|
+
@param prompt Called once for every placeholder, in document order, with
|
|
193
|
+
its location such as `git."gitlab.example.org".token`; returns its
|
|
194
|
+
value. None makes a placeholder an error.
|
|
195
|
+
|
|
196
|
+
@return The number of secrets encrypted, placeholders included.
|
|
197
|
+
|
|
198
|
+
@throws DecryptionError An existing envelope uses another password.
|
|
199
|
+
|
|
200
|
+
@throws MissingSecret The file has a placeholder and `prompt` is None.
|
|
201
|
+
"""
|
|
202
|
+
return _files.encrypt_file(
|
|
203
|
+
input_path=input_path,
|
|
204
|
+
output_path=output_path,
|
|
205
|
+
password=password,
|
|
206
|
+
algorithm=algorithm,
|
|
207
|
+
prompt=prompt,
|
|
208
|
+
)
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def decrypt_file(
|
|
212
|
+
*,
|
|
213
|
+
input_path: str | pathlib.Path,
|
|
214
|
+
output_path: str | pathlib.Path,
|
|
215
|
+
password: str,
|
|
216
|
+
) -> None:
|
|
217
|
+
"""Decrypt the secrets of a configuration file into a plaintext file.
|
|
218
|
+
|
|
219
|
+
The wrappers are kept, so `encrypt_file` turns the output back into an
|
|
220
|
+
encrypted file. The output is written atomically with mode 0600.
|
|
221
|
+
|
|
222
|
+
@param input_path The encrypted file.
|
|
223
|
+
|
|
224
|
+
@param output_path The plaintext file; must not be `input_path`.
|
|
225
|
+
|
|
226
|
+
@param password The vault password.
|
|
227
|
+
|
|
228
|
+
@throws UnsafeOutput The output is the input file, directly or through a
|
|
229
|
+
link.
|
|
230
|
+
|
|
231
|
+
@throws PlaintextSecret A secret in the file is not encrypted.
|
|
232
|
+
|
|
233
|
+
@throws MissingSecret A secret in the file is a placeholder.
|
|
234
|
+
"""
|
|
235
|
+
_files.decrypt_file(
|
|
236
|
+
input_path=input_path, output_path=output_path, password=password
|
|
237
|
+
)
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
def reencrypt_file(
|
|
241
|
+
*,
|
|
242
|
+
input_path: str | pathlib.Path,
|
|
243
|
+
output_path: str | pathlib.Path,
|
|
244
|
+
password: str,
|
|
245
|
+
new_password: str,
|
|
246
|
+
algorithm: str,
|
|
247
|
+
) -> int:
|
|
248
|
+
"""Encrypt every secret of a file again, without writing plaintext.
|
|
249
|
+
|
|
250
|
+
Every secret is decrypted with `password` and encrypted with
|
|
251
|
+
`new_password` and `algorithm`, in memory. Pass the same password twice
|
|
252
|
+
to change only the algorithm, and the same path twice to work in place.
|
|
253
|
+
|
|
254
|
+
@param input_path The encrypted file.
|
|
255
|
+
|
|
256
|
+
@param output_path The file to write; may be `input_path`.
|
|
257
|
+
|
|
258
|
+
@param password The current vault password.
|
|
259
|
+
|
|
260
|
+
@param new_password The vault password to encrypt with.
|
|
261
|
+
|
|
262
|
+
@param algorithm The algorithm to encrypt with.
|
|
263
|
+
|
|
264
|
+
@return The number of secrets encrypted again.
|
|
265
|
+
|
|
266
|
+
@throws PlaintextSecret A secret in the file is not encrypted.
|
|
267
|
+
|
|
268
|
+
@throws MissingSecret A secret in the file is a placeholder.
|
|
269
|
+
"""
|
|
270
|
+
return _files.reencrypt_file(
|
|
271
|
+
input_path=input_path,
|
|
272
|
+
output_path=output_path,
|
|
273
|
+
password=password,
|
|
274
|
+
new_password=new_password,
|
|
275
|
+
algorithm=algorithm,
|
|
276
|
+
)
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
# ------------------------------------------------------------------------------
|
|
280
|
+
# Single values
|
|
281
|
+
# ------------------------------------------------------------------------------
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
def encrypt_value(*, value: typing.Any, password: str, algorithm: str) -> str:
|
|
285
|
+
"""Encrypt one value into a self-contained envelope string.
|
|
286
|
+
|
|
287
|
+
The envelope names its algorithm and carries its own salt and nonce, so
|
|
288
|
+
it can be decrypted wherever it is copied.
|
|
289
|
+
|
|
290
|
+
@param value A string, number, boolean or None.
|
|
291
|
+
|
|
292
|
+
@param password The vault password.
|
|
293
|
+
|
|
294
|
+
@param algorithm The algorithm, from `algorithms`.
|
|
295
|
+
|
|
296
|
+
@return An envelope such as `$KEYLOOM;1;argon2;s=...;n=...;c=...`.
|
|
297
|
+
|
|
298
|
+
@throws InvalidSecret The value is not a scalar, or is a string that
|
|
299
|
+
starts with `$KEYLOOM;`.
|
|
300
|
+
|
|
301
|
+
@throws UnsupportedAlgorithm The algorithm is not known.
|
|
302
|
+
"""
|
|
303
|
+
return _envelope.encrypt_value(
|
|
304
|
+
value=value, password=password, algorithm=algorithm
|
|
305
|
+
)
|
|
306
|
+
|
|
307
|
+
|
|
308
|
+
def decrypt_value(*, value: str, password: str) -> typing.Any:
|
|
309
|
+
"""Authenticate and decrypt one envelope string.
|
|
310
|
+
|
|
311
|
+
@param value The envelope.
|
|
312
|
+
|
|
313
|
+
@param password The vault password.
|
|
314
|
+
|
|
315
|
+
@return The original string, number, boolean or None.
|
|
316
|
+
|
|
317
|
+
@throws DecryptionError The password is wrong or the value was modified.
|
|
318
|
+
|
|
319
|
+
@throws MalformedEnvelope The value is not a valid envelope.
|
|
320
|
+
"""
|
|
321
|
+
return _envelope.decrypt_value(value=value, password=password)
|
|
322
|
+
|
|
323
|
+
|
|
324
|
+
def algorithms() -> tuple[str, ...]:
|
|
325
|
+
"""Return the names of the supported algorithms.
|
|
326
|
+
|
|
327
|
+
An algorithm name fixes every cryptographic parameter; new parameters
|
|
328
|
+
come as a new name.
|
|
329
|
+
|
|
330
|
+
@return The names, such as `("argon2",)`.
|
|
331
|
+
"""
|
|
332
|
+
return _envelope.algorithms()
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
__all__ = [
|
|
336
|
+
"DecryptionError",
|
|
337
|
+
"InvalidSecret",
|
|
338
|
+
"KeyloomError",
|
|
339
|
+
"MalformedEnvelope",
|
|
340
|
+
"MissingSecret",
|
|
341
|
+
"ParseError",
|
|
342
|
+
"PasswordError",
|
|
343
|
+
"PlaintextSecret",
|
|
344
|
+
"UnsafeOutput",
|
|
345
|
+
"UnsupportedAlgorithm",
|
|
346
|
+
"UnsupportedFormat",
|
|
347
|
+
"__version__",
|
|
348
|
+
"algorithms",
|
|
349
|
+
"decrypt_file",
|
|
350
|
+
"decrypt_value",
|
|
351
|
+
"encrypt_file",
|
|
352
|
+
"encrypt_value",
|
|
353
|
+
"load",
|
|
354
|
+
"reencrypt_file",
|
|
355
|
+
"secret",
|
|
356
|
+
"store",
|
|
357
|
+
]
|