fscryptography 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.
- fscryptography/__init__.py +41 -0
- fscryptography/_directory.py +99 -0
- fscryptography/_filesystem.py +671 -0
- fscryptography/_journal.py +493 -0
- fscryptography/_master_key.py +294 -0
- fscryptography/crypto.py +89 -0
- fscryptography/errors.py +52 -0
- fscryptography/file_format.py +178 -0
- fscryptography/names/__init__.py +16 -0
- fscryptography/names/codec.py +116 -0
- fscryptography/names/tink_backend.py +28 -0
- fscryptography/names/validation.py +84 -0
- fscryptography/py.typed +0 -0
- fscryptography-0.1.0.dist-info/METADATA +168 -0
- fscryptography-0.1.0.dist-info/RECORD +18 -0
- fscryptography-0.1.0.dist-info/WHEEL +5 -0
- fscryptography-0.1.0.dist-info/licenses/LICENSE +25 -0
- fscryptography-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
"""Production MasterKey v1.0 container and Tink keyset integration."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import base64
|
|
6
|
+
import binascii
|
|
7
|
+
import os
|
|
8
|
+
import struct
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
|
|
11
|
+
import tink
|
|
12
|
+
from argon2.low_level import Type, hash_secret_raw
|
|
13
|
+
from cryptography.exceptions import InvalidTag
|
|
14
|
+
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
|
|
15
|
+
from tink import aead, secret_key_access, streaming_aead
|
|
16
|
+
|
|
17
|
+
from .errors import (
|
|
18
|
+
AuthenticationError,
|
|
19
|
+
BackendError,
|
|
20
|
+
FormatError,
|
|
21
|
+
KeyDerivationError,
|
|
22
|
+
UnsupportedFormatVersionError,
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
_MAGIC = b"FSCRKEY\0"
|
|
26
|
+
_MAJOR = 1
|
|
27
|
+
_MINOR = 0
|
|
28
|
+
_SCHEMA = 1
|
|
29
|
+
_MODE_RANDOM = 0
|
|
30
|
+
_MODE_PASSWORD = 1
|
|
31
|
+
_HEADER_RANDOM = 20
|
|
32
|
+
_HEADER_PASSWORD = 61
|
|
33
|
+
_MAX_KEYSET = 32 * 1024
|
|
34
|
+
_MAX_LOGICAL_PAYLOAD = 128 * 1024
|
|
35
|
+
_MAX_BINARY = 131_149
|
|
36
|
+
_MAX_BASE64 = 174_868
|
|
37
|
+
_ARGON2_VERSION = 19
|
|
38
|
+
_ARGON2_MEMORY_KIB = 65_536
|
|
39
|
+
_ARGON2_TIME = 3
|
|
40
|
+
_ARGON2_PARALLELISM = 1
|
|
41
|
+
_SALT_LENGTH = 16
|
|
42
|
+
_NONCE_LENGTH = 12
|
|
43
|
+
_TAG_LENGTH = 16
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@dataclass(frozen=True, slots=True)
|
|
47
|
+
class _KeyMaterial:
|
|
48
|
+
content: streaming_aead.StreamingAead
|
|
49
|
+
names: aead.Aead
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def _password_bytes(password: str) -> bytes:
|
|
53
|
+
if not isinstance(password, str):
|
|
54
|
+
raise TypeError("password must be str")
|
|
55
|
+
try:
|
|
56
|
+
value = password.encode("utf-8", errors="strict")
|
|
57
|
+
except UnicodeEncodeError as exc:
|
|
58
|
+
raise ValueError("password must be valid UTF-8 text") from exc
|
|
59
|
+
if not value or len(value) > 1024:
|
|
60
|
+
raise ValueError("password must contain 1 to 1024 UTF-8 bytes")
|
|
61
|
+
return value
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def _derive_wrapping_key(password: bytes, salt: bytes) -> bytes:
|
|
65
|
+
try:
|
|
66
|
+
return hash_secret_raw(
|
|
67
|
+
secret=password,
|
|
68
|
+
salt=salt,
|
|
69
|
+
time_cost=_ARGON2_TIME,
|
|
70
|
+
memory_cost=_ARGON2_MEMORY_KIB,
|
|
71
|
+
parallelism=_ARGON2_PARALLELISM,
|
|
72
|
+
hash_len=32,
|
|
73
|
+
type=Type.ID,
|
|
74
|
+
version=_ARGON2_VERSION,
|
|
75
|
+
)
|
|
76
|
+
except Exception as exc:
|
|
77
|
+
raise KeyDerivationError("MasterKey key derivation failed") from exc
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _serialize_keyset(handle: tink.KeysetHandle) -> bytes:
|
|
81
|
+
try:
|
|
82
|
+
return tink.proto_keyset_format.serialize(
|
|
83
|
+
handle, secret_key_access.TOKEN
|
|
84
|
+
)
|
|
85
|
+
except Exception as exc:
|
|
86
|
+
raise BackendError("unable to serialize MasterKey keyset") from exc
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def _new_keysets() -> tuple[bytes, bytes]:
|
|
90
|
+
try:
|
|
91
|
+
streaming_aead.register()
|
|
92
|
+
aead.register()
|
|
93
|
+
content_template = getattr(
|
|
94
|
+
streaming_aead.streaming_aead_key_templates,
|
|
95
|
+
"AES256_GCM_HKDF_1MB",
|
|
96
|
+
)
|
|
97
|
+
names_template = aead.aead_key_templates.AES256_GCM
|
|
98
|
+
content = _serialize_keyset(tink.new_keyset_handle(content_template))
|
|
99
|
+
names = _serialize_keyset(tink.new_keyset_handle(names_template))
|
|
100
|
+
except BackendError:
|
|
101
|
+
raise
|
|
102
|
+
except Exception as exc:
|
|
103
|
+
raise BackendError("unable to generate MasterKey keysets") from exc
|
|
104
|
+
return content, names
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def _frame_payload(content_keyset: bytes, names_keyset: bytes) -> bytes:
|
|
108
|
+
if not content_keyset or not names_keyset:
|
|
109
|
+
raise BackendError("Tink generated an empty keyset")
|
|
110
|
+
if len(content_keyset) > _MAX_KEYSET or len(names_keyset) > _MAX_KEYSET:
|
|
111
|
+
raise BackendError("Tink keyset exceeds the MasterKey size limit")
|
|
112
|
+
payload = (
|
|
113
|
+
struct.pack(">I", len(content_keyset))
|
|
114
|
+
+ content_keyset
|
|
115
|
+
+ struct.pack(">I", len(names_keyset))
|
|
116
|
+
+ names_keyset
|
|
117
|
+
)
|
|
118
|
+
if len(payload) > _MAX_LOGICAL_PAYLOAD:
|
|
119
|
+
raise BackendError("MasterKey payload exceeds the size limit")
|
|
120
|
+
return payload
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def _split_payload(payload: bytes) -> tuple[bytes, bytes]:
|
|
124
|
+
if not isinstance(payload, bytes) or len(payload) < 8:
|
|
125
|
+
raise FormatError("MasterKey payload framing is truncated")
|
|
126
|
+
first_length = struct.unpack_from(">I", payload, 0)[0]
|
|
127
|
+
if first_length == 0 or first_length > _MAX_KEYSET:
|
|
128
|
+
raise FormatError("invalid content keyset length")
|
|
129
|
+
first_end = 4 + first_length
|
|
130
|
+
if len(payload) < first_end + 4:
|
|
131
|
+
raise FormatError("MasterKey name keyset length is missing")
|
|
132
|
+
second_length = struct.unpack_from(">I", payload, first_end)[0]
|
|
133
|
+
if second_length == 0 or second_length > _MAX_KEYSET:
|
|
134
|
+
raise FormatError("invalid name keyset length")
|
|
135
|
+
second_start = first_end + 4
|
|
136
|
+
second_end = second_start + second_length
|
|
137
|
+
if second_end != len(payload):
|
|
138
|
+
raise FormatError("MasterKey payload has truncated or trailing data")
|
|
139
|
+
return payload[4:first_end], payload[second_start:second_end]
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def _restore_key_material(content_keyset: bytes, names_keyset: bytes) -> _KeyMaterial:
|
|
143
|
+
try:
|
|
144
|
+
streaming_aead.register()
|
|
145
|
+
aead.register()
|
|
146
|
+
content_handle = tink.proto_keyset_format.parse(
|
|
147
|
+
content_keyset, secret_key_access.TOKEN
|
|
148
|
+
)
|
|
149
|
+
names_handle = tink.proto_keyset_format.parse(
|
|
150
|
+
names_keyset, secret_key_access.TOKEN
|
|
151
|
+
)
|
|
152
|
+
content = content_handle.primitive(streaming_aead.StreamingAead)
|
|
153
|
+
names = names_handle.primitive(aead.Aead)
|
|
154
|
+
except Exception as exc:
|
|
155
|
+
raise FormatError("MasterKey contains invalid or unexpected Tink keysets") from exc
|
|
156
|
+
return _KeyMaterial(content=content, names=names)
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def generate_master_key(*, password: str | None = None) -> str:
|
|
160
|
+
"""Generate an opaque Base64 MasterKey v1.0 container."""
|
|
161
|
+
password_raw = None if password is None else _password_bytes(password)
|
|
162
|
+
content_keyset, names_keyset = _new_keysets()
|
|
163
|
+
logical_payload = _frame_payload(content_keyset, names_keyset)
|
|
164
|
+
|
|
165
|
+
if password is None:
|
|
166
|
+
header = (
|
|
167
|
+
_MAGIC
|
|
168
|
+
+ bytes((_MAJOR, _MINOR, _MODE_RANDOM, _SCHEMA))
|
|
169
|
+
+ struct.pack(">HHI", 0, _HEADER_RANDOM, len(logical_payload))
|
|
170
|
+
)
|
|
171
|
+
binary = header + logical_payload
|
|
172
|
+
else:
|
|
173
|
+
salt = os.urandom(_SALT_LENGTH)
|
|
174
|
+
nonce = os.urandom(_NONCE_LENGTH)
|
|
175
|
+
header = (
|
|
176
|
+
_MAGIC
|
|
177
|
+
+ bytes((_MAJOR, _MINOR, _MODE_PASSWORD, _SCHEMA))
|
|
178
|
+
+ struct.pack(">HHI", 0, _HEADER_PASSWORD, len(logical_payload) + _TAG_LENGTH)
|
|
179
|
+
+ bytes((1, _ARGON2_VERSION))
|
|
180
|
+
+ struct.pack(">IIH", _ARGON2_MEMORY_KIB, _ARGON2_TIME, _ARGON2_PARALLELISM)
|
|
181
|
+
+ salt
|
|
182
|
+
+ bytes((1,))
|
|
183
|
+
+ nonce
|
|
184
|
+
)
|
|
185
|
+
wrapping_key = _derive_wrapping_key(password_raw, salt)
|
|
186
|
+
try:
|
|
187
|
+
encrypted_payload = AESGCM(wrapping_key).encrypt(
|
|
188
|
+
nonce, logical_payload, header
|
|
189
|
+
)
|
|
190
|
+
except Exception as exc:
|
|
191
|
+
raise BackendError("MasterKey payload protection failed") from exc
|
|
192
|
+
binary = header + encrypted_payload
|
|
193
|
+
|
|
194
|
+
if len(binary) > _MAX_BINARY:
|
|
195
|
+
raise BackendError("generated MasterKey exceeds the binary size limit")
|
|
196
|
+
return base64.b64encode(binary).decode("ascii")
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def _decode_master_key(master_key: str) -> bytes:
|
|
200
|
+
"""Decode and validate the public Base64 representation."""
|
|
201
|
+
if not isinstance(master_key, str):
|
|
202
|
+
raise TypeError("master_key must be str")
|
|
203
|
+
try:
|
|
204
|
+
encoded = master_key.encode("ascii", errors="strict")
|
|
205
|
+
except UnicodeEncodeError as exc:
|
|
206
|
+
raise FormatError("MasterKey must be standard Base64 ASCII") from exc
|
|
207
|
+
if not encoded or len(encoded) > _MAX_BASE64:
|
|
208
|
+
raise FormatError("MasterKey Base64 length is invalid")
|
|
209
|
+
try:
|
|
210
|
+
binary = base64.b64decode(encoded, validate=True)
|
|
211
|
+
except (binascii.Error, ValueError) as exc:
|
|
212
|
+
raise FormatError("MasterKey is not valid Base64") from exc
|
|
213
|
+
if base64.b64encode(binary) != encoded:
|
|
214
|
+
raise FormatError("MasterKey Base64 is not canonical")
|
|
215
|
+
return binary
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def _open_master_key_bytes(binary: bytes, *, password: str | None = None) -> _KeyMaterial:
|
|
219
|
+
"""Open an already-decoded MasterKey container."""
|
|
220
|
+
if not isinstance(binary, bytes):
|
|
221
|
+
raise TypeError("binary MasterKey must be bytes")
|
|
222
|
+
if len(binary) > _MAX_BINARY or len(binary) < _HEADER_RANDOM:
|
|
223
|
+
raise FormatError("MasterKey binary size is invalid")
|
|
224
|
+
if binary[:8] != _MAGIC:
|
|
225
|
+
raise FormatError("MasterKey magic is invalid")
|
|
226
|
+
if binary[8] != _MAJOR or binary[9] != _MINOR:
|
|
227
|
+
raise UnsupportedFormatVersionError("unsupported MasterKey version")
|
|
228
|
+
|
|
229
|
+
mode, schema = binary[10], binary[11]
|
|
230
|
+
if mode not in (_MODE_RANDOM, _MODE_PASSWORD) or schema != _SCHEMA:
|
|
231
|
+
raise FormatError("unsupported MasterKey mode or payload schema")
|
|
232
|
+
flags, header_length, payload_length = struct.unpack_from(">HHI", binary, 12)
|
|
233
|
+
if flags != 0:
|
|
234
|
+
raise FormatError("MasterKey reserved flags must be zero")
|
|
235
|
+
expected_header = _HEADER_RANDOM if mode == _MODE_RANDOM else _HEADER_PASSWORD
|
|
236
|
+
payload_limit = (
|
|
237
|
+
_MAX_LOGICAL_PAYLOAD
|
|
238
|
+
if mode == _MODE_RANDOM
|
|
239
|
+
else _MAX_LOGICAL_PAYLOAD + _TAG_LENGTH
|
|
240
|
+
)
|
|
241
|
+
if header_length != expected_header:
|
|
242
|
+
raise FormatError("MasterKey header length is invalid")
|
|
243
|
+
if payload_length > payload_limit:
|
|
244
|
+
raise FormatError("MasterKey payload exceeds the size limit")
|
|
245
|
+
if mode == _MODE_PASSWORD and payload_length < _TAG_LENGTH:
|
|
246
|
+
raise FormatError("protected MasterKey payload is shorter than its AEAD tag")
|
|
247
|
+
if len(binary) != header_length + payload_length:
|
|
248
|
+
raise FormatError("MasterKey total length does not match its header")
|
|
249
|
+
|
|
250
|
+
header = binary[:header_length]
|
|
251
|
+
payload = binary[header_length:]
|
|
252
|
+
if mode == _MODE_RANDOM:
|
|
253
|
+
if password is not None:
|
|
254
|
+
raise ValueError("password must not be supplied for an unprotected MasterKey")
|
|
255
|
+
logical_payload = payload
|
|
256
|
+
else:
|
|
257
|
+
if password is None:
|
|
258
|
+
raise ValueError("password is required for this MasterKey")
|
|
259
|
+
password_raw = _password_bytes(password)
|
|
260
|
+
if (
|
|
261
|
+
header[20] != 1
|
|
262
|
+
or header[21] != _ARGON2_VERSION
|
|
263
|
+
or struct.unpack_from(">I", header, 22)[0] != _ARGON2_MEMORY_KIB
|
|
264
|
+
or struct.unpack_from(">I", header, 26)[0] != _ARGON2_TIME
|
|
265
|
+
or struct.unpack_from(">H", header, 30)[0] != _ARGON2_PARALLELISM
|
|
266
|
+
or header[48] != 1
|
|
267
|
+
):
|
|
268
|
+
raise FormatError("MasterKey KDF or wrapping profile is unsupported")
|
|
269
|
+
salt = header[32:48]
|
|
270
|
+
nonce = header[49:61]
|
|
271
|
+
if len(salt) != _SALT_LENGTH or len(nonce) != _NONCE_LENGTH:
|
|
272
|
+
raise FormatError("MasterKey salt or nonce length is invalid")
|
|
273
|
+
wrapping_key = _derive_wrapping_key(password_raw, salt)
|
|
274
|
+
try:
|
|
275
|
+
logical_payload = AESGCM(wrapping_key).decrypt(
|
|
276
|
+
nonce, payload, header
|
|
277
|
+
)
|
|
278
|
+
except InvalidTag as exc:
|
|
279
|
+
raise AuthenticationError(
|
|
280
|
+
"MasterKey password or protected payload is invalid"
|
|
281
|
+
) from exc
|
|
282
|
+
except Exception as exc:
|
|
283
|
+
raise BackendError("MasterKey payload decryption failed") from exc
|
|
284
|
+
|
|
285
|
+
if len(logical_payload) > _MAX_LOGICAL_PAYLOAD:
|
|
286
|
+
raise FormatError("MasterKey logical payload exceeds the size limit")
|
|
287
|
+
content_keyset, names_keyset = _split_payload(logical_payload)
|
|
288
|
+
return _restore_key_material(content_keyset, names_keyset)
|
|
289
|
+
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def open_master_key(master_key: str, *, password: str | None = None) -> _KeyMaterial:
|
|
293
|
+
"""Validate and open the public Base64 MasterKey representation."""
|
|
294
|
+
return _open_master_key_bytes(_decode_master_key(master_key), password=password)
|
fscryptography/crypto.py
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
"""Public Manager API for MasterKey-backed filesystem cryptography."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import base64
|
|
6
|
+
|
|
7
|
+
from ._master_key import (
|
|
8
|
+
_KeyMaterial,
|
|
9
|
+
_decode_master_key,
|
|
10
|
+
_open_master_key_bytes,
|
|
11
|
+
generate_master_key,
|
|
12
|
+
)
|
|
13
|
+
from .errors import ClosedInstanceError
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def generate(*, password: str | None = None) -> str:
|
|
17
|
+
"""Generate a Base64 MasterKey, optionally protected by a password."""
|
|
18
|
+
return generate_master_key(password=password)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class Manager:
|
|
22
|
+
"""An opened cryptographic context bound to one MasterKey.
|
|
23
|
+
|
|
24
|
+
The public key representation is Base64 text. The manager retains the
|
|
25
|
+
decoded binary container and the opened Tink primitives. Passwords are
|
|
26
|
+
consumed during initialization or key replacement and are never retained.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
def __init__(self, key: str, *, password: str | None = None) -> None:
|
|
30
|
+
key_bytes = _decode_master_key(key)
|
|
31
|
+
material = _open_master_key_bytes(key_bytes, password=password)
|
|
32
|
+
self._key: bytes | None = key_bytes
|
|
33
|
+
self._material: _KeyMaterial | None = material
|
|
34
|
+
from ._filesystem import _DirectoryOperations, _FileOperations
|
|
35
|
+
self._file_operations = _FileOperations(self)
|
|
36
|
+
self._directory_operations = _DirectoryOperations(self)
|
|
37
|
+
|
|
38
|
+
def _require_open(self) -> _KeyMaterial:
|
|
39
|
+
if self._material is None or self._key is None:
|
|
40
|
+
raise ClosedInstanceError("Manager is closed")
|
|
41
|
+
return self._material
|
|
42
|
+
|
|
43
|
+
@property
|
|
44
|
+
def _content_primitive(self):
|
|
45
|
+
return self._require_open().content
|
|
46
|
+
|
|
47
|
+
@property
|
|
48
|
+
def _names_primitive(self):
|
|
49
|
+
return self._require_open().names
|
|
50
|
+
|
|
51
|
+
@property
|
|
52
|
+
def file(self):
|
|
53
|
+
self._require_open()
|
|
54
|
+
return self._file_operations
|
|
55
|
+
|
|
56
|
+
@property
|
|
57
|
+
def dir(self):
|
|
58
|
+
self._require_open()
|
|
59
|
+
return self._directory_operations
|
|
60
|
+
|
|
61
|
+
def change_key(self, new_key: str, *, password: str | None = None) -> None:
|
|
62
|
+
"""Replace the active context only after the new key opens successfully."""
|
|
63
|
+
self._require_open()
|
|
64
|
+
key_bytes = _decode_master_key(new_key)
|
|
65
|
+
material = _open_master_key_bytes(key_bytes, password=password)
|
|
66
|
+
self._key = key_bytes
|
|
67
|
+
self._material = material
|
|
68
|
+
|
|
69
|
+
def inspect_recovery(self, parent):
|
|
70
|
+
"""Return immutable, read-only diagnostics for transactions under parent."""
|
|
71
|
+
from ._journal import inspect
|
|
72
|
+
return inspect(parent)
|
|
73
|
+
|
|
74
|
+
def export_key(self) -> str:
|
|
75
|
+
"""Return the current MasterKey container as canonical Base64 text."""
|
|
76
|
+
self._require_open()
|
|
77
|
+
return base64.b64encode(self._key).decode("ascii")
|
|
78
|
+
|
|
79
|
+
def close(self) -> None:
|
|
80
|
+
"""Invalidate this manager and release references to its key material."""
|
|
81
|
+
self._material = None
|
|
82
|
+
self._key = None
|
|
83
|
+
|
|
84
|
+
def __enter__(self) -> Manager:
|
|
85
|
+
self._require_open()
|
|
86
|
+
return self
|
|
87
|
+
|
|
88
|
+
def __exit__(self, exc_type, exc, traceback) -> None:
|
|
89
|
+
self.close()
|
fscryptography/errors.py
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
"""Public exception hierarchy for fscryptography."""
|
|
2
|
+
|
|
3
|
+
class FsCryptographyError(Exception):
|
|
4
|
+
"""Base class for errors raised by fscryptography."""
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
class InvalidPathError(FsCryptographyError):
|
|
8
|
+
"""A path or path component cannot be used by the requested operation."""
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class UnsupportedResourceError(FsCryptographyError):
|
|
12
|
+
"""The resource exists but is not supported by the operation."""
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class FormatError(FsCryptographyError):
|
|
16
|
+
"""An encoded representation is malformed or not recognized."""
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class UnsupportedFormatVersionError(FormatError):
|
|
20
|
+
"""The encoded representation uses an unsupported version."""
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class AuthenticationError(FsCryptographyError):
|
|
24
|
+
"""Authenticated decryption failed."""
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class KeyDerivationError(FsCryptographyError):
|
|
28
|
+
"""A key derivation operation failed."""
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class DestinationConflictError(FsCryptographyError):
|
|
32
|
+
"""The destination conflicts with an existing filesystem entry."""
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class NameConstraintError(FsCryptographyError):
|
|
36
|
+
"""A name violates the selected filesystem name profile."""
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class BackendError(FsCryptographyError):
|
|
40
|
+
"""A cryptographic backend operation failed unexpectedly."""
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class ClosedInstanceError(FsCryptographyError):
|
|
44
|
+
"""An operation was attempted on a closed Crypto instance."""
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
class AtomicOperationError(FsCryptographyError):
|
|
48
|
+
"""An atomic filesystem operation could not be completed safely."""
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
class RecoveryError(AtomicOperationError):
|
|
52
|
+
"""Rollback or recovery failed."""
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
"""Binary file envelope header for fscryptography v1.0."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import struct
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
|
|
8
|
+
from .errors import FormatError, UnsupportedFormatVersionError
|
|
9
|
+
|
|
10
|
+
MAGIC = b"FSCRFIL\0"
|
|
11
|
+
MAJOR_VERSION = 1
|
|
12
|
+
MINOR_VERSION = 0
|
|
13
|
+
FIXED_HEADER_SIZE = 16
|
|
14
|
+
METADATA_PREFIX_SIZE = 4
|
|
15
|
+
MAX_EXTENSION_BYTES = 1020
|
|
16
|
+
MAX_HEADER_SIZE = FIXED_HEADER_SIZE + METADATA_PREFIX_SIZE + 2 * MAX_EXTENSION_BYTES
|
|
17
|
+
|
|
18
|
+
FLAG_ORIGINAL_EXTENSION = 0x0001
|
|
19
|
+
FLAG_ENCRYPTED_NAME = 0x0002
|
|
20
|
+
_KNOWN_FLAGS = FLAG_ORIGINAL_EXTENSION | FLAG_ENCRYPTED_NAME
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass(frozen=True, slots=True)
|
|
24
|
+
class FileHeader:
|
|
25
|
+
"""Validated, authenticated metadata carried by a file header."""
|
|
26
|
+
|
|
27
|
+
original_extension: str | None
|
|
28
|
+
output_extension: str | None
|
|
29
|
+
encrypted_name: bool
|
|
30
|
+
raw: bytes
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def split_extension(name: str) -> tuple[str, str | None]:
|
|
34
|
+
"""Return (base, extension); dotfiles and trailing dots have no extension."""
|
|
35
|
+
if not isinstance(name, str):
|
|
36
|
+
raise TypeError("name must be str")
|
|
37
|
+
if not name or name in {".", ".."} or "/" in name or "\\x00" in name:
|
|
38
|
+
raise ValueError("name must be one non-empty filename component")
|
|
39
|
+
dot = name.rfind(".")
|
|
40
|
+
if dot <= 0 or dot == len(name) - 1:
|
|
41
|
+
return name, None
|
|
42
|
+
return name[:dot], name[dot:]
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def validate_extension(extension: str | None, *, allow_none: bool = True) -> str | None:
|
|
46
|
+
"""Validate an extension value without adding, stripping, or normalizing."""
|
|
47
|
+
if extension is None:
|
|
48
|
+
if allow_none:
|
|
49
|
+
return None
|
|
50
|
+
raise ValueError("extension is required")
|
|
51
|
+
if not isinstance(extension, str):
|
|
52
|
+
raise TypeError("extension must be str or None")
|
|
53
|
+
if extension == "":
|
|
54
|
+
return ""
|
|
55
|
+
if (
|
|
56
|
+
not extension.startswith(".")
|
|
57
|
+
or extension.startswith("..")
|
|
58
|
+
or "/" in extension
|
|
59
|
+
or "\\x00" in extension
|
|
60
|
+
or len(extension) < 2
|
|
61
|
+
or any(ord(char) < 0x20 for char in extension)
|
|
62
|
+
):
|
|
63
|
+
raise ValueError("extension must be a valid single-component suffix")
|
|
64
|
+
try:
|
|
65
|
+
encoded = extension.encode("utf-8", errors="strict")
|
|
66
|
+
except UnicodeEncodeError as exc:
|
|
67
|
+
raise ValueError("extension must be valid UTF-8") from exc
|
|
68
|
+
if len(encoded) > MAX_EXTENSION_BYTES:
|
|
69
|
+
raise ValueError("extension exceeds the format metadata limit")
|
|
70
|
+
return extension
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def build_header(
|
|
74
|
+
*,
|
|
75
|
+
original_extension: str | None,
|
|
76
|
+
output_extension: str | None,
|
|
77
|
+
encrypted_name: bool = False,
|
|
78
|
+
) -> bytes:
|
|
79
|
+
"""Serialize the v1.0 header; both extension values are authenticated as AAD.
|
|
80
|
+
|
|
81
|
+
For visible names, output_extension is mandatory and may be empty. For
|
|
82
|
+
encrypted names, neither extension is stored in cleartext.
|
|
83
|
+
"""
|
|
84
|
+
original = validate_extension(original_extension)
|
|
85
|
+
output = validate_extension(output_extension)
|
|
86
|
+
if original == "":
|
|
87
|
+
raise ValueError("original_extension must be None or a non-empty suffix")
|
|
88
|
+
if not isinstance(encrypted_name, bool):
|
|
89
|
+
raise TypeError("encrypted_name must be bool")
|
|
90
|
+
if encrypted_name:
|
|
91
|
+
if original is not None or output is not None:
|
|
92
|
+
raise ValueError("encrypted-name headers must not expose extensions")
|
|
93
|
+
flags = FLAG_ENCRYPTED_NAME
|
|
94
|
+
original_bytes = output_bytes = b""
|
|
95
|
+
else:
|
|
96
|
+
if output is None:
|
|
97
|
+
raise ValueError("visible-name headers require output_extension")
|
|
98
|
+
flags = 0
|
|
99
|
+
if original is not None:
|
|
100
|
+
flags |= FLAG_ORIGINAL_EXTENSION
|
|
101
|
+
original_bytes = b"" if original is None else original.encode("utf-8")
|
|
102
|
+
output_bytes = output.encode("utf-8")
|
|
103
|
+
|
|
104
|
+
metadata = struct.pack(">HH", len(original_bytes), len(output_bytes))
|
|
105
|
+
metadata += original_bytes + output_bytes
|
|
106
|
+
header_length = FIXED_HEADER_SIZE + len(metadata)
|
|
107
|
+
if header_length > MAX_HEADER_SIZE:
|
|
108
|
+
raise ValueError("file header exceeds the format limit")
|
|
109
|
+
fixed = (
|
|
110
|
+
MAGIC
|
|
111
|
+
+ bytes((MAJOR_VERSION, MINOR_VERSION))
|
|
112
|
+
+ struct.pack(">HI", flags, header_length)
|
|
113
|
+
)
|
|
114
|
+
return fixed + metadata
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def parse_header(raw: bytes) -> FileHeader:
|
|
118
|
+
"""Parse and strictly validate one complete v1.0 header."""
|
|
119
|
+
if not isinstance(raw, bytes):
|
|
120
|
+
raise TypeError("header must be bytes")
|
|
121
|
+
if len(raw) < FIXED_HEADER_SIZE:
|
|
122
|
+
raise FormatError("file header is truncated")
|
|
123
|
+
if raw[:8] != MAGIC:
|
|
124
|
+
raise FormatError("file magic is invalid")
|
|
125
|
+
if raw[8] != MAJOR_VERSION or raw[9] != MINOR_VERSION:
|
|
126
|
+
raise UnsupportedFormatVersionError("unsupported file format version")
|
|
127
|
+
flags, header_length = struct.unpack_from(">HI", raw, 10)
|
|
128
|
+
if flags & ~_KNOWN_FLAGS:
|
|
129
|
+
raise FormatError("file header contains reserved flags")
|
|
130
|
+
if header_length < FIXED_HEADER_SIZE + METADATA_PREFIX_SIZE:
|
|
131
|
+
raise FormatError("file header length is too small")
|
|
132
|
+
if header_length > MAX_HEADER_SIZE:
|
|
133
|
+
raise FormatError("file header exceeds the format limit")
|
|
134
|
+
if len(raw) != header_length:
|
|
135
|
+
raise FormatError("file header length does not match supplied bytes")
|
|
136
|
+
|
|
137
|
+
original_length, output_length = struct.unpack_from(">HH", raw, FIXED_HEADER_SIZE)
|
|
138
|
+
if original_length > MAX_EXTENSION_BYTES or output_length > MAX_EXTENSION_BYTES:
|
|
139
|
+
raise FormatError("file extension metadata exceeds the format limit")
|
|
140
|
+
expected_length = FIXED_HEADER_SIZE + METADATA_PREFIX_SIZE + original_length + output_length
|
|
141
|
+
if expected_length != header_length:
|
|
142
|
+
raise FormatError("file extension metadata lengths are inconsistent")
|
|
143
|
+
|
|
144
|
+
original_raw = raw[20 : 20 + original_length]
|
|
145
|
+
output_raw = raw[20 + original_length : header_length]
|
|
146
|
+
try:
|
|
147
|
+
original = original_raw.decode("utf-8", errors="strict") if original_length else None
|
|
148
|
+
output = output_raw.decode("utf-8", errors="strict") if output_length else ""
|
|
149
|
+
except UnicodeDecodeError as exc:
|
|
150
|
+
raise FormatError("file extension metadata is not valid UTF-8") from exc
|
|
151
|
+
|
|
152
|
+
original_flag = bool(flags & FLAG_ORIGINAL_EXTENSION)
|
|
153
|
+
encrypted_name = bool(flags & FLAG_ENCRYPTED_NAME)
|
|
154
|
+
if original_flag != (original is not None):
|
|
155
|
+
raise FormatError("original-extension flag and metadata disagree")
|
|
156
|
+
if original is not None:
|
|
157
|
+
try:
|
|
158
|
+
validate_extension(original, allow_none=False)
|
|
159
|
+
except (TypeError, ValueError) as exc:
|
|
160
|
+
raise FormatError("original extension metadata is invalid") from exc
|
|
161
|
+
if encrypted_name:
|
|
162
|
+
if original_length or output_length or original_flag:
|
|
163
|
+
raise FormatError("encrypted-name header exposes extension metadata")
|
|
164
|
+
output_value = None
|
|
165
|
+
else:
|
|
166
|
+
if output_length:
|
|
167
|
+
try:
|
|
168
|
+
validate_extension(output, allow_none=False)
|
|
169
|
+
except (TypeError, ValueError) as exc:
|
|
170
|
+
raise FormatError("output extension metadata is invalid") from exc
|
|
171
|
+
output_value = output
|
|
172
|
+
|
|
173
|
+
return FileHeader(
|
|
174
|
+
original_extension=original,
|
|
175
|
+
output_extension=output_value,
|
|
176
|
+
encrypted_name=encrypted_name,
|
|
177
|
+
raw=raw,
|
|
178
|
+
)
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
"""Filename encryption and validation primitives."""
|
|
2
|
+
|
|
3
|
+
from .codec import AAD, MARKER, decrypt_name, encrypt_name, is_canonical_candidate
|
|
4
|
+
from .validation import NameProfile, validate_name
|
|
5
|
+
from .tink_backend import load_name_primitive
|
|
6
|
+
|
|
7
|
+
__all__ = [
|
|
8
|
+
"AAD",
|
|
9
|
+
"MARKER",
|
|
10
|
+
"NameProfile",
|
|
11
|
+
"decrypt_name",
|
|
12
|
+
"encrypt_name",
|
|
13
|
+
"is_canonical_candidate",
|
|
14
|
+
"load_name_primitive",
|
|
15
|
+
"validate_name",
|
|
16
|
+
]
|