Make the "storeroom" module's helper functions private but documented
Marco Ricci

Marco Ricci commited on 2025-01-19 21:10:38
Zeige 2 geänderte Dateien mit 23 Einfügungen und 14 Löschungen.

... ...
@@ -5,6 +5,15 @@
5 5
 ::: derivepassphrase.exporter.storeroom
6 6
     options:
7 7
       heading_level: 2
8
+      filters:
9
+        - "^[A-Za-z0-9]"
10
+        - "^__[a-zA-Z0-9_-]+__"
11
+        - "^_derive_master_keys_keys$"
12
+        - "^_decrypt_master_keys_data$"
13
+        - "^_decrypt_session_keys$"
14
+        - "^_decrypt_contents$"
15
+        - "^_decrypt_bucket_item$"
16
+        - "^_decrypt_bucket_file$"
8 17
 
9 18
 ::: derivepassphrase.exporter.vault_native
10 19
     options:
... ...
@@ -258,7 +258,7 @@ def _h(bs: Buffer) -> str:
258 258
     return '<{}>'.format(memoryview(bs).hex(' '))
259 259
 
260 260
 
261
-def derive_master_keys_keys(
261
+def _derive_master_keys_keys(
262 262
     password: str | Buffer,
263 263
     iterations: int,
264 264
 ) -> _types.StoreroomKeyPair:
... ...
@@ -318,7 +318,7 @@ def derive_master_keys_keys(
318 318
     ).toreadonly()
319 319
 
320 320
 
321
-def decrypt_master_keys_data(
321
+def _decrypt_master_keys_data(
322 322
     data: Buffer,
323 323
     keys: _types.StoreroomKeyPair,
324 324
 ) -> _types.StoreroomMasterKeys:
... ...
@@ -348,7 +348,7 @@ def decrypt_master_keys_data(
348 348
         keys:
349 349
             The encryption and signing keys for the master keys data.
350 350
             These should have previously been derived via the
351
-            [`derive_master_keys_keys`][] function.
351
+            [`_derive_master_keys_keys`][] function.
352 352
 
353 353
     Returns:
354 354
         The master encryption, signing and hashing keys.
... ...
@@ -413,7 +413,7 @@ def decrypt_master_keys_data(
413 413
     ).toreadonly()
414 414
 
415 415
 
416
-def decrypt_session_keys(
416
+def _decrypt_session_keys(
417 417
     data: Buffer,
418 418
     master_keys: _types.StoreroomMasterKeys,
419 419
 ) -> _types.StoreroomKeyPair:
... ...
@@ -441,7 +441,7 @@ def decrypt_session_keys(
441 441
             The encrypted bucket item session key data.
442 442
         master_keys:
443 443
             The master keys.  Presumably these have previously been
444
-            obtained via the [`decrypt_master_keys_data`][] function.
444
+            obtained via the [`_decrypt_master_keys_data`][] function.
445 445
 
446 446
     Returns:
447 447
         The bucket item's encryption and signing keys.
... ...
@@ -524,7 +524,7 @@ def decrypt_session_keys(
524 524
     return session_keys
525 525
 
526 526
 
527
-def decrypt_contents(
527
+def _decrypt_contents(
528 528
     data: Buffer,
529 529
     session_keys: _types.StoreroomKeyPair,
530 530
 ) -> Buffer:
... ...
@@ -547,7 +547,7 @@ def decrypt_contents(
547 547
             The encrypted bucket item payload data.
548 548
         session_keys:
549 549
             The bucket item's session keys.  Presumably these have
550
-            previously been obtained via the [`decrypt_session_keys`][]
550
+            previously been obtained via the [`_decrypt_session_keys`][]
551 551
             function.
552 552
 
553 553
     Returns:
... ...
@@ -613,7 +613,7 @@ def decrypt_contents(
613 613
     return plaintext
614 614
 
615 615
 
616
-def decrypt_bucket_item(
616
+def _decrypt_bucket_item(
617 617
     bucket_item: Buffer,
618 618
     master_keys: _types.StoreroomMasterKeys,
619 619
 ) -> Buffer:
... ...
@@ -624,7 +624,7 @@ def decrypt_bucket_item(
624 624
             The encrypted bucket item.
625 625
         master_keys:
626 626
             The master keys.  Presumably these have previously been
627
-            obtained via the [`decrypt_master_keys_data`][] function.
627
+            obtained via the [`_decrypt_master_keys_data`][] function.
628 628
 
629 629
     Returns:
630 630
         The decrypted bucket item.
... ...
@@ -664,11 +664,11 @@ def decrypt_bucket_item(
664 664
     if data_version != 1:
665 665
         msg = f'Cannot handle version {data_version} encrypted data'
666 666
         raise ValueError(msg)
667
-    session_keys = decrypt_session_keys(encrypted_session_keys, master_keys)
668
-    return decrypt_contents(data_contents, session_keys)
667
+    session_keys = _decrypt_session_keys(encrypted_session_keys, master_keys)
668
+    return _decrypt_contents(data_contents, session_keys)
669 669
 
670 670
 
671
-def decrypt_bucket_file(
671
+def _decrypt_bucket_file(
672 672
     filename: str,
673 673
     master_keys: _types.StoreroomMasterKeys,
674 674
     *,
... ...
@@ -681,7 +681,7 @@ def decrypt_bucket_file(
681 681
             The bucket file's filename.
682 682
         master_keys:
683 683
             The master keys.  Presumably these have previously been
684
-            obtained via the [`decrypt_master_keys_data`][] function.
684
+            obtained via the [`_decrypt_master_keys_data`][] function.
685 685
         root_dir:
686 686
             The root directory of the data store.  The filename is
687 687
             interpreted relatively to this directory.
... ...
@@ -718,7 +718,7 @@ def decrypt_bucket_file(
718 718
             msg = f'Invalid bucket file: {filename}'
719 719
             raise ValueError(msg) from None
720 720
         for line in bucket_file:
721
-            yield decrypt_bucket_item(
721
+            yield _decrypt_bucket_item(
722 722
                 base64.standard_b64decode(line), master_keys
723 723
             )
724 724
 
725 725