derivepassphrase.git

@@ -569,6 +569,11 @@ class SSH_AGENTC(enum.Enum):  # noqa: N801

             Remove an (SSH2) identity.

         ADD_ID_CONSTRAINED:

             Add an (SSH2) identity, including key constraints.

+        EXTENSION:

+            Issue a named request that isn't part of the core agent

+            protocol.  Expecting [`SSH_AGENT.EXTENSION_RESPONSE`][] or

+            [`SSH_AGENT.EXTENSION_FAILURE`][] if the named request is

+            supported, [`SSH_AGENT.FAILURE`][] otherwise.

     """

@@ -582,6 +587,8 @@ class SSH_AGENTC(enum.Enum):  # noqa: N801

     """"""

     ADD_ID_CONSTRAINED: int = 25

     """"""

+    EXTENSION: int = 27

+    """"""

 class SSH_AGENT(enum.Enum):  # noqa: N801

@@ -596,6 +603,10 @@ class SSH_AGENT(enum.Enum):  # noqa: N801

             Successful answer to [`SSH_AGENTC.REQUEST_IDENTITIES`][].

         SIGN_RESPONSE:

             Successful answer to [`SSH_AGENTC.SIGN_REQUEST`][].

+        EXTENSION_FAILURE:

+            Unsuccessful answer to [`SSH_AGENTC.EXTENSION`][].

+        EXTENSION_RESPONSE:

+            Successful answer to [`SSH_AGENTC.EXTENSION`][].

     """

@@ -607,3 +618,7 @@ class SSH_AGENT(enum.Enum):  # noqa: N801

     """"""

     SIGN_RESPONSE: int = 14

     """"""

+    EXTENSION_FAILURE: int = 28

+    """"""

+    EXTENSION_RESPONSE: int = 29

+    """"""

@@ -338,6 +338,25 @@ class SSHAgentClient:

             msg = f'invalid connection hint: {conn!r}'

             raise TypeError(msg)  # noqa: DOC501

+    def has_deterministic_signatures(self) -> bool:

+        """Check whether the agent returns deterministic signatures.

+

+        Returns:

+            True if a known agent was detected where signatures are

+            deterministic for all SSH key types, false otherwise.

+

+        Note: Known agents with deterministic signatures

+            | agent           | detected via                                                  |

+            |:----------------|:--------------------------------------------------------------|

+            | Pageant (PuTTY) | `list-extended@putty.projects.tartarus.org` extension request |

+

+        """  # noqa: E501

+        returncode, _payload = self.request(

+            _types.SSH_AGENTC.EXTENSION,

+            self.string(b'list-extended@putty.projects.tartarus.org'),

+        )

+        return returncode == _types.SSH_AGENT.SUCCESS.value

+

     @overload

     def request(  # pragma: no cover

         self,

@@ -18,6 +18,7 @@ from typing_extensions import TypeAlias, assert_type

 from derivepassphrase import sequin, ssh_agent

 if TYPE_CHECKING:

+    import socket

     from collections.abc import Callable

 __author__ = 'Marco Ricci <software@the13thletter.info>'

@@ -449,15 +450,20 @@ class Vault:

     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.

+        Currently, this only statically checks whether signatures with

+        this key type are guaranteed to be 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.

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

+            deriving a passphrase deterministically.

+

+        Note:

+            Some SSH agents additionally guarantee that all signatures

+            are deterministic and thus *all* keys are suitable; see

+            [`ssh_agent.SSHAgentClient.has_deterministic_signatures`][].

         """

         TestFunc: TypeAlias = 'Callable[[bytes | bytearray], bool]'

@@ -472,21 +478,42 @@ class Vault:

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

     @classmethod

-    def phrase_from_key(cls, key: bytes | bytearray, /) -> bytes:

+    def phrase_from_key(

+        cls,

+        key: bytes | bytearray,

+        /,

+        *,

+        conn: ssh_agent.SSHAgentClient | socket.socket | None = None,

+    ) -> bytes:

         """Obtain the master passphrase from a configured SSH key.

         vault allows the usage of certain SSH keys to derive a master

         passphrase, by signing the vault UUID with the SSH key.  The key

-        type must ensure that signatures are deterministic.

+        type or the SSH agent must ensure that signatures are

+        deterministic.

         Args:

-            key: The (public) SSH key to use for signing.

+            key:

+                The (public) SSH key to use for signing.

+            conn:

+                An optional connection hint to the SSH agent.  See

+                [`ssh_agent.SSHAgentClient.ensure_agent_subcontext`][].

         Returns:

             The signature of the vault UUID under this key, unframed but

             encoded in base64.

         Raises:

+            KeyError:

+                `conn` was `None`, and the `SSH_AUTH_SOCK` environment

+                variable was not found.

+            NotImplementedError:

+                `conn` was `None`, and this Python does not support

+                [`socket.AF_UNIX`][], so the SSH agent client cannot be

+                automatically set up.

+            OSError:

+                `conn` was a socket or `None`, and there was an error

+                setting up a socket connection to the agent.

             ValueError:

                 The SSH key is principally unsuitable for this use case.

                 Usually this means that the signature is not

@@ -516,13 +543,16 @@ class Vault:

             True

         """

-        if not cls._is_suitable_ssh_key(key):

+        with ssh_agent.SSHAgentClient.ensure_agent_subcontext(conn) as client:

+            if not (

+                client.has_deterministic_signatures()

+                or cls._is_suitable_ssh_key(key)

+            ):

                 msg = (

                     'unsuitable SSH key: bad key, or '

-                'signature not deterministic'

+                    'signature not deterministic under this agent'

                 )

                 raise ValueError(msg)

-        with ssh_agent.SSHAgentClient.ensure_agent_subcontext() as client:

             raw_sig = client.sign(key, cls._UUID)

         _keytype, trailer = ssh_agent.SSHAgentClient.unstring_prefix(raw_sig)

         signature_blob = ssh_agent.SSHAgentClient.unstring(trailer)