derivepassphrase.git

src/ssh_agent_client/__init__.py             1) # SPDX-FileCopyrightText: 2024 Marco Ricci <m@the13thletter.info>
src/ssh_agent_client/__init__.py             2) #
src/ssh_agent_client/__init__.py             3) # SPDX-License-Identifier: MIT
src/ssh_agent_client/__init__.py             4) 
src/ssh_agent_client/__init__.py             5) """A bare-bones SSH agent client supporting signing and key listing."""
src/ssh_agent_client/__init__.py             6) 
src/ssh_agent_client/__init__.py             7) from __future__ import annotations
src/ssh_agent_client/__init__.py             8) 
src/ssh_agent_client/__init__.py             9) import collections
src/ssh_agent_client/__init__.py            10) import errno
src/ssh_agent_client/__init__.py            11) import os
src/ssh_agent_client/__init__.py            12) import socket

src/ssh_agent_client/__init__.py            13) from typing import TYPE_CHECKING

src/ssh_agent_client/__init__.py            14) 

src/ssh_agent_client/__init__.py            15) from typing_extensions import Self

src/ssh_agent_client/__init__.py            16) 

src/derivepassphrase/ssh_agent/__init__.py  17) from derivepassphrase import _types

src/ssh_agent_client/__init__.py            18) 
src/ssh_agent_client/__init__.py            19) if TYPE_CHECKING:
src/ssh_agent_client/__init__.py            20)     from collections.abc import Sequence

src/ssh_agent_client/__init__.py            21)     from types import TracebackType

src/ssh_agent_client/__init__.py            22) 
src/ssh_agent_client/__init__.py            23) __all__ = ('SSHAgentClient',)

src/ssh_agent_client/__init__.py            24) __author__ = 'Marco Ricci <m@the13thletter.info>'

src/ssh_agent_client/__init__.py            25) 

src/ssh_agent_client/__init__.py            26) # In SSH bytestrings, the "length" of the byte string is stored as
src/ssh_agent_client/__init__.py            27) # a 4-byte/32-bit unsigned integer at the beginning.
src/ssh_agent_client/__init__.py            28) HEAD_LEN = 4
src/ssh_agent_client/__init__.py            29) 

src/ssh_agent_client/__init__.py            30) _socket = socket
src/ssh_agent_client/__init__.py            31) 

src/ssh_agent_client/__init__.py            32) 

src/ssh_agent_client/__init__.py            33) class TrailingDataError(RuntimeError):
src/ssh_agent_client/__init__.py            34)     """The result contained trailing data."""

src/ssh_agent_client/__init__.py            35) 

src/ssh_agent_client/__init__.py            36)     def __init__(self) -> None:

src/ssh_agent_client/__init__.py            37)         super().__init__('Overlong response from SSH agent')

src/ssh_agent_client/__init__.py            38) 

src/ssh_agent_client/__init__.py            39) 

src/ssh_agent_client/__init__.py            40) class SSHAgentClient:
src/ssh_agent_client/__init__.py            41)     """A bare-bones SSH agent client supporting signing and key listing.
src/ssh_agent_client/__init__.py            42) 
src/ssh_agent_client/__init__.py            43)     The main use case is requesting the agent sign some data, after
src/ssh_agent_client/__init__.py            44)     checking that the necessary key is already loaded.
src/ssh_agent_client/__init__.py            45) 
src/ssh_agent_client/__init__.py            46)     The main fleshed out methods are `list_keys` and `sign`, which
src/ssh_agent_client/__init__.py            47)     implement the `REQUEST_IDENTITIES` and `SIGN_REQUEST` requests.  If
src/ssh_agent_client/__init__.py            48)     you *really* wanted to, there is enough infrastructure in place to
src/ssh_agent_client/__init__.py            49)     issue other requests as defined in the protocol---it's merely the
src/ssh_agent_client/__init__.py            50)     wrapper functions and the protocol numbers table that are missing.
src/ssh_agent_client/__init__.py            51) 
src/ssh_agent_client/__init__.py            52)     """

src/ssh_agent_client/__init__.py            53) 

src/ssh_agent_client/__init__.py            54)     _connection: socket.socket

src/ssh_agent_client/__init__.py            55) 

src/ssh_agent_client/__init__.py            56)     def __init__(
src/ssh_agent_client/__init__.py            57)         self, /, *, socket: socket.socket | None = None, timeout: int = 125
src/ssh_agent_client/__init__.py            58)     ) -> None:
src/ssh_agent_client/__init__.py            59)         """Initialize the client.
src/ssh_agent_client/__init__.py            60) 
src/ssh_agent_client/__init__.py            61)         Args:
src/ssh_agent_client/__init__.py            62)             socket:
src/ssh_agent_client/__init__.py            63)                 An optional socket, connected to the SSH agent.  If not
src/ssh_agent_client/__init__.py            64)                 given, we query the `SSH_AUTH_SOCK` environment
src/ssh_agent_client/__init__.py            65)                 variable to auto-discover the correct socket address.
src/ssh_agent_client/__init__.py            66)             timeout:
src/ssh_agent_client/__init__.py            67)                 A connection timeout for the SSH agent.  Only used if
src/ssh_agent_client/__init__.py            68)                 the socket is not yet connected.  The default value
src/ssh_agent_client/__init__.py            69)                 gives ample time for agent connections forwarded via
src/ssh_agent_client/__init__.py            70)                 SSH on high-latency networks (e.g. Tor).
src/ssh_agent_client/__init__.py            71) 

src/ssh_agent_client/__init__.py            72)         Raises:
src/ssh_agent_client/__init__.py            73)             KeyError:
src/ssh_agent_client/__init__.py            74)                 The `SSH_AUTH_SOCK` environment was not found.
src/ssh_agent_client/__init__.py            75)             OSError:
src/ssh_agent_client/__init__.py            76)                 There was an error setting up a socket connection to the
src/ssh_agent_client/__init__.py            77)                 agent.
src/ssh_agent_client/__init__.py            78) 

src/ssh_agent_client/__init__.py            79)         """
src/ssh_agent_client/__init__.py            80)         if socket is not None:

src/ssh_agent_client/__init__.py            81)             self._connection = socket

src/ssh_agent_client/__init__.py            82)         else:

src/ssh_agent_client/__init__.py            83)             self._connection = _socket.socket(family=_socket.AF_UNIX)

src/ssh_agent_client/__init__.py            84)         try:

src/ssh_agent_client/__init__.py            85)             # Test whether the socket is connected.
src/ssh_agent_client/__init__.py            86)             self._connection.getpeername()

src/ssh_agent_client/__init__.py            87)         except OSError as e:

src/ssh_agent_client/__init__.py            88)             # This condition is hard to test purposefully, so exclude
src/ssh_agent_client/__init__.py            89)             # from coverage.
src/ssh_agent_client/__init__.py            90)             if e.errno != errno.ENOTCONN:  # pragma: no cover

src/ssh_agent_client/__init__.py            91)                 raise

src/ssh_agent_client/__init__.py            92)             if 'SSH_AUTH_SOCK' not in os.environ:

src/ssh_agent_client/__init__.py            93)                 msg = 'SSH_AUTH_SOCK environment variable'
src/ssh_agent_client/__init__.py            94)                 raise KeyError(msg) from None

src/ssh_agent_client/__init__.py            95)             ssh_auth_sock = os.environ['SSH_AUTH_SOCK']

src/ssh_agent_client/__init__.py            96)             self._connection.settimeout(timeout)

src/ssh_agent_client/__init__.py            97)             self._connection.connect(ssh_auth_sock)

src/ssh_agent_client/__init__.py            98) 
src/ssh_agent_client/__init__.py            99)     def __enter__(self) -> Self:

src/ssh_agent_client/__init__.py           100)         """Close socket connection upon context manager completion."""
src/ssh_agent_client/__init__.py           101)         self._connection.__enter__()

src/ssh_agent_client/__init__.py           102)         return self
src/ssh_agent_client/__init__.py           103) 
src/ssh_agent_client/__init__.py           104)     def __exit__(

src/ssh_agent_client/__init__.py           105)         self,
src/ssh_agent_client/__init__.py           106)         exc_type: type[BaseException] | None,
src/ssh_agent_client/__init__.py           107)         exc_val: BaseException | None,

src/ssh_agent_client/__init__.py           108)         exc_tb: TracebackType | None,

src/ssh_agent_client/__init__.py           109)     ) -> bool:

src/ssh_agent_client/__init__.py           110)         """Close socket connection upon context manager completion."""

src/ssh_agent_client/__init__.py           111)         return bool(

src/ssh_agent_client/__init__.py           112)             self._connection.__exit__(exc_type, exc_val, exc_tb)  # type: ignore[func-returns-value]

src/ssh_agent_client/__init__.py           113)         )
src/ssh_agent_client/__init__.py           114) 
src/ssh_agent_client/__init__.py           115)     @staticmethod

src/ssh_agent_client/__init__.py           116)     def uint32(num: int, /) -> bytes:
src/ssh_agent_client/__init__.py           117)         r"""Format the number as a `uint32`, as per the agent protocol.
src/ssh_agent_client/__init__.py           118) 
src/ssh_agent_client/__init__.py           119)         Args:
src/ssh_agent_client/__init__.py           120)             num: A number.
src/ssh_agent_client/__init__.py           121) 
src/ssh_agent_client/__init__.py           122)         Returns:
src/ssh_agent_client/__init__.py           123)             The number in SSH agent wire protocol format, i.e. as
src/ssh_agent_client/__init__.py           124)             a 32-bit big endian number.
src/ssh_agent_client/__init__.py           125) 
src/ssh_agent_client/__init__.py           126)         Raises:
src/ssh_agent_client/__init__.py           127)             OverflowError:
src/ssh_agent_client/__init__.py           128)                 As per [`int.to_bytes`][].
src/ssh_agent_client/__init__.py           129) 
src/ssh_agent_client/__init__.py           130)         Examples:
src/ssh_agent_client/__init__.py           131)             >>> SSHAgentClient.uint32(16777216)
src/ssh_agent_client/__init__.py           132)             b'\x01\x00\x00\x00'
src/ssh_agent_client/__init__.py           133) 
src/ssh_agent_client/__init__.py           134)         """

src/ssh_agent_client/__init__.py           135)         return int.to_bytes(num, 4, 'big', signed=False)
src/ssh_agent_client/__init__.py           136) 
src/ssh_agent_client/__init__.py           137)     @classmethod
src/ssh_agent_client/__init__.py           138)     def string(cls, payload: bytes | bytearray, /) -> bytes | bytearray:

src/ssh_agent_client/__init__.py           139)         r"""Format the payload as an SSH string, as per the agent protocol.
src/ssh_agent_client/__init__.py           140) 
src/ssh_agent_client/__init__.py           141)         Args:
src/ssh_agent_client/__init__.py           142)             payload: A byte string.
src/ssh_agent_client/__init__.py           143) 
src/ssh_agent_client/__init__.py           144)         Returns:
src/ssh_agent_client/__init__.py           145)             The payload, framed in the SSH agent wire protocol format.
src/ssh_agent_client/__init__.py           146) 
src/ssh_agent_client/__init__.py           147)         Examples:
src/ssh_agent_client/__init__.py           148)             >>> bytes(SSHAgentClient.string(b'ssh-rsa'))
src/ssh_agent_client/__init__.py           149)             b'\x00\x00\x00\x07ssh-rsa'
src/ssh_agent_client/__init__.py           150) 
src/ssh_agent_client/__init__.py           151)         """

src/ssh_agent_client/__init__.py           152)         try:
src/ssh_agent_client/__init__.py           153)             ret = bytearray()
src/ssh_agent_client/__init__.py           154)             ret.extend(cls.uint32(len(payload)))
src/ssh_agent_client/__init__.py           155)             ret.extend(payload)
src/ssh_agent_client/__init__.py           156)         except Exception as e:

src/ssh_agent_client/__init__.py           157)             msg = 'invalid payload type'
src/ssh_agent_client/__init__.py           158)             raise TypeError(msg) from e
src/ssh_agent_client/__init__.py           159)         return ret

src/ssh_agent_client/__init__.py           160) 
src/ssh_agent_client/__init__.py           161)     @classmethod
src/ssh_agent_client/__init__.py           162)     def unstring(cls, bytestring: bytes | bytearray, /) -> bytes | bytearray:

src/ssh_agent_client/__init__.py           163)         r"""Unpack an SSH string.
src/ssh_agent_client/__init__.py           164) 
src/ssh_agent_client/__init__.py           165)         Args:
src/ssh_agent_client/__init__.py           166)             bytestring: A framed byte string.
src/ssh_agent_client/__init__.py           167) 
src/ssh_agent_client/__init__.py           168)         Returns:
src/ssh_agent_client/__init__.py           169)             The unframed byte string, i.e., the payload.
src/ssh_agent_client/__init__.py           170) 
src/ssh_agent_client/__init__.py           171)         Raises:
src/ssh_agent_client/__init__.py           172)             ValueError:

src/ssh_agent_client/__init__.py           173)                 The byte string is not an SSH string.

src/ssh_agent_client/__init__.py           174) 
src/ssh_agent_client/__init__.py           175)         Examples:
src/ssh_agent_client/__init__.py           176)             >>> bytes(SSHAgentClient.unstring(b'\x00\x00\x00\x07ssh-rsa'))
src/ssh_agent_client/__init__.py           177)             b'ssh-rsa'

src/ssh_agent_client/__init__.py           178)             >>> bytes(
src/ssh_agent_client/__init__.py           179)             ...     SSHAgentClient.unstring(SSHAgentClient.string(b'ssh-ed25519'))
src/ssh_agent_client/__init__.py           180)             ... )

src/ssh_agent_client/__init__.py           181)             b'ssh-ed25519'
src/ssh_agent_client/__init__.py           182) 

src/ssh_agent_client/__init__.py           183)         """  # noqa: E501

src/ssh_agent_client/__init__.py           184)         n = len(bytestring)

src/ssh_agent_client/__init__.py           185)         msg = 'malformed SSH byte string'

src/ssh_agent_client/__init__.py           186)         if n < HEAD_LEN or n != HEAD_LEN + int.from_bytes(
src/ssh_agent_client/__init__.py           187)             bytestring[:HEAD_LEN], 'big', signed=False

src/ssh_agent_client/__init__.py           188)         ):
src/ssh_agent_client/__init__.py           189)             raise ValueError(msg)
src/ssh_agent_client/__init__.py           190)         return bytestring[HEAD_LEN:]

src/ssh_agent_client/__init__.py           191) 

src/ssh_agent_client/__init__.py           192)     @classmethod
src/ssh_agent_client/__init__.py           193)     def unstring_prefix(
src/ssh_agent_client/__init__.py           194)         cls, bytestring: bytes | bytearray, /
src/ssh_agent_client/__init__.py           195)     ) -> tuple[bytes | bytearray, bytes | bytearray]:
src/ssh_agent_client/__init__.py           196)         r"""Unpack an SSH string at the beginning of the byte string.
src/ssh_agent_client/__init__.py           197) 
src/ssh_agent_client/__init__.py           198)         Args:
src/ssh_agent_client/__init__.py           199)             bytestring:
src/ssh_agent_client/__init__.py           200)                 A (general) byte string, beginning with a framed/SSH
src/ssh_agent_client/__init__.py           201)                 byte string.
src/ssh_agent_client/__init__.py           202) 
src/ssh_agent_client/__init__.py           203)         Returns:
src/ssh_agent_client/__init__.py           204)             A 2-tuple `(a, b)`, where `a` is the unframed byte
src/ssh_agent_client/__init__.py           205)             string/payload at the beginning of input byte string, and
src/ssh_agent_client/__init__.py           206)             `b` is the remainder of the input byte string.
src/ssh_agent_client/__init__.py           207) 
src/ssh_agent_client/__init__.py           208)         Raises:
src/ssh_agent_client/__init__.py           209)             ValueError:
src/ssh_agent_client/__init__.py           210)                 The byte string does not begin with an SSH string.
src/ssh_agent_client/__init__.py           211) 
src/ssh_agent_client/__init__.py           212)         Examples:
src/ssh_agent_client/__init__.py           213)             >>> a, b = SSHAgentClient.unstring_prefix(

src/ssh_agent_client/__init__.py           214)             ...     b'\x00\x00\x00\x07ssh-rsa____trailing data'
src/ssh_agent_client/__init__.py           215)             ... )

src/ssh_agent_client/__init__.py           216)             >>> (bytes(a), bytes(b))
src/ssh_agent_client/__init__.py           217)             (b'ssh-rsa', b'____trailing data')
src/ssh_agent_client/__init__.py           218)             >>> a, b = SSHAgentClient.unstring_prefix(

src/ssh_agent_client/__init__.py           219)             ...     SSHAgentClient.string(b'ssh-ed25519')
src/ssh_agent_client/__init__.py           220)             ... )

src/ssh_agent_client/__init__.py           221)             >>> (bytes(a), bytes(b))
src/ssh_agent_client/__init__.py           222)             (b'ssh-ed25519', b'')
src/ssh_agent_client/__init__.py           223) 
src/ssh_agent_client/__init__.py           224)         """
src/ssh_agent_client/__init__.py           225)         n = len(bytestring)

src/ssh_agent_client/__init__.py           226)         msg = 'malformed SSH byte string'
src/ssh_agent_client/__init__.py           227)         if n < HEAD_LEN:
src/ssh_agent_client/__init__.py           228)             raise ValueError(msg)
src/ssh_agent_client/__init__.py           229)         m = int.from_bytes(bytestring[:HEAD_LEN], 'big', signed=False)
src/ssh_agent_client/__init__.py           230)         if m + HEAD_LEN > n:
src/ssh_agent_client/__init__.py           231)             raise ValueError(msg)

src/ssh_agent_client/__init__.py           232)         return (
src/ssh_agent_client/__init__.py           233)             bytestring[HEAD_LEN : m + HEAD_LEN],
src/ssh_agent_client/__init__.py           234)             bytestring[m + HEAD_LEN :],
src/ssh_agent_client/__init__.py           235)         )

src/ssh_agent_client/__init__.py           236) 

src/ssh_agent_client/__init__.py           237)     def request(
src/ssh_agent_client/__init__.py           238)         self, code: int, payload: bytes | bytearray, /
src/ssh_agent_client/__init__.py           239)     ) -> tuple[int, bytes | bytearray]:
src/ssh_agent_client/__init__.py           240)         """Issue a generic request to the SSH agent.
src/ssh_agent_client/__init__.py           241) 
src/ssh_agent_client/__init__.py           242)         Args:
src/ssh_agent_client/__init__.py           243)             code:
src/ssh_agent_client/__init__.py           244)                 The request code.  See the SSH agent protocol for
src/ssh_agent_client/__init__.py           245)                 protocol numbers to use here (and which protocol numbers
src/ssh_agent_client/__init__.py           246)                 to expect in a response).
src/ssh_agent_client/__init__.py           247)             payload:
src/ssh_agent_client/__init__.py           248)                 A byte string containing the payload, or "contents", of
src/ssh_agent_client/__init__.py           249)                 the request.  Request-specific.  `request` will add any
src/ssh_agent_client/__init__.py           250)                 necessary wire framing around the request code and the
src/ssh_agent_client/__init__.py           251)                 payload.
src/ssh_agent_client/__init__.py           252) 
src/ssh_agent_client/__init__.py           253)         Returns:
src/ssh_agent_client/__init__.py           254)             A 2-tuple consisting of the response code and the payload,
src/ssh_agent_client/__init__.py           255)             with all wire framing removed.
src/ssh_agent_client/__init__.py           256) 
src/ssh_agent_client/__init__.py           257)         Raises:
src/ssh_agent_client/__init__.py           258)             EOFError:
src/ssh_agent_client/__init__.py           259)                 The response from the SSH agent is truncated or missing.
src/ssh_agent_client/__init__.py           260) 
src/ssh_agent_client/__init__.py           261)         """
src/ssh_agent_client/__init__.py           262)         request_message = bytearray([code])
src/ssh_agent_client/__init__.py           263)         request_message.extend(payload)

src/ssh_agent_client/__init__.py           264)         self._connection.sendall(self.string(request_message))

src/ssh_agent_client/__init__.py           265)         chunk = self._connection.recv(HEAD_LEN)
src/ssh_agent_client/__init__.py           266)         if len(chunk) < HEAD_LEN:
src/ssh_agent_client/__init__.py           267)             msg = 'cannot read response length'
src/ssh_agent_client/__init__.py           268)             raise EOFError(msg)

src/ssh_agent_client/__init__.py           269)         response_length = int.from_bytes(chunk, 'big', signed=False)

src/ssh_agent_client/__init__.py           270)         response = self._connection.recv(response_length)

src/ssh_agent_client/__init__.py           271)         if len(response) < response_length:

src/ssh_agent_client/__init__.py           272)             msg = 'truncated response from SSH agent'
src/ssh_agent_client/__init__.py           273)             raise EOFError(msg)

src/ssh_agent_client/__init__.py           274)         return response[0], response[1:]
src/ssh_agent_client/__init__.py           275) 

src/derivepassphrase/ssh_agent/__init__.py 276)     def list_keys(self) -> Sequence[_types.KeyCommentPair]:

src/ssh_agent_client/__init__.py           277)         """Request a list of keys known to the SSH agent.
src/ssh_agent_client/__init__.py           278) 
src/ssh_agent_client/__init__.py           279)         Returns:
src/ssh_agent_client/__init__.py           280)             A read-only sequence of key/comment pairs.
src/ssh_agent_client/__init__.py           281) 
src/ssh_agent_client/__init__.py           282)         Raises:
src/ssh_agent_client/__init__.py           283)             EOFError:
src/ssh_agent_client/__init__.py           284)                 The response from the SSH agent is truncated or missing.

src/ssh_agent_client/__init__.py           285)             TrailingDataError:

src/ssh_agent_client/__init__.py           286)                 The response from the SSH agent is too long.

src/ssh_agent_client/__init__.py           287)             RuntimeError:
src/ssh_agent_client/__init__.py           288)                 The agent failed to complete the request.

src/ssh_agent_client/__init__.py           289) 
src/ssh_agent_client/__init__.py           290)         """
src/ssh_agent_client/__init__.py           291)         response_code, response = self.request(

src/derivepassphrase/ssh_agent/__init__.py 292)             _types.SSH_AGENTC.REQUEST_IDENTITIES.value, b''

src/ssh_agent_client/__init__.py           293)         )

src/derivepassphrase/ssh_agent/__init__.py 294)         if response_code != _types.SSH_AGENT.IDENTITIES_ANSWER.value:

src/ssh_agent_client/__init__.py           295)             msg = (
src/ssh_agent_client/__init__.py           296)                 f'error return from SSH agent: '
src/ssh_agent_client/__init__.py           297)                 f'{response_code = }, {response = }'
src/ssh_agent_client/__init__.py           298)             )

src/ssh_agent_client/__init__.py           299)             raise RuntimeError(msg)

src/ssh_agent_client/__init__.py           300)         response_stream = collections.deque(response)

src/ssh_agent_client/__init__.py           301) 

src/ssh_agent_client/__init__.py           302)         def shift(num: int) -> bytes:

src/ssh_agent_client/__init__.py           303)             buf = collections.deque(b'')
src/ssh_agent_client/__init__.py           304)             for _ in range(num):

src/ssh_agent_client/__init__.py           305)                 try:
src/ssh_agent_client/__init__.py           306)                     val = response_stream.popleft()
src/ssh_agent_client/__init__.py           307)                 except IndexError:
src/ssh_agent_client/__init__.py           308)                     response_stream.extendleft(reversed(buf))

src/ssh_agent_client/__init__.py           309)                     msg = 'truncated response from SSH agent'
src/ssh_agent_client/__init__.py           310)                     raise EOFError(msg) from None

src/ssh_agent_client/__init__.py           311)                 buf.append(val)
src/ssh_agent_client/__init__.py           312)             return bytes(buf)

src/ssh_agent_client/__init__.py           313) 

src/ssh_agent_client/__init__.py           314)         key_count = int.from_bytes(shift(4), 'big')

src/derivepassphrase/ssh_agent/__init__.py 315)         keys: collections.deque[_types.KeyCommentPair]

src/ssh_agent_client/__init__.py           316)         keys = collections.deque()

src/ssh_agent_client/__init__.py           317)         for _ in range(key_count):

src/ssh_agent_client/__init__.py           318)             key_size = int.from_bytes(shift(4), 'big')
src/ssh_agent_client/__init__.py           319)             key = shift(key_size)
src/ssh_agent_client/__init__.py           320)             comment_size = int.from_bytes(shift(4), 'big')
src/ssh_agent_client/__init__.py           321)             comment = shift(comment_size)
src/ssh_agent_client/__init__.py           322)             # Both `key` and `comment` are not wrapped as SSH strings.

src/derivepassphrase/ssh_agent/__init__.py 323)             keys.append(_types.KeyCommentPair(key, comment))

src/ssh_agent_client/__init__.py           324)         if response_stream:

src/ssh_agent_client/__init__.py           325)             raise TrailingDataError

src/ssh_agent_client/__init__.py           326)         return keys
src/ssh_agent_client/__init__.py           327) 
src/ssh_agent_client/__init__.py           328)     def sign(

src/ssh_agent_client/__init__.py           329)         self,
src/ssh_agent_client/__init__.py           330)         /,
src/ssh_agent_client/__init__.py           331)         key: bytes | bytearray,
src/ssh_agent_client/__init__.py           332)         payload: bytes | bytearray,
src/ssh_agent_client/__init__.py           333)         *,
src/ssh_agent_client/__init__.py           334)         flags: int = 0,
src/ssh_agent_client/__init__.py           335)         check_if_key_loaded: bool = False,

src/ssh_agent_client/__init__.py           336)     ) -> bytes | bytearray:
src/ssh_agent_client/__init__.py           337)         """Request the SSH agent sign the payload with the key.
src/ssh_agent_client/__init__.py           338) 
src/ssh_agent_client/__init__.py           339)         Args:
src/ssh_agent_client/__init__.py           340)             key:
src/ssh_agent_client/__init__.py           341)                 The public SSH key to sign the payload with, in the same
src/ssh_agent_client/__init__.py           342)                 format as returned by, e.g., the `list_keys` method.
src/ssh_agent_client/__init__.py           343)                 The corresponding private key must have previously been
src/ssh_agent_client/__init__.py           344)                 loaded into the agent to successfully issue a signature.
src/ssh_agent_client/__init__.py           345)             payload:
src/ssh_agent_client/__init__.py           346)                 A byte string of data to sign.
src/ssh_agent_client/__init__.py           347)             flags:
src/ssh_agent_client/__init__.py           348)                 Optional flags for the signing request.  Currently
src/ssh_agent_client/__init__.py           349)                 passed on as-is to the agent.  In real-world usage, this
src/ssh_agent_client/__init__.py           350)                 could be used, e.g., to request more modern hash
src/ssh_agent_client/__init__.py           351)                 algorithms when signing with RSA keys.  (No such
src/ssh_agent_client/__init__.py           352)                 real-world usage is currently implemented.)
src/ssh_agent_client/__init__.py           353)             check_if_key_loaded:
src/ssh_agent_client/__init__.py           354)                 If true, check beforehand (via `list_keys`) if the
src/ssh_agent_client/__init__.py           355)                 corresponding key has been loaded into the agent.
src/ssh_agent_client/__init__.py           356) 
src/ssh_agent_client/__init__.py           357)         Returns:
src/ssh_agent_client/__init__.py           358)             The binary signature of the payload under the given key.
src/ssh_agent_client/__init__.py           359) 
src/ssh_agent_client/__init__.py           360)         Raises:
src/ssh_agent_client/__init__.py           361)             EOFError:
src/ssh_agent_client/__init__.py           362)                 The response from the SSH agent is truncated or missing.

src/ssh_agent_client/__init__.py           363)             TrailingDataError:

src/ssh_agent_client/__init__.py           364)                 The response from the SSH agent is too long.
src/ssh_agent_client/__init__.py           365)             RuntimeError:
src/ssh_agent_client/__init__.py           366)                 The agent failed to complete the request.

src/ssh_agent_client/__init__.py           367)             KeyError:

src/ssh_agent_client/__init__.py           368)                 `check_if_key_loaded` is true, and the `key` was not
src/ssh_agent_client/__init__.py           369)                 loaded into the agent.
src/ssh_agent_client/__init__.py           370) 
src/ssh_agent_client/__init__.py           371)         """
src/ssh_agent_client/__init__.py           372)         if check_if_key_loaded:
src/ssh_agent_client/__init__.py           373)             loaded_keys = frozenset({pair.key for pair in self.list_keys()})
src/ssh_agent_client/__init__.py           374)             if bytes(key) not in loaded_keys:

src/ssh_agent_client/__init__.py           375)                 msg = 'target SSH key not loaded into agent'
src/ssh_agent_client/__init__.py           376)                 raise KeyError(msg)

src/ssh_agent_client/__init__.py           377)         request_data = bytearray(self.string(key))
src/ssh_agent_client/__init__.py           378)         request_data.extend(self.string(payload))
src/ssh_agent_client/__init__.py           379)         request_data.extend(self.uint32(flags))
src/ssh_agent_client/__init__.py           380)         response_code, response = self.request(

src/derivepassphrase/ssh_agent/__init__.py 381)             _types.SSH_AGENTC.SIGN_REQUEST.value, request_data

src/ssh_agent_client/__init__.py           382)         )

src/derivepassphrase/ssh_agent/__init__.py 383)         if response_code != _types.SSH_AGENT.SIGN_RESPONSE.value:

src/ssh_agent_client/__init__.py           384)             msg = f'signing data failed: {response_code = }, {response = }'
src/ssh_agent_client/__init__.py           385)             raise RuntimeError(msg)