twisted.conch.ssh.transport.SSHTransportBase

class documentation

class SSHTransportBase(protocol.Protocol): (source)

Known subclasses: twisted.conch.ssh.transport.SSHClientTransport, twisted.conch.ssh.transport.SSHServerTransport

Protocol supporting basic SSH functionality: sending/receiving packets and message dispatch. To connect to or run a server, you must use SSHClientTransport or SSHServerTransport.

Method	`connectionLost`	When the underlying connection is closed, stop the running service (if any), and log out the avatar (if any).
Method	`connectionMade`	Called when the connection is made to the other side. We sent our version and the MSG_KEXINIT packet.
Method	`dataReceived`	First, check for the version string (SSH-2.0-*). After that has been received, this method adds data to the buffer, and pulls out any packets.
Method	`dispatchMessage`	Send a received message to the appropriate method.
Method	`getHost`	Returns an `SSHTransportAddress` corresponding to the this side of transport.
Method	`getPacket`	Try to return a decrypted, authenticated, and decompressed packet out of the buffer. If there is not enough data, return None.
Method	`getPeer`	Returns an `SSHTransportAddress` corresponding to the other (peer) side of this transport.
Method	`isEncrypted`	Check if the connection is encrypted in the given direction.
Method	`isVerified`	Check if the connection is verified/authentication in the given direction.
Method	`kexAlg.setter`	Set the key exchange algorithm name.
Method	`loseConnection`	Lose the connection to the other side, sending a DISCONNECT_CONNECTION_LOST message.
Method	`receiveDebug`	Called when we receive a debug message from the other side.
Method	`receiveError`	Called when we receive a disconnect error message from the other side.
Method	`receiveUnimplemented`	Called when we receive an unimplemented packet message from the other side.
Method	`sendDebug`	Send a debug message to the other side.
Method	`sendDisconnect`	Send a disconnect message to the other side and then disconnect.
Method	`sendIgnore`	Send a message that will be ignored by the other side. This is useful to fool attacks based on guessing packet sizes in the encrypted stream.
Method	`sendKexInit`	Send a KEXINIT message to initiate key exchange or to respond to a key exchange initiated by the peer.
Method	`sendPacket`	Sends a packet. If it's been set up, compress the data, encrypt it, and authenticate it before sending. If key exchange is in progress and the message is not part of key exchange, queue it to be sent later.
Method	`sendUnimplemented`	Send a message to the other side that the last packet was not understood.
Method	`setService`	Set our service to service and start it running. If we were running a service previously, stop it first.
Method	`ssh_DEBUG`	No summary
Method	`ssh_DISCONNECT`	Called when we receive a MSG_DISCONNECT message. Payload:: long code string description
Method	`ssh_IGNORE`	Called when we receive a MSG_IGNORE message. No payload. This means nothing; we simply return.
Method	`ssh_KEXINIT`	No summary
Method	`ssh_UNIMPLEMENTED`	Called when we receive a MSG_UNIMPLEMENTED message. Payload:: long packet
Instance Variable	`buf`	Data we've received but hasn't been parsed into a packet.
Instance Variable	`comment`	An optional string giving more information about the server or client.
Instance Variable	`currentEncryptions`	an SSHCiphers instance. It represents the current encryption and authentication options for the transport.
Instance Variable	`dhSecretKey`	Undocumented
Instance Variable	`dhSecretKeyPublicMP`	Undocumented
Instance Variable	`first`	the first bytes of the next packet. In order to avoid decrypting data twice, the first bytes are decrypted and stored until the whole packet is available.
Instance Variable	`gotVersion`	A boolean indicating whether we have received the version string from the other side.
Instance Variable	`incomingCompression`	an object supporting the .decompress(str) method, or None if there is no incoming compression. Used to decompress incoming data.
Instance Variable	`incomingCompressionType`	A string representing the incoming compression type.
Instance Variable	`incomingPacketSequence`	the sequence number of the next packet we are expecting from the other side.
Instance Variable	`isClient`	A boolean indicating whether this is a client or server.
Instance Variable	`kexAlg`	The key exchange algorithm name agreed between client and server.
Instance Variable	`keyAlg`	the agreed-upon public key type for the key exchange.
Instance Variable	`nextEncryptions`	an SSHCiphers instance. Held here until the MSG_NEWKEYS messages are exchanged, when nextEncryptions is transitioned to currentEncryptions.
Instance Variable	`otherKexInitPayload`	the MSG_KEXINIT payload we received. Used in the key exchange
Instance Variable	`otherVersionString`	the version string sent by the other side. Used in the key exchange.
Instance Variable	`ourKexInitPayload`	the MSG_KEXINIT payload we sent. Used in the key exchange.
Instance Variable	`ourVersionString`	the version string that we sent to the other side. Used in the key exchange.
Instance Variable	`outgoingCompression`	an object supporting the .compress(str) and .flush() methods, or None if there is no outgoing compression. Used to compress outgoing data.
Instance Variable	`outgoingCompressionType`	A string representing the outgoing compression type.
Instance Variable	`outgoingPacketSequence`	the sequence number of the next packet we will send.
Instance Variable	`protocolVersion`	A string representing the version of the SSH protocol we support. Currently defaults to '2.0'.
Instance Variable	`service`	an SSHService instance, or None. If it's set to an object, it's the currently running service.
Instance Variable	`sessionID`	a string that is unique to this SSH session. Created as part of the key exchange, sessionID is used to generate the various encryption and authentication keys.
Instance Variable	`supportedCiphers`	A list of strings representing the encryption algorithms supported, in order from most-preferred to least.
Instance Variable	`supportedCompressions`	A list of strings representing compression types supported, from most-preferred to least.
Instance Variable	`supportedKeyExchanges`	A list of strings representing the key exchanges supported, in order from most-preferred to least.
Instance Variable	`supportedLanguages`	A list of strings representing languages supported, from most-preferred to least.
Instance Variable	`supportedMACs`	A list of strings representing the message authentication codes (hashes) supported, in order from most-preferred to least. Both this and supportedCiphers can include 'none' to use no encryption or authentication, but that must be done manually,
Instance Variable	`supportedPublicKeys`	A list of strings representing the public key types supported, in order from most-preferred to least.
Instance Variable	`supportedVersions`	A container of strings representing supported ssh protocol version numbers.
Instance Variable	`version`	A string representing the version of the server or client. Currently defaults to 'Twisted'.
Method	`_allowedKeyExchangeMessageType`	Determine if the given message type may be sent while key exchange is in progress.
Method	`_encodeECPublicKey`	Encode an elliptic curve public key to bytes.
Method	`_finishEphemeralDH`	Completes the Diffie-Hellman key agreement started by _startEphemeralDH, and forgets the ephemeral secret key.
Method	`_generateECPrivateKey`	Generate an private key for ECDH key exchange.
Method	`_generateECSharedSecret`	Generate a shared secret for ECDH key exchange.
Method	`_getKey`	Get one of the keys for authentication/encryption.
Method	`_keySetup`	Set up the keys for the connection and sends MSG_NEWKEYS when finished,
Method	`_newKeys`	No summary
Method	`_startEphemeralDH`	Prepares for a Diffie-Hellman key agreement exchange.
Method	`_unsupportedVersionReceived`	Called when an unsupported version of the ssh protocol is received from the remote endpoint.
Constant	`_KEY_EXCHANGE_NONE`	Undocumented
Constant	`_KEY_EXCHANGE_PROGRESSING`	Undocumented
Constant	`_KEY_EXCHANGE_REQUESTED`	Undocumented
Class Variable	`_log`	Undocumented
Instance Variable	`_blockedByKeyExchange`	Whenever `_keyExchangeState` is not `_KEY_EXCHANGE_NONE`, this is a `list` of pending messages which were passed to `sendPacket` but could not be sent because it is not legal to send them while a key exchange is in progress. When the key exchange completes, another attempt is made to send these messages.
Instance Variable	`_kexAlg`	Undocumented
Instance Variable	`_keyExchangeState`	The current protocol state with respect to key exchange. This is either `_KEY_EXCHANGE_NONE` if no key exchange is in progress (and returns to this value after any key exchange completqes), `_KEY_EXCHANGE_REQUESTED` if this side of the connection initiated a key exchange, and `_KEY_EXCHANGE_PROGRESSING` if the other side of the connection initiated a key exchange. `_KEY_EXCHANGE_NONE` is the initial value (however SSH connections begin with key exchange, so it will quickly change to another state).

Inherited from Protocol:

Method	`logPrefix`	Return a prefix matching the class name, to identify log messages related to this protocol instance.
Class Variable	`factory`	Undocumented

Inherited from BaseProtocol (via Protocol):

Method	`makeConnection`	Make a connection to a transport and a server.
Instance Variable	`connected`	Undocumented
Instance Variable	`transport`	Undocumented

def connectionLost(self, reason): (source)

from twisted.internet.interfaces.IProtocol

overrides twisted.internet.protocol.Protocol.connectionLost

overridden in twisted.conch.client.direct.SSHClientTransport, twisted.conch.endpoints._CommandTransport

When the underlying connection is closed, stop the running service (if any), and log out the avatar (if any).

Parameters
reason:`twisted.python.failure.Failure`	The cause of the connection being closed.

def connectionMade(self): (source)

from twisted.internet.interfaces.IProtocol

overrides twisted.internet.protocol.BaseProtocol.connectionMade

overridden in twisted.conch.ssh.transport.SSHClientTransport

Called when the connection is made to the other side. We sent our version and the MSG_KEXINIT packet.

def dataReceived(self, data): (source)

from twisted.internet.interfaces.IProtocol

overrides twisted.internet.protocol.Protocol.dataReceived

First, check for the version string (SSH-2.0-*). After that has been received, this method adds data to the buffer, and pulls out any packets.

Parameters
data:`bytes`	The data that was received.

def dispatchMessage(self, messageNum, payload): (source)

Send a received message to the appropriate method.

Parameters
messageNum:`int`	The message number.
payload:`bytes`	The message payload.

def getHost(self): (source)

Returns an SSHTransportAddress corresponding to the this side of transport.

Returns
`SSHTransportAddress`	`SSHTransportAddress` for the peer
Present Since
12.1

def getPacket(self): (source)

Try to return a decrypted, authenticated, and decompressed packet out of the buffer. If there is not enough data, return None.

Returns
`str` or `None`	The decoded packet, if any.

def getPeer(self): (source)

Returns an SSHTransportAddress corresponding to the other (peer) side of this transport.

Returns
`SSHTransportAddress`	`SSHTransportAddress` for the peer
Present Since
12.1

def isEncrypted(self, direction='out'): (source)

Check if the connection is encrypted in the given direction.

Parameters
direction:`str`	The direction: one of 'out', 'in', or 'both'.
Returns
`bool`	`True` if it is encrypted.

def isVerified(self, direction='out'): (source)

Check if the connection is verified/authentication in the given direction.

Parameters
direction:`str`	The direction: one of 'out', 'in', or 'both'.
Returns
`bool`	`True` if it is verified.

@kexAlg.setter
def kexAlg(self, value): (source)

Set the key exchange algorithm name.

def loseConnection(self): (source)

Lose the connection to the other side, sending a DISCONNECT_CONNECTION_LOST message.

def receiveDebug(self, alwaysDisplay, message, lang): (source)

overridden in twisted.conch.client.direct.SSHClientTransport, twisted.conch.scripts.tkconch.SSHClientTransport

Called when we receive a debug message from the other side.

Parameters
alwaysDisplay:`bool`	if True, this message should always be displayed.
message:`str`	the debug message
lang:`str`	optionally the language the message is in.

def receiveError(self, reasonCode, description): (source)

overridden in twisted.conch.client.direct.SSHClientTransport, twisted.conch.scripts.tkconch.SSHClientTransport

Called when we receive a disconnect error message from the other side.

Parameters
reasonCode:`int`	the reason for the disconnect, one of the DISCONNECT_ values.
description:`str`	a human-readable description of the disconnection.

def receiveUnimplemented(self, seqnum): (source)

Called when we receive an unimplemented packet message from the other side.

Parameters
seqnum:`int`	the sequence number that was not understood.

def sendDebug(self, message, alwaysDisplay=False, language=b''): (source)

Send a debug message to the other side.

Parameters
message:`str`	the message to send.
alwaysDisplay:`bool`	if True, tell the other side to always display this message.
language:`str`	optionally, the language the message is in.

def sendDisconnect(self, reason, desc): (source)

overridden in twisted.conch.client.direct.SSHClientTransport, twisted.conch.scripts.tkconch.SSHClientTransport

Send a disconnect message to the other side and then disconnect.

Parameters
reason:`int`	the reason for the disconnect. Should be one of the DISCONNECT_* values.
desc:`str`	a descrption of the reason for the disconnection.

def sendIgnore(self, message): (source)

Send a message that will be ignored by the other side. This is useful to fool attacks based on guessing packet sizes in the encrypted stream.

Parameters
message:`str`	data to send with the message

def sendKexInit(self): (source)

Send a KEXINIT message to initiate key exchange or to respond to a key exchange initiated by the peer.

Returns
`None`
Raises
`RuntimeError`	If a key exchange has already been started and it is not appropriate to send a KEXINIT message at this time.

def sendPacket(self, messageType, payload): (source)

Sends a packet. If it's been set up, compress the data, encrypt it, and authenticate it before sending. If key exchange is in progress and the message is not part of key exchange, queue it to be sent later.

Parameters
messageType:`int`	The type of the packet; generally one of the MSG_* values.
payload:`str`	The payload for the message.

def sendUnimplemented(self): (source)

Send a message to the other side that the last packet was not understood.

def setService(self, service): (source)

overridden in twisted.conch.client.direct.SSHClientTransport

Set our service to service and start it running. If we were running a service previously, stop it first.

Parameters
service:`SSHService`	The service to attach.

def ssh_DEBUG(self, packet): (source)

Called when we receive a MSG_DEBUG message. Payload:

    bool alwaysDisplay
    string message
    string language

This means the other side has passed along some debugging info.

Parameters
packet:`bytes`	The message data.

def ssh_DISCONNECT(self, packet): (source)

Called when we receive a MSG_DISCONNECT message. Payload:

    long code
    string description

This means that the other side has disconnected. Pass the message up and disconnect ourselves.

Parameters
packet:`bytes`	The message data.

def ssh_IGNORE(self, packet): (source)

Called when we receive a MSG_IGNORE message. No payload. This means nothing; we simply return.

Parameters
packet:`bytes`	The message data.

def ssh_KEXINIT(self, packet): (source)

overridden in twisted.conch.ssh.transport.SSHClientTransport, twisted.conch.ssh.transport.SSHServerTransport

Called when we receive a MSG_KEXINIT message. Payload:

    bytes[16] cookie
    string keyExchangeAlgorithms
    string keyAlgorithms
    string incomingEncryptions
    string outgoingEncryptions
    string incomingAuthentications
    string outgoingAuthentications
    string incomingCompressions
    string outgoingCompressions
    string incomingLanguages
    string outgoingLanguages
    bool firstPacketFollows
    unit32 0 (reserved)

Starts setting up the key exchange, keys, encryptions, and authentications. Extended by ssh_KEXINIT in SSHServerTransport and SSHClientTransport.

Parameters
packet:`bytes`	The message data.
Returns
A `tuple` of negotiated key exchange algorithms, key algorithms, and unhandled data, or `None` if something went wrong.

def ssh_UNIMPLEMENTED(self, packet): (source)

Called when we receive a MSG_UNIMPLEMENTED message. Payload:

    long packet

This means that the other side did not implement one of our packets.

Parameters
packet:`bytes`	The message data.

buf = (source)

Data we've received but hasn't been parsed into a packet.

comment: bytes = (source)

An optional string giving more information about the server or client.

currentEncryptions = (source)

an SSHCiphers instance. It represents the current encryption and authentication options for the transport.

dhSecretKey = (source)

Undocumented

dhSecretKeyPublicMP = (source)

Undocumented

first = (source)

the first bytes of the next packet. In order to avoid decrypting data twice, the first bytes are decrypted and stored until the whole packet is available.

gotVersion: bool = (source)

A boolean indicating whether we have received the version string from the other side.

incomingCompression = (source)

an object supporting the .decompress(str) method, or None if there is no incoming compression. Used to decompress incoming data.

incomingCompressionType = (source)

A string representing the incoming compression type.

incomingPacketSequence: int = (source)

the sequence number of the next packet we are expecting from the other side.

isClient: bool = (source)

overridden in twisted.conch.ssh.transport.SSHClientTransport, twisted.conch.ssh.transport.SSHServerTransport

A boolean indicating whether this is a client or server.

@property
kexAlg = (source)

The key exchange algorithm name agreed between client and server.

keyAlg = (source)

the agreed-upon public key type for the key exchange.

nextEncryptions = (source)

an SSHCiphers instance. Held here until the MSG_NEWKEYS messages are exchanged, when nextEncryptions is transitioned to currentEncryptions.

otherKexInitPayload = (source)

the MSG_KEXINIT payload we received. Used in the key exchange

otherVersionString = (source)

the version string sent by the other side. Used in the key exchange.

ourKexInitPayload = (source)

the MSG_KEXINIT payload we sent. Used in the key exchange.

ourVersionString = (source)

the version string that we sent to the other side. Used in the key exchange.

outgoingCompression = (source)

an object supporting the .compress(str) and .flush() methods, or None if there is no outgoing compression. Used to compress outgoing data.

outgoingCompressionType = (source)

A string representing the outgoing compression type.

outgoingPacketSequence: int = (source)

the sequence number of the next packet we will send.

protocolVersion: bytes = (source)

A string representing the version of the SSH protocol we support. Currently defaults to '2.0'.

service = (source)

an SSHService instance, or None. If it's set to an object, it's the currently running service.

sessionID = (source)

a string that is unique to this SSH session. Created as part of the key exchange, sessionID is used to generate the various encryption and authentication keys.

supportedCiphers = (source)

A list of strings representing the encryption algorithms supported, in order from most-preferred to least.

supportedCompressions: list[bytes] = (source)

A list of strings representing compression types supported, from most-preferred to least.

supportedKeyExchanges = (source)

A list of strings representing the key exchanges supported, in order from most-preferred to least.

supportedLanguages: tuple = (source)

A list of strings representing languages supported, from most-preferred to least.

supportedMACs: list[bytes] = (source)

A list of strings representing the message authentication codes (hashes) supported, in order from most-preferred to least. Both this and supportedCiphers can include 'none' to use no encryption or authentication, but that must be done manually,

supportedPublicKeys: list = (source)

A list of strings representing the public key types supported, in order from most-preferred to least.

supportedVersions: tuple[bytes, ...] = (source)

A container of strings representing supported ssh protocol version numbers.

version = (source)

A string representing the version of the server or client. Currently defaults to 'Twisted'.

def _allowedKeyExchangeMessageType(self, messageType): (source)

Determine if the given message type may be sent while key exchange is in progress.

Parameters
messageType:`int`	The type of message
Returns
`bool`	`True` if the given type of message may be sent while key exchange is in progress, `False` if it may not.
See Also
http://tools.ietf.org/html/rfc4253#section-7.1

def _encodeECPublicKey(self, ecPub): (source)

Encode an elliptic curve public key to bytes.

Parameters
ecPub:The appropriate public key type matching `self.kexAlg`: `ec.EllipticCurvePublicKey` for `ecdh-sha2-nistp*`, or `x25519.X25519PublicKey` for `curve25519-sha256`.	The public key to encode.
Returns
`bytes`	The encoded public key.

def _finishEphemeralDH(self, remoteDHpublicKey): (source)

Completes the Diffie-Hellman key agreement started by _startEphemeralDH, and forgets the ephemeral secret key.

Parameters
remoteDHpublicKey:`int`	Undocumented
Returns
`bytes`	The new shared secret, in SSH `mpint` format.

def _generateECPrivateKey(self): (source)

Generate an private key for ECDH key exchange.

Returns
The appropriate private key type matching `self.kexAlg`: `ec.EllipticCurvePrivateKey` for `ecdh-sha2-nistp*`, or `x25519.X25519PrivateKey` for `curve25519-sha256`.	The generated private key.

def _generateECSharedSecret(self, ecPriv, theirECPubBytes): (source)

Generate a shared secret for ECDH key exchange.

Parameters
ecPriv:The appropriate private key type matching `self.kexAlg`: `ec.EllipticCurvePrivateKey` for `ecdh-sha2-nistp*`, or `x25519.X25519PrivateKey` for `curve25519-sha256`.	Our private key.
theirECPubBytes	Undocumented
Returns
`bytes`	The generated shared secret, as an SSH multiple-precision integer.

def _getKey(self, c, sharedSecret, exchangeHash): (source)

Get one of the keys for authentication/encryption.

Parameters
c:`bytes`	The letter identifying which key this is.
sharedSecret:`bytes`	The shared secret K.
exchangeHash:`bytes`	The hash H from key exchange.
Returns
`bytes`	The derived key.

def _keySetup(self, sharedSecret, exchangeHash): (source)

overridden in twisted.conch.ssh.transport.SSHClientTransport

Set up the keys for the connection and sends MSG_NEWKEYS when finished,

Parameters
sharedSecret:`str`	a secret string agreed upon using a Diffie- Hellman exchange, so it is only shared between the server and the client.
exchangeHash:`str`	A hash of various data known by both sides.

def _newKeys(self): (source)

Called back by a subclass once a MSG_NEWKEYS message has been received. This indicates key exchange has completed and new encryption and compression parameters should be adopted. Any messages which were queued during key exchange will also be flushed.

def _startEphemeralDH(self): (source)

Prepares for a Diffie-Hellman key agreement exchange.

Creates an ephemeral keypair in the group defined by (self.g, self.p) and stores it.

def _unsupportedVersionReceived(self, remoteVersion): (source)

Called when an unsupported version of the ssh protocol is received from the remote endpoint.

Parameters
remoteVersion:`str`	remote ssh protocol version which is unsupported by us.

_KEY_EXCHANGE_NONE: str = (source)

Undocumented

Value

'_KEY_EXCHANGE_NONE'

_KEY_EXCHANGE_PROGRESSING: str = (source)

Undocumented

Value

'_KEY_EXCHANGE_PROGRESSING'

_KEY_EXCHANGE_REQUESTED: str = (source)

Undocumented

Value

'_KEY_EXCHANGE_REQUESTED'

_log = (source)

Undocumented

_blockedByKeyExchange = (source)

Whenever _keyExchangeState is not _KEY_EXCHANGE_NONE, this is a list of pending messages which were passed to sendPacket but could not be sent because it is not legal to send them while a key exchange is in progress. When the key exchange completes, another attempt is made to send these messages.

_kexAlg = (source)

Undocumented

_keyExchangeState = (source)

The current protocol state with respect to key exchange. This is either _KEY_EXCHANGE_NONE if no key exchange is in progress (and returns to this value after any key exchange completqes), _KEY_EXCHANGE_REQUESTED if this side of the connection initiated a key exchange, and _KEY_EXCHANGE_PROGRESSING if the other side of the connection initiated a key exchange. _KEY_EXCHANGE_NONE is the initial value (however SSH connections begin with key exchange, so it will quickly change to another state).