derivepassphrase.git

@@ -132,19 +132,70 @@ class Vault:

         for _ in range(len(self._required), self._length):

             self._required.append(bytes(self._allowed))

-    def _entropy_upper_bound(self) -> int:

+    def _entropy(self) -> float:

         """Estimate the passphrase entropy, given the current settings.

         The entropy is the base 2 logarithm of the amount of

-        possibilities.  We operate directly on the logarithms, and round

-        each summand up, overestimating the true entropy.

+        possibilities.  We operate directly on the logarithms, and use

+        sorting and [`math.fsum`][] to keep high accuracy.

+

+        Note:

+            We actually overestimate the entropy here because of poor

+            handling of character repetitions.  In the extreme, assuming

+            that only one character were allowed, then because there is

+            only one possible string of each given length, the entropy

+            of that string `s` is always be zero.  However, we calculate

+            the entropy as `math.log2(math.factorial(len(s)))`, i.e. we

+            assume the characters at the respective string position are

+            distinguishable from each other.

+

+        Returns:

+            A valid (and somewhat close) upper bound to the entropy.

         """

         factors: list[int] = []

+        if not self._required or any(not x for x in self._required):

+            return float('-inf')

         for i, charset in enumerate(self._required):

             factors.append(i + 1)

             factors.append(len(charset))

-        return sum(int(math.ceil(math.log2(f))) for f in factors)

+        factors.sort()

+        return math.fsum(math.log2(f) for f in factors)

+

+    def _estimate_sufficient_hash_length(

+        self, safety_factor: float = 2.0,

+    ) -> int:

+        """Estimate the sufficient hash length, given the current settings.

+

+        Using the entropy (via `_entropy`) and a safety factor, give an

+        initial estimate of the length to use for `create_hash` such

+        that using a `Sequin` with this hash will not exhaust it during

+        passphrase generation.

+

+        Args:

+            safety_factor: The safety factor.  Must be at least 1.

+

+        Returns:

+            The estimated sufficient hash length.

+

+        Warning:

+            This is a heuristic, not an exact computation; it may

+            underestimate the true necessary hash length.  It is

+            intended as a starting point for searching for a sufficient

+            hash length, usually by doubling the hash length each time

+            it does not yet prove so.

+

+        """

+        try:

+            safety_factor = float(safety_factor)

+        except TypeError as e:

+            raise TypeError(f'invalid safety factor: not a float: '

+                            f'{safety_factor!r}') from e

+        if not math.isfinite(safety_factor) or safety_factor < 1.0:

+            raise ValueError(f'invalid safety factor {safety_factor!r}')

+        # Ensure the bound is strictly positive.

+        entropy_bound = max(1, self._entropy())

+        return int(math.ceil(safety_factor * entropy_bound / 8))

     @classmethod

     def create_hash(

@@ -225,12 +276,8 @@ class Vault:

             b': 4TVH#5:aZl8LueOT\\{'

         """

-        entropy_bound = self._entropy_upper_bound()

-        # Use a safety factor, because a sequin will potentially throw

-        # bits away and we cannot rely on having generated a hash of

-        # exactly the right length.

-        safety_factor = 2

-        hash_length = int(math.ceil(safety_factor * entropy_bound / 8))

+        hash_length = self._estimate_sufficient_hash_length()

+        assert hash_length >= 1

         # Ensure the phrase is a bytes object.  Needed later for safe

         # concatenation.

         if isinstance(service_name, str):

@@ -267,11 +314,36 @@ class Vault:

                                                      charset)

                     pos = seq.generate(len(charset))

                     result.extend(charset[pos:pos+1])

-            except sequin.SequinExhaustedException:  # pragma: no cover

+            except sequin.SequinExhaustedException:

                 hash_length *= 2

             else:

                 return bytes(result)

+    @staticmethod

+    def _is_suitable_ssh_key(key: bytes | bytearray, /) -> bool:

+        """Check whether the key is suitable for passphrase derivation.

+

+        Currently, this only checks whether signatures with this key

+        type are deterministic.

+

+        Args:

+            key: SSH public key to check.

+

+        Returns:

+            True if and only if the key is suitable for use in deriving

+            a passphrase deterministically.

+

+        """

+        deterministic_signature_types = {

+            'ssh-ed25519':

+                lambda k: k.startswith(b'\x00\x00\x00\x0bssh-ed25519'),

+            'ssh-ed448':

+                lambda k: k.startswith(b'\x00\x00\x00\x09ssh-ed448'),

+            'ssh-rsa':

+                lambda k: k.startswith(b'\x00\x00\x00\x07ssh-rsa'),

+        }

+        return any(v(key) for v in deterministic_signature_types.values())

+

     @classmethod

     def phrase_from_signature(

         cls, key: bytes | bytearray, /

@@ -314,15 +386,7 @@ class Vault:

             True

         """

-        deterministic_signature_types = {

-            'ssh-ed25519':

-                lambda k: k.startswith(b'\x00\x00\x00\x0bssh-ed25519'),

-            'ssh-ed448':

-                lambda k: k.startswith(b'\x00\x00\x00\x09ssh-ed448'),

-            'ssh-rsa':

-                lambda k: k.startswith(b'\x00\x00\x00\x07ssh-rsa'),

-        }

-        if not any(v(key) for v in deterministic_signature_types.values()):

+        if not cls._is_suitable_ssh_key(key):

             raise ValueError(

                 'unsuitable SSH key: bad key, or signature not deterministic')

         with ssh_agent_client.SSHAgentClient() as client:

@@ -4,17 +4,22 @@

 """Test passphrase generation via derivepassphrase.Vault."""

-import pytest

+from __future__ import annotations

+

+import math

 import derivepassphrase

 import sequin

+import pytest

 Vault = derivepassphrase.Vault

 phrase = b'She cells C shells bye the sea shoars'

+google_phrase = rb': 4TVH#5:aZl8LueOT\{'

+twitter_phrase = rb"[ (HN_N:lI&<ro=)3'g9"

-@pytest.mark.parametrize('service,expected', [

-    (b'google', rb': 4TVH#5:aZl8LueOT\{'),

-    ('twitter', rb"[ (HN_N:lI&<ro=)3'g9"),

+@pytest.mark.parametrize(['service', 'expected'], [

+    (b'google', google_phrase),

+    ('twitter', twitter_phrase),

 ])

 def test_200_basic_configuration(service, expected):

     assert Vault(phrase=phrase).generate(service) == expected

@@ -122,3 +127,71 @@ def test_301_character_set_subtraction_duplicate():

         Vault._subtract(b'abcdef', b'aabbccddeeff')

     with pytest.raises(ValueError, match='duplicate characters'):

         Vault._subtract(b'aabbccddeeff', b'abcdef')

+

+@pytest.mark.parametrize(['length', 'settings', 'entropy'], [

+    (20, {}, math.log2(math.factorial(20)) + 20 * math.log2(94)),

+    (

+        20,

+        {'upper': 0, 'number': 0, 'space': 0, 'symbol': 0},

+        math.log2(math.factorial(20)) + 20 * math.log2(26)

+    ),

+    (0, {}, float('-inf')),

+    (0, {'lower': 0, 'number': 0, 'space': 0, 'symbol': 0}, float('-inf')),

+    (1, {}, math.log2(94)),

+    (1, {'upper': 0, 'lower': 0, 'number': 0, 'symbol': 0}, 0.0),

+])

+def test_400_entropy(

+    length: int, settings: dict[str, int], entropy: int

+) -> None:

+    v = Vault(length=length, **settings)

+    assert math.isclose(v._entropy(), entropy)

+    assert v._estimate_sufficient_hash_length() > 0

+    if math.isfinite(entropy) and entropy:

+        assert v._estimate_sufficient_hash_length(1.0) == math.ceil(entropy / 8)

+    assert v._estimate_sufficient_hash_length(8.0) >= entropy

+

+def test_401_hash_length_estimation(

+) -> None:

+    v = Vault(phrase=phrase)

+    with pytest.raises(ValueError,

+                       match='invalid safety factor'):

+        assert v._estimate_sufficient_hash_length(-1.0)

+    with pytest.raises(TypeError,

+                       match='invalid safety factor: not a float'):

+        assert v._estimate_sufficient_hash_length(None)  # type: ignore

+    v2 = Vault(phrase=phrase, lower=0, upper=0, number=0, symbol=0,

+               space=1, length=1)

+    assert v2._entropy() == 0.0

+    assert v2._estimate_sufficient_hash_length() > 0

+

+@pytest.mark.parametrize(['service', 'expected'], [

+    (b'google', google_phrase),

+    ('twitter', twitter_phrase),

+])

+def test_402_hash_length_expansion(

+    monkeypatch: Any, service: str | bytes, expected: bytes

+) -> None:

+    v = Vault(phrase=phrase)

+    monkeypatch.setattr(v,

+                        '_estimate_sufficient_hash_length',

+                        lambda *args, **kwargs: 1)

+    assert v._estimate_sufficient_hash_length

+    assert v.generate(service) == expected

+

+@pytest.mark.parametrize(['s', 'raises'], [

+    ('ñ', True), ('Düsseldorf', True),

+    ('liberté, egalité, fraternité', True), ('ASCII', False),

+    ('Düsseldorf'.encode('UTF-8'), False),

+    (bytearray([2, 3, 5, 7, 11, 13]), False),

+])

+def test_403_binary_strings(s: str | bytes | bytearray, raises: bool) -> None:

+    binstr = derivepassphrase.Vault._get_binary_string

+    if raises:

+        with pytest.raises(derivepassphrase.AmbiguousByteRepresentationError):

+            binstr(s)

+    elif isinstance(s, str):

+        assert binstr(s) == s.encode('UTF-8')

+        assert binstr(binstr(s)) == s.encode('UTF-8')

+    else:

+        assert binstr(s) == bytes(s)

+        assert binstr(binstr(s)) == bytes(s)