derivepassphrase.git

1) # SPDX-FileCopyrightText: 2025 Marco Ricci <software@the13thletter.info>

2) #

3) # SPDX-License-Identifier: Zlib

4) 

5) """Exporter for the vault "storeroom" configuration format.
6) 
7) The "storeroom" format is the experimental format used in alpha and beta
8) versions of vault beyond v0.3.0.  The configuration is stored as
9) a separate directory, which acts like a hash table (i.e. has named
10) slots) and provides an impure quasi-filesystem interface.  Each hash
11) table entry is separately encrypted and authenticated.  James Coglan
12) designed this format to avoid concurrent write issues when updating or
13) synchronizing the vault configuration with e.g. a cloud service.
14) 

15) The public interface is the [`export_storeroom_data`][] function.
16) Multiple *non-public* functions are additionally documented here for
17) didactical and educational reasons, but they are not part of the module
18) API, are subject to change without notice (including removal), and
19) should *not* be used or relied on.

20) 
21) """

22) 

23) # ruff: noqa: S303
24) 

25) from __future__ import annotations
26) 

27) import base64

28) import fnmatch

29) import importlib

30) import json
31) import logging
32) import os
33) import os.path
34) import struct

35) from typing import TYPE_CHECKING, Any

36) 

37) from derivepassphrase import _cli_msg as _msg

38) from derivepassphrase import _types, exporter

39) 

40) if TYPE_CHECKING:
41)     from collections.abc import Iterator
42) 

43)     from cryptography.hazmat.primitives import ciphers, hashes, hmac, padding
44)     from cryptography.hazmat.primitives.ciphers import algorithms, modes
45)     from cryptography.hazmat.primitives.kdf import pbkdf2

46)     from typing_extensions import Buffer

47) else:
48)     try:

49)         importlib.import_module('cryptography')

50)     except ModuleNotFoundError as exc:
51) 

52)         class _DummyModule:  # pragma: no cover

53)             def __init__(self, exc: type[Exception]) -> None:
54)                 self.exc = exc
55) 

56)             def __getattr__(self, name: str) -> Any:  # noqa: ANN401
57)                 def func(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401,ARG001

58)                     raise self.exc
59) 
60)                 return func
61) 

62)         ciphers = hashes = hmac = padding = _DummyModule(exc)
63)         algorithms = modes = pbkdf2 = _DummyModule(exc)

64)         STUBBED = True
65)     else:

66)         from cryptography.hazmat.primitives import (
67)             ciphers,
68)             hashes,
69)             hmac,
70)             padding,
71)         )
72)         from cryptography.hazmat.primitives.ciphers import algorithms, modes
73)         from cryptography.hazmat.primitives.kdf import pbkdf2
74) 

75)         STUBBED = False
76) 

77) STOREROOM_MASTER_KEYS_UUID = b'35b7c7ed-f71e-4adf-9051-02fb0f1e0e17'
78) VAULT_CIPHER_UUID = b'73e69e8a-cb05-4b50-9f42-59d76a511299'
79) IV_SIZE = 16
80) KEY_SIZE = MAC_SIZE = 32
81) ENCRYPTED_KEYPAIR_SIZE = 128
82) VERSION_SIZE = 1
83) 

84) __all__ = ('export_storeroom_data',)
85) 

86) logger = logging.getLogger(__name__)

87) 
88) 

89) def _h(bs: Buffer) -> str:
90)     return '<{}>'.format(memoryview(bs).hex(' '))
91) 
92) 

93) def derive_master_keys_keys(
94)     password: str | Buffer,
95)     iterations: int,

96) ) -> _types.StoreroomKeyPair:

97)     """Derive encryption and signing keys for the master keys data.
98) 
99)     The master password is run through a key derivation function to
100)     obtain a 64-byte string, which is then split to yield two 32-byte
101)     keys.  The key derivation function is PBKDF2, using HMAC-SHA1 and
102)     salted with the storeroom master keys UUID.
103) 
104)     Args:
105)         password:
106)             A master password for the storeroom instance.  Usually read
107)             from the `VAULT_KEY` environment variable, otherwise
108)             defaults to the username.
109)         iterations:
110)             A count of rounds for the underlying key derivation
111)             function.  Usually stored as a setting next to the encrypted
112)             master keys data.
113) 
114)     Returns:
115)         A 2-tuple of keys, the encryption key and the signing key, to
116)         decrypt and verify the master keys data with.
117) 

118)     Warning:
119)         Non-public function, provided for didactical and educational
120)         purposes only.  Subject to change without notice, including
121)         removal.
122) 

123)     """

124)     if isinstance(password, str):
125)         password = password.encode('ASCII')
126)     master_keys_keys_blob = pbkdf2.PBKDF2HMAC(

127)         algorithm=hashes.SHA1(),

128)         length=2 * KEY_SIZE,

129)         salt=STOREROOM_MASTER_KEYS_UUID,
130)         iterations=iterations,

131)     ).derive(bytes(password))

132)     encryption_key, signing_key = struct.unpack(
133)         f'{KEY_SIZE}s {KEY_SIZE}s', master_keys_keys_blob
134)     )
135)     logger.debug(

136)         _msg.TranslatedString(
137)             _msg.DebugMsgTemplate.DERIVED_MASTER_KEYS_KEYS,
138)             enc_key=_h(encryption_key),
139)             sign_key=_h(signing_key),
140)             pw_bytes=_h(password),
141)             algorithm='SHA256',
142)             length=64,
143)             salt=STOREROOM_MASTER_KEYS_UUID,
144)             iterations=iterations,

145)         ),
146)     )

147)     return _types.StoreroomKeyPair(
148)         encryption_key=encryption_key,
149)         signing_key=signing_key,

150)     ).toreadonly()

151) 
152) 

153) def decrypt_master_keys_data(
154)     data: Buffer,

155)     keys: _types.StoreroomKeyPair,
156) ) -> _types.StoreroomMasterKeys:

157)     r"""Decrypt the master keys data.

158) 
159)     The master keys data contains:
160) 
161)     - a 16-byte IV,

162)     - a 96-byte AES256-CBC-encrypted payload, plus 16 further bytes of
163)       PKCS7 padding, and
164)     - a 32-byte MAC of the preceding 128 bytes.

165) 
166)     The decrypted payload itself consists of three 32-byte keys: the
167)     hashing, encryption and signing keys, in that order.
168) 
169)     The encrypted payload is encrypted with the encryption key, and the
170)     MAC is created based on the signing key.  As per standard
171)     cryptographic procedure, the MAC can be verified before attempting
172)     to decrypt the payload.
173) 

174)     Because the payload size is both fixed and a multiple of the cipher
175)     blocksize, in this case, the PKCS7 padding always is `b'\x10' * 16`.

176) 
177)     Args:
178)         data:
179)             The encrypted master keys data.
180)         keys:
181)             The encryption and signing keys for the master keys data.
182)             These should have previously been derived via the

183)             [`derive_master_keys_keys`][] function.

184) 
185)     Returns:
186)         The master encryption, signing and hashing keys.
187) 

188)     Raises:
189)         cryptography.exceptions.InvalidSignature:
190)             The data does not contain a valid signature under the given
191)             key.
192)         ValueError:
193)             The format is invalid, in a non-cryptographic way.  (For
194)             example, it contains an unsupported version marker, or
195)             unexpected extra contents, or invalid padding.)
196) 

197)     Warning:
198)         Non-public function, provided for didactical and educational
199)         purposes only.  Subject to change without notice, including
200)         removal.
201) 

202)     """

203)     data = memoryview(data).toreadonly().cast('c')

204)     keys = keys.toreadonly()

205)     ciphertext, claimed_mac = struct.unpack(
206)         f'{len(data) - MAC_SIZE}s {MAC_SIZE}s', data
207)     )

208)     actual_mac = hmac.HMAC(keys.signing_key, hashes.SHA256())

209)     actual_mac.update(ciphertext)
210)     logger.debug(

211)         _msg.TranslatedString(
212)             _msg.DebugMsgTemplate.MASTER_KEYS_DATA_MAC_INFO,

213)             sign_key=_h(keys.signing_key),

214)             ciphertext=_h(ciphertext),
215)             claimed_mac=_h(claimed_mac),
216)             actual_mac=_h(actual_mac.copy().finalize()),

217)         ),
218)     )
219)     actual_mac.verify(claimed_mac)
220) 

221)     try:
222)         iv, payload = struct.unpack(
223)             f'{IV_SIZE}s {len(ciphertext) - IV_SIZE}s', ciphertext

224)         )

225)         decryptor = ciphers.Cipher(

226)             algorithms.AES256(keys.encryption_key), modes.CBC(iv)

227)         ).decryptor()
228)         padded_plaintext = bytearray()
229)         padded_plaintext.extend(decryptor.update(payload))
230)         padded_plaintext.extend(decryptor.finalize())
231)         unpadder = padding.PKCS7(IV_SIZE * 8).unpadder()
232)         plaintext = bytearray()
233)         plaintext.extend(unpadder.update(padded_plaintext))
234)         plaintext.extend(unpadder.finalize())
235)         hashing_key, encryption_key, signing_key = struct.unpack(
236)             f'{KEY_SIZE}s {KEY_SIZE}s {KEY_SIZE}s', plaintext
237)         )
238)     except (ValueError, struct.error) as exc:
239)         msg = 'Invalid encrypted master keys payload'
240)         raise ValueError(msg) from exc

241)     return _types.StoreroomMasterKeys(
242)         hashing_key=hashing_key,
243)         encryption_key=encryption_key,
244)         signing_key=signing_key,

245)     ).toreadonly()

246) 
247) 

248) def decrypt_session_keys(
249)     data: Buffer,

250)     master_keys: _types.StoreroomMasterKeys,
251) ) -> _types.StoreroomKeyPair:

252)     r"""Decrypt the bucket item's session keys.

253) 
254)     The bucket item's session keys are single-use keys for encrypting
255)     and signing a single item in the storage bucket.  The encrypted
256)     session key data consists of:
257) 
258)     - a 16-byte IV,

259)     - a 64-byte AES256-CBC-encrypted payload, plus 16 further bytes of
260)       PKCS7 padding, and
261)     - a 32-byte MAC of the preceding 96 bytes.

262) 
263)     The encrypted payload is encrypted with the master encryption key,
264)     and the MAC is created with the master signing key.  As per standard
265)     cryptographic procedure, the MAC can be verified before attempting
266)     to decrypt the payload.
267) 

268)     Because the payload size is both fixed and a multiple of the cipher
269)     blocksize, in this case, the PKCS7 padding always is `b'\x10' * 16`.

270) 
271)     Args:
272)         data:
273)             The encrypted bucket item session key data.
274)         master_keys:
275)             The master keys.  Presumably these have previously been

276)             obtained via the [`decrypt_master_keys_data`][] function.

277) 
278)     Returns:
279)         The bucket item's encryption and signing keys.
280) 

281)     Raises:
282)         cryptography.exceptions.InvalidSignature:
283)             The data does not contain a valid signature under the given
284)             key.
285)         ValueError:
286)             The format is invalid, in a non-cryptographic way.  (For
287)             example, it contains an unsupported version marker, or
288)             unexpected extra contents, or invalid padding.)

289) 

290)     Warning:
291)         Non-public function, provided for didactical and educational
292)         purposes only.  Subject to change without notice, including
293)         removal.
294) 

295)     """

296)     data = memoryview(data).toreadonly().cast('c')

297)     master_keys = master_keys.toreadonly()

298)     ciphertext, claimed_mac = struct.unpack(
299)         f'{len(data) - MAC_SIZE}s {MAC_SIZE}s', data
300)     )

301)     actual_mac = hmac.HMAC(master_keys.signing_key, hashes.SHA256())

302)     actual_mac.update(ciphertext)
303)     logger.debug(

304)         _msg.TranslatedString(
305)             _msg.DebugMsgTemplate.DECRYPT_BUCKET_ITEM_SESSION_KEYS_MAC_INFO,

306)             sign_key=_h(master_keys.signing_key),

307)             ciphertext=_h(ciphertext),
308)             claimed_mac=_h(claimed_mac),
309)             actual_mac=_h(actual_mac.copy().finalize()),

310)         ),
311)     )
312)     actual_mac.verify(claimed_mac)
313) 

314)     try:
315)         iv, payload = struct.unpack(
316)             f'{IV_SIZE}s {len(ciphertext) - IV_SIZE}s', ciphertext
317)         )
318)         decryptor = ciphers.Cipher(

319)             algorithms.AES256(master_keys.encryption_key), modes.CBC(iv)

320)         ).decryptor()
321)         padded_plaintext = bytearray()
322)         padded_plaintext.extend(decryptor.update(payload))
323)         padded_plaintext.extend(decryptor.finalize())
324)         unpadder = padding.PKCS7(IV_SIZE * 8).unpadder()
325)         plaintext = bytearray()
326)         plaintext.extend(unpadder.update(padded_plaintext))
327)         plaintext.extend(unpadder.finalize())
328)         session_encryption_key, session_signing_key = struct.unpack(
329)             f'{KEY_SIZE}s {KEY_SIZE}s', plaintext
330)         )
331)     except (ValueError, struct.error) as exc:
332)         msg = 'Invalid encrypted session keys payload'
333)         raise ValueError(msg) from exc

334) 

335)     session_keys = _types.StoreroomKeyPair(
336)         encryption_key=session_encryption_key,
337)         signing_key=session_signing_key,

338)     ).toreadonly()

339) 
340)     logger.debug(

341)         _msg.TranslatedString(
342)             _msg.DebugMsgTemplate.DECRYPT_BUCKET_ITEM_SESSION_KEYS_INFO,

343)             enc_key=_h(master_keys.encryption_key),

344)             iv=_h(iv),
345)             ciphertext=_h(payload),
346)             plaintext=_h(plaintext),
347)             code=_msg.TranslatedString(

348)                 'StoreroomKeyPair(encryption_key=bytes.fromhex({enc_key!r}), '
349)                 'signing_key=bytes.fromhex({sign_key!r}))',
350)                 enc_key=session_keys.encryption_key.hex(' '),
351)                 sign_key=session_keys.signing_key.hex(' '),

352)             ),

353)         ),
354)     )
355) 
356)     return session_keys
357) 
358) 

359) def decrypt_contents(
360)     data: Buffer,

361)     session_keys: _types.StoreroomKeyPair,

362) ) -> Buffer:

363)     """Decrypt the bucket item's contents.
364) 
365)     The data consists of:
366) 
367)     - a 16-byte IV,
368)     - a variable-sized AES256-CBC-encrypted payload (using PKCS7 padding
369)       on the inside), and

370)     - a 32-byte MAC of the preceding bytes.

371) 
372)     The encrypted payload is encrypted with the bucket item's session
373)     encryption key, and the MAC is created with the bucket item's
374)     session signing key.  As per standard cryptographic procedure, the
375)     MAC can be verified before attempting to decrypt the payload.
376) 
377)     Args:
378)         data:
379)             The encrypted bucket item payload data.
380)         session_keys:
381)             The bucket item's session keys.  Presumably these have

382)             previously been obtained via the [`decrypt_session_keys`][]

383)             function.
384) 
385)     Returns:
386)         The bucket item's payload.
387) 

388)     Raises:
389)         cryptography.exceptions.InvalidSignature:
390)             The data does not contain a valid signature under the given
391)             key.
392)         ValueError:
393)             The format is invalid, in a non-cryptographic way.  (For
394)             example, it contains an unsupported version marker, or
395)             unexpected extra contents, or invalid padding.)

396) 

397)     Warning:
398)         Non-public function, provided for didactical and educational
399)         purposes only.  Subject to change without notice, including
400)         removal.
401) 

402)     """

403)     data = memoryview(data).toreadonly().cast('c')

404)     session_keys = session_keys.toreadonly()

405)     ciphertext, claimed_mac = struct.unpack(
406)         f'{len(data) - MAC_SIZE}s {MAC_SIZE}s', data
407)     )

408)     actual_mac = hmac.HMAC(session_keys.signing_key, hashes.SHA256())

409)     actual_mac.update(ciphertext)
410)     logger.debug(

411)         _msg.TranslatedString(
412)             _msg.DebugMsgTemplate.DECRYPT_BUCKET_ITEM_MAC_INFO,

413)             sign_key=_h(session_keys.signing_key),

414)             ciphertext=_h(ciphertext),
415)             claimed_mac=_h(claimed_mac),
416)             actual_mac=_h(actual_mac.copy().finalize()),

417)         ),
418)     )
419)     actual_mac.verify(claimed_mac)
420) 
421)     iv, payload = struct.unpack(
422)         f'{IV_SIZE}s {len(ciphertext) - IV_SIZE}s', ciphertext
423)     )
424)     decryptor = ciphers.Cipher(

425)         algorithms.AES256(session_keys.encryption_key), modes.CBC(iv)

426)     ).decryptor()
427)     padded_plaintext = bytearray()
428)     padded_plaintext.extend(decryptor.update(payload))
429)     padded_plaintext.extend(decryptor.finalize())
430)     unpadder = padding.PKCS7(IV_SIZE * 8).unpadder()
431)     plaintext = bytearray()
432)     plaintext.extend(unpadder.update(padded_plaintext))
433)     plaintext.extend(unpadder.finalize())
434) 
435)     logger.debug(

436)         _msg.TranslatedString(
437)             _msg.DebugMsgTemplate.DECRYPT_BUCKET_ITEM_INFO,

438)             enc_key=_h(session_keys.encryption_key),

439)             iv=_h(iv),
440)             ciphertext=_h(payload),
441)             plaintext=_h(plaintext),

442)         ),
443)     )
444) 
445)     return plaintext
446) 
447) 

448) def decrypt_bucket_item(
449)     bucket_item: Buffer,

450)     master_keys: _types.StoreroomMasterKeys,

451) ) -> Buffer:

452)     """Decrypt a bucket item.
453) 
454)     Args:
455)         bucket_item:
456)             The encrypted bucket item.
457)         master_keys:
458)             The master keys.  Presumably these have previously been

459)             obtained via the [`decrypt_master_keys_data`][] function.

460) 
461)     Returns:
462)         The decrypted bucket item.
463) 
464)     Raises:
465)         cryptography.exceptions.InvalidSignature:
466)             The data does not contain a valid signature under the given
467)             key.
468)         ValueError:
469)             The format is invalid, in a non-cryptographic way.  (For
470)             example, it contains an unsupported version marker, or
471)             unexpected extra contents, or invalid padding.)
472) 

473)     Warning:
474)         Non-public function, provided for didactical and educational
475)         purposes only.  Subject to change without notice, including
476)         removal.
477) 

478)     """

479)     bucket_item = memoryview(bucket_item).toreadonly().cast('c')

480)     master_keys = master_keys.toreadonly()

481)     logger.debug(

482)         _msg.TranslatedString(
483)             _msg.DebugMsgTemplate.DECRYPT_BUCKET_ITEM_KEY_INFO,
484)             plaintext=_h(bucket_item),

485)             enc_key=_h(master_keys.encryption_key),
486)             sign_key=_h(master_keys.signing_key),

487)         ),
488)     )
489)     data_version, encrypted_session_keys, data_contents = struct.unpack(
490)         (
491)             f'B {ENCRYPTED_KEYPAIR_SIZE}s '

492)             f'{len(bucket_item) - 1 - ENCRYPTED_KEYPAIR_SIZE}s'

493)         ),

494)         bucket_item,

495)     )
496)     if data_version != 1:
497)         msg = f'Cannot handle version {data_version} encrypted data'

498)         raise ValueError(msg)

499)     session_keys = decrypt_session_keys(encrypted_session_keys, master_keys)
500)     return decrypt_contents(data_contents, session_keys)
501) 
502) 

503) def decrypt_bucket_file(

504)     filename: str,

505)     master_keys: _types.StoreroomMasterKeys,

506)     *,
507)     root_dir: str | bytes | os.PathLike = '.',

508) ) -> Iterator[Buffer]:

509)     """Decrypt a complete bucket.

510) 
511)     Args:
512)         filename:
513)             The bucket file's filename.
514)         master_keys:
515)             The master keys.  Presumably these have previously been

516)             obtained via the [`decrypt_master_keys_data`][] function.

517)         root_dir:
518)             The root directory of the data store.  The filename is
519)             interpreted relatively to this directory.
520) 
521)     Yields:

522)         A decrypted bucket item.

523) 
524)     Raises:
525)         cryptography.exceptions.InvalidSignature:
526)             The data does not contain a valid signature under the given
527)             key.
528)         ValueError:
529)             The format is invalid, in a non-cryptographic way.  (For
530)             example, it contains an unsupported version marker, or
531)             unexpected extra contents, or invalid padding.)
532) 

533)     Warning:
534)         Non-public function, provided for didactical and educational
535)         purposes only.  Subject to change without notice, including
536)         removal.
537) 

538)     """

539)     master_keys = master_keys.toreadonly()

540)     with open(
541)         os.path.join(os.fsdecode(root_dir), filename), 'rb'
542)     ) as bucket_file:

543)         header_line = bucket_file.readline()
544)         try:
545)             header = json.loads(header_line)
546)         except ValueError as exc:
547)             msg = f'Invalid bucket file: {filename}'

548)             raise ValueError(msg) from exc

549)         if header != {'version': 1}:
550)             msg = f'Invalid bucket file: {filename}'

551)             raise ValueError(msg) from None

552)         for line in bucket_file:

553)             yield decrypt_bucket_item(
554)                 base64.standard_b64decode(line), master_keys

555)             )
556) 
557) 

558) def _store(config: dict[str, Any], path: str, json_contents: bytes) -> None:

559)     """Store the JSON contents at path in the config structure.
560) 
561)     Traverse the config structure according to path, and set the value
562)     of the leaf to the decoded JSON contents.
563) 
564)     A path `/foo/bar/xyz` translates to the JSON structure
565)     `{"foo": {"bar": {"xyz": ...}}}`.
566) 
567)     Args:
568)         config:
569)             The (top-level) configuration structure to update.
570)         path:
571)             The path within the configuration structure to traverse.
572)         json_contents:
573)             The contents to set the item to, after JSON-decoding.
574) 
575)     Raises:
576)         json.JSONDecodeError:
577)             There was an error parsing the JSON contents.
578) 
579)     """
580)     contents = json.loads(json_contents)
581)     path_parts = [part for part in path.split('/') if part]
582)     for part in path_parts[:-1]:
583)         config = config.setdefault(part, {})
584)     if path_parts:
585)         config[path_parts[-1]] = contents
586) 
587) 

588) @exporter.register_export_vault_config_data_handler('storeroom')

589) def export_storeroom_data(  # noqa: C901,PLR0912,PLR0914,PLR0915

590)     path: str | bytes | os.PathLike | None = None,
591)     key: str | Buffer | None = None,
592)     *,
593)     format: str = 'storeroom',  # noqa: A002

594) ) -> dict[str, Any]:
595)     """Export the full configuration stored in the storeroom.
596) 
597)     Args:

598)         path:
599)             The path to the vault configuration directory.  If not
600)             given, then query [`exporter.get_vault_path`][] for the
601)             correct value.
602)         key:
603)             Encryption key/password for the (master keys file in the)
604)             configuration directory, usually the username, or passed via
605)             the `VAULT_KEY` environment variable.  If not given, then
606)             query [`exporter.get_vault_key`][] for the value.
607)         format:
608)             The format to attempt parsing as.  If specified, must be
609)             `storeroom`.

610) 
611)     Returns:

612)         The vault configuration, as recorded in the configuration
613)         directory.

614) 

615)         This may or may not be a valid configuration according to
616)         `vault` or `derivepassphrase`.

617) 
618)     Raises:
619)         RuntimeError:
620)             Something went wrong during data collection, e.g. we
621)             encountered unsupported or corrupted data in the storeroom.
622)         json.JSONDecodeError:
623)             An internal JSON data structure failed to parse from disk.
624)             The storeroom is probably corrupted.

625)         exporter.NotAVaultConfigError:
626)             The directory does contain not a storeroom.
627)         ValueError:
628)             The requested format is invalid.

629) 
630)     """

631)     # Trigger import errors if necessary.
632)     importlib.import_module('cryptography')
633)     if path is None:
634)         path = exporter.get_vault_path()
635)     if key is None:
636)         key = exporter.get_vault_key()
637)     if format != 'storeroom':  # pragma: no cover
638)         msg = exporter.INVALID_VAULT_NATIVE_CONFIGURATION_FORMAT.format(
639)             fmt=format
640)         )
641)         raise ValueError(msg)
642)     try:
643)         master_keys_file = open(  # noqa: SIM115
644)             os.path.join(os.fsdecode(path), '.keys'),
645)             encoding='utf-8',
646)         )
647)     except FileNotFoundError as exc:
648)         raise exporter.NotAVaultConfigError(
649)             os.fsdecode(path),
650)             format='storeroom',
651)         ) from exc
652)     with master_keys_file:

653)         header = json.loads(master_keys_file.readline())
654)         if header != {'version': 1}:
655)             msg = 'bad or unsupported keys version header'
656)             raise RuntimeError(msg)
657)         raw_keys_data = base64.standard_b64decode(master_keys_file.readline())
658)         encrypted_keys_params, encrypted_keys = struct.unpack(
659)             f'B {len(raw_keys_data) - 1}s', raw_keys_data
660)         )
661)         if master_keys_file.read():
662)             msg = 'trailing data; cannot make sense of .keys file'
663)             raise RuntimeError(msg)
664)     encrypted_keys_version = encrypted_keys_params >> 4
665)     if encrypted_keys_version != 1:
666)         msg = f'cannot handle version {encrypted_keys_version} encrypted keys'
667)         raise RuntimeError(msg)

668)     logger.info(
669)         _msg.TranslatedString(_msg.InfoMsgTemplate.PARSING_MASTER_KEYS_DATA)
670)     )

671)     encrypted_keys_iterations = 2 ** (10 + (encrypted_keys_params & 0x0F))

672)     master_keys_keys = derive_master_keys_keys(key, encrypted_keys_iterations)

673)     master_keys = decrypt_master_keys_data(encrypted_keys, master_keys_keys)
674) 

675)     config_structure: dict[str, Any] = {}
676)     json_contents: dict[str, bytes] = {}

677)     # Use glob.glob(..., root_dir=...) here once Python 3.9 becomes
678)     # unsupported.

679)     storeroom_path_str = os.fsdecode(path)

680)     valid_hashdirs = [
681)         hashdir_name
682)         for hashdir_name in os.listdir(storeroom_path_str)
683)         if fnmatch.fnmatch(hashdir_name, '[01][0-9a-f]')
684)     ]
685)     for file in valid_hashdirs:

686)         logger.info(
687)             _msg.TranslatedString(
688)                 _msg.InfoMsgTemplate.DECRYPTING_BUCKET,
689)                 bucket_number=file,
690)             )
691)         )

692)         bucket_contents = [
693)             bytes(item)

694)             for item in decrypt_bucket_file(file, master_keys, root_dir=path)

695)         ]

696)         bucket_index = json.loads(bucket_contents.pop(0))
697)         for pos, item in enumerate(bucket_index):
698)             json_contents[item] = bucket_contents[pos]
699)             logger.debug(

700)                 _msg.TranslatedString(
701)                     _msg.DebugMsgTemplate.BUCKET_ITEM_FOUND,
702)                     path=item,
703)                     value=bucket_contents[pos],
704)                 )

705)             )
706)     dirs_to_check: dict[str, list[str]] = {}
707)     json_payload: Any

708)     logger.info(
709)         _msg.TranslatedString(_msg.InfoMsgTemplate.ASSEMBLING_CONFIG_STRUCTURE)
710)     )

711)     for item_path, json_content in sorted(json_contents.items()):
712)         if item_path.endswith('/'):

713)             logger.debug(

714)                 _msg.TranslatedString(
715)                     _msg.DebugMsgTemplate.POSTPONING_DIRECTORY_CONTENTS_CHECK,

716)                     path=item_path,

717)                     contents=json_content.decode('utf-8'),
718)                 )

719)             )
720)             json_payload = json.loads(json_content)
721)             if not isinstance(json_payload, list) or any(
722)                 not isinstance(x, str) for x in json_payload
723)             ):
724)                 msg = (
725)                     f'Directory index is not actually an index: '
726)                     f'{json_content!r}'
727)                 )
728)                 raise RuntimeError(msg)

729)             dirs_to_check[item_path] = json_payload

730)             logger.debug(

731)                 _msg.TranslatedString(
732)                     _msg.DebugMsgTemplate.SETTING_CONFIG_STRUCTURE_CONTENTS_EMPTY_DIRECTORY,

733)                     path=item_path,

734)                 ),

735)             )

736)             _store(config_structure, item_path, b'{}')

737)         else:
738)             logger.debug(

739)                 _msg.TranslatedString(
740)                     _msg.DebugMsgTemplate.SETTING_CONFIG_STRUCTURE_CONTENTS,

741)                     path=item_path,

742)                     value=json_content.decode('utf-8'),
743)                 ),

744)             )

745)             _store(config_structure, item_path, json_content)

746)     logger.info(
747)         _msg.TranslatedString(
748)             _msg.InfoMsgTemplate.CHECKING_CONFIG_STRUCTURE_CONSISTENCY,
749)         )
750)     )

751)     # Sorted order is important; see `maybe_obj` below.

752)     for dir_, namelist_ in sorted(dirs_to_check.items()):
753)         namelist = [x.rstrip('/') for x in namelist_]

754)         obj: dict[Any, Any] = config_structure

755)         for part in dir_.split('/'):

756)             if part:
757)                 # Because we iterate paths in sorted order, parent
758)                 # directories are encountered before child directories.
759)                 # So parent directories always exist (lest we would have
760)                 # aborted earlier).
761)                 #
762)                 # Of course, the type checker doesn't necessarily know
763)                 # this, so we need to use assertions anyway.
764)                 maybe_obj = obj.get(part)

765)                 assert isinstance(maybe_obj, dict), (

766)                     f'Cannot traverse storage path {dir_!r}'

767)                 )

768)                 obj = maybe_obj

769)         if set(obj.keys()) != set(namelist):

770)             msg = f'Object key mismatch for path {dir_!r}'

771)             raise RuntimeError(msg)

772)         logger.debug(
773)             _msg.TranslatedString(
774)                 _msg.DebugMsgTemplate.DIRECTORY_CONTENTS_CHECK_OK,

775)                 path=dir_,
776)                 contents=json.dumps(namelist_),

777)             )
778)         )

779)     return config_structure

780) 
781) 
782) if __name__ == '__main__':

783)     logging.basicConfig(level=('DEBUG' if os.getenv('DEBUG') else 'WARNING'))

784)     config_structure = export_storeroom_data(format='storeroom')