5. Channel Mechanism (Kanal-Mechanismus)

Alle Terminalsitzungen, weitergeleitete Verbindungen usw. sind Kanäle. Jede Seite kann einen Kanal öffnen. Mehrere Kanäle werden in eine einzige Verbindung multiplexiert.

Kanäle werden an jedem Ende durch Nummern identifiziert. Die Nummer, die sich auf einen Kanal bezieht, kann auf jeder Seite unterschiedlich sein. Anfragen zum Öffnen eines Kanals enthalten die Kanalnummer des Absenders. Alle anderen kanalbezogenen Nachrichten enthalten die Kanalnummer des Empfängers für den Kanal.

Kanäle sind flusskontrolliert. Es dürfen keine Daten an einen Kanal gesendet werden, bis eine Nachricht empfangen wird, die anzeigt, dass Fensterplatz verfügbar ist.

5.1. Opening a Channel

Wenn eine Seite einen neuen Kanal öffnen möchte, weist sie eine lokale Nummer für den Kanal zu. Sie sendet dann die folgende Nachricht an die andere Seite und fügt die lokale Kanalnummer und die anfängliche Fenstergröße in die Nachricht ein.

byte      SSH_MSG_CHANNEL_OPEN
string    channel type in US-ASCII only
uint32    sender channel
uint32    initial window size
uint32    maximum packet size
....      channel type specific data follows

Der channel type ist ein Name, wie in [SSH-ARCH] und [SSH-NUMBERS] beschrieben, mit ähnlichen Erweiterungsmechanismen. Der sender channel ist eine lokale Kennung für den Kanal, die vom Absender dieser Nachricht verwendet wird. Die initial window size gibt an, wie viele Bytes Kanaldaten an den Absender dieser Nachricht gesendet werden können, ohne das Fenster anzupassen. Die maximum packet size gibt die maximale Größe eines einzelnen Datenpakets an, das an den Absender gesendet werden kann. Beispielsweise könnte man kleinere Pakete für interaktive Verbindungen verwenden wollen, um eine bessere interaktive Reaktion bei langsamen Verbindungen zu erhalten.

Die entfernte Seite entscheidet dann, ob sie den Kanal öffnen kann, und antwortet entweder mit SSH_MSG_CHANNEL_OPEN_CONFIRMATION oder SSH_MSG_CHANNEL_OPEN_FAILURE.

byte      SSH_MSG_CHANNEL_OPEN_CONFIRMATION
uint32    recipient channel
uint32    sender channel
uint32    initial window size
uint32    maximum packet size
....      channel type specific data follows

Der recipient channel ist die Kanalnummer, die in der ursprünglichen Öffnungsanfrage angegeben wurde, und sender channel ist die von der anderen Seite zugewiesene Kanalnummer.

byte      SSH_MSG_CHANNEL_OPEN_FAILURE
uint32    recipient channel
uint32    reason code
string    description in ISO-10646 UTF-8 encoding [RFC3629]
string    language tag [RFC3066]

Wenn der Empfänger der SSH_MSG_CHANNEL_OPEN-Nachricht den angegebenen channel type nicht unterstützt, antwortet er einfach mit SSH_MSG_CHANNEL_OPEN_FAILURE. Der Client DARF die description-Zeichenkette dem Benutzer anzeigen. Wenn dies geschieht, sollte die Client-Software die in [SSH-ARCH] besprochenen Vorsichtsmaßnahmen treffen.

Die SSH_MSG_CHANNEL_OPEN_FAILURE reason code-Werte sind in der folgenden Tabelle definiert. Beachten Sie, dass die Werte für den reason code zur besseren Lesbarkeit im Dezimalformat angegeben sind, es sich jedoch tatsächlich um uint32-Werte handelt.

Symbolic name	reason code
`SSH_OPEN_ADMINISTRATIVELY_PROHIBITED`	1
`SSH_OPEN_CONNECT_FAILED`	2
`SSH_OPEN_UNKNOWN_CHANNEL_TYPE`	3
`SSH_OPEN_RESOURCE_SHORTAGE`	4

Anfragen zur Zuweisung neuer SSH_MSG_CHANNEL_OPEN reason code-Werte (und zugehörigem description-Text) im Bereich von 0x00000005 bis 0xFDFFFFFF MÜSSEN über die IETF CONSENSUS-Methode erfolgen, wie in [RFC2434] beschrieben. Die IANA wird keine Channel Connection Failure reason code-Werte im Bereich von 0xFE000000 bis 0xFFFFFFFF zuweisen. Channel Connection Failure reason code-Werte in diesem Bereich sind für PRIVATE USE reserviert, wie in [RFC2434] beschrieben.

Obwohl verstanden wird, dass die IANA keine Kontrolle über den Bereich von 0xFE000000 bis 0xFFFFFFFF haben wird, wird dieser Bereich in zwei Teile aufgeteilt und nach folgenden Konventionen verwaltet.

Der Bereich von 0xFE000000 bis 0xFEFFFFFF soll in Verbindung mit lokal zugewiesenen Kanälen verwendet werden. Wenn beispielsweise ein Kanal mit einem channel type von "[email protected]" vorgeschlagen wird, aber fehlschlägt, enthält die Antwort entweder einen von der IANA zugewiesenen reason code (wie oben aufgeführt und im Bereich von 0x00000001 bis 0xFDFFFFFF) oder einen lokal zugewiesenen Wert im Bereich von 0xFE000000 bis 0xFEFFFFFF. Natürlich MUSS, wenn der Server den vorgeschlagenen channel type nicht versteht, selbst wenn es sich um einen lokal definierten channel type handelt, der reason code 0x00000003 sein, wie oben beschrieben, wenn der reason code gesendet wird. Wenn der Server den channel type versteht, aber der Kanal dennoch nicht geöffnet werden kann, SOLLTE der Server mit einem lokal zugewiesenen reason code-Wert antworten, der mit dem vorgeschlagenen lokalen channel type übereinstimmt. Es wird angenommen, dass Praktiker zunächst versuchen werden, die von der IANA zugewiesenen reason code-Werte zu verwenden, und dann ihre lokal zugewiesenen reason code-Werte dokumentieren.
Es gibt keine Einschränkungen oder Vorschläge für den Bereich, der mit 0xFF beginnt. Für alles, was in diesem Bereich verwendet wird, wird keine Interoperabilität erwartet. Im Wesentlichen ist er für Experimente gedacht.

5.2. Data Transfer

Die Fenstergröße gibt an, wie viele Bytes die andere Partei senden kann, bevor sie warten muss, bis das Fenster angepasst wird. Beide Parteien verwenden die folgende Nachricht, um das Fenster anzupassen.

byte      SSH_MSG_CHANNEL_WINDOW_ADJUST
uint32    recipient channel
uint32    bytes to add

Nach Erhalt dieser Nachricht DARF der Empfänger die angegebene Anzahl von Bytes mehr senden, als ihm zuvor erlaubt war; die Fenstergröße wird erhöht. Implementierungen MÜSSEN Fenstergrößen von bis zu 2^32 - 1 Bytes korrekt handhaben. Das Fenster DARF NICHT über 2^32 - 1 Bytes hinaus vergrößert werden.

Die Datenübertragung erfolgt mit Nachrichten des folgenden Typs.

byte      SSH_MSG_CHANNEL_DATA
uint32    recipient channel
string    data

Die maximal zulässige Datenmenge wird durch die maximale Paketgröße für den Kanal und die aktuelle Fenstergröße bestimmt, je nachdem, welche kleiner ist. Die Fenstergröße wird um die Menge der gesendeten Daten verringert. Beide Parteien DÜRFEN alle zusätzlichen Daten ignorieren, die gesendet werden, nachdem das zulässige Fenster leer ist.

Es wird erwartet, dass Implementierungen eine Begrenzung für die SSH-Transportschicht-Paketgröße haben (jede Begrenzung für empfangene Pakete MUSS 32768 Bytes oder größer sein, wie in [SSH-TRANS] beschrieben). Die Implementierung der SSH-Verbindungsschicht:

DARF KEINE maximale Paketgröße ankündigen, die zu Transportpaketen führen würde, die größer sind, als ihre Transportschicht zu empfangen bereit ist.
DARF KEINE Datenpakete erzeugen, die größer sind, als ihre Transportschicht zu senden bereit ist, selbst wenn das entfernte Ende bereit wäre, sehr große Pakete zu akzeptieren.

Darüber hinaus können einige Kanäle mehrere Datentypen übertragen. Ein Beispiel dafür sind stderr-Daten aus interaktiven Sitzungen. Solche Daten können mit SSH_MSG_CHANNEL_EXTENDED_DATA-Nachrichten übergeben werden, wobei eine separate Ganzzahl den Datentyp angibt. Die verfügbaren Typen und ihre Interpretation hängen vom Kanaltyp ab.

byte      SSH_MSG_CHANNEL_EXTENDED_DATA
uint32    recipient channel
uint32    data_type_code
string    data

Mit diesen Nachrichten gesendete Daten verbrauchen dasselbe Fenster wie gewöhnliche Daten.

Derzeit ist nur der folgende Typ definiert. Beachten Sie, dass der Wert für den data_type_code zur besseren Lesbarkeit im Dezimalformat angegeben ist, die Werte jedoch tatsächlich uint32-Werte sind.

Symbolic name	data_type_code
`SSH_EXTENDED_DATA_STDERR`	1

Extended Channel Data Transfer data_type_code-Werte MÜSSEN sequenziell zugewiesen werden. Anfragen zur Zuweisung neuer Extended Channel Data Transfer data_type_code-Werte und ihrer zugehörigen Extended Channel Data Transfer data-Zeichenketten im Bereich von 0x00000002 bis 0xFDFFFFFF MÜSSEN über die IETF CONSENSUS-Methode erfolgen, wie in [RFC2434] beschrieben. Die IANA wird keine Extended Channel Data Transfer data_type_code-Werte im Bereich von 0xFE000000 bis 0xFFFFFFFF zuweisen. Extended Channel Data Transfer data_type_code-Werte in diesem Bereich sind für PRIVATE USE reserviert, wie in [RFC2434] beschrieben. Wie bereits erwähnt, befinden sich die tatsächlichen Anweisungen an die IANA in [SSH-NUMBERS].

5.3. Closing a Channel

Wenn eine Partei keine weiteren Daten mehr an einen Kanal senden wird, SOLLTE sie SSH_MSG_CHANNEL_EOF senden.

byte      SSH_MSG_CHANNEL_EOF
uint32    recipient channel

Auf diese Nachricht wird keine explizite Antwort gesendet. Die Anwendung kann jedoch EOF an alles senden, was sich am anderen Ende des Kanals befindet. Beachten Sie, dass der Kanal nach dieser Nachricht offen bleibt und in der anderen Richtung noch weitere Daten gesendet werden können. Diese Nachricht verbraucht keinen Fensterplatz und kann auch dann gesendet werden, wenn kein Fensterplatz verfügbar ist.

Wenn eine Partei den Kanal beenden möchte, sendet sie SSH_MSG_CHANNEL_CLOSE. Nach Erhalt dieser Nachricht MUSS eine Partei ein SSH_MSG_CHANNEL_CLOSE zurücksenden, es sei denn, sie hat diese Nachricht bereits für den Kanal gesendet. Der Kanal gilt für eine Partei als geschlossen, wenn sie sowohl SSH_MSG_CHANNEL_CLOSE gesendet als auch empfangen hat, und die Partei kann dann die Kanalnummer wiederverwenden. Eine Partei DARF SSH_MSG_CHANNEL_CLOSE senden, ohne SSH_MSG_CHANNEL_EOF gesendet oder empfangen zu haben.

byte      SSH_MSG_CHANNEL_CLOSE
uint32    recipient channel

Diese Nachricht verbraucht keinen Fensterplatz und kann auch dann gesendet werden, wenn kein Fensterplatz verfügbar ist.

Es wird EMPFOHLEN, dass alle vor dieser Nachricht gesendeten Daten nach Möglichkeit an das tatsächliche Ziel zugestellt werden.

5.4. Channel-Specific Requests

Viele channel type-Werte haben Erweiterungen, die für diesen bestimmten channel type spezifisch sind. Ein Beispiel ist die Anforderung eines pty (Pseudo-Terminals) für eine interaktive Sitzung.

Alle kanalspezifischen Anfragen verwenden das folgende Format.

byte      SSH_MSG_CHANNEL_REQUEST
uint32    recipient channel
string    request type in US-ASCII characters only
boolean   want reply
....      type-specific data follows

Wenn want reply FALSE ist, wird keine Antwort auf die Anfrage gesendet. Andernfalls antwortet der Empfänger entweder mit SSH_MSG_CHANNEL_SUCCESS, SSH_MSG_CHANNEL_FAILURE oder anfragespezifischen Fortsetzungsnachrichten. Wenn die Anfrage nicht erkannt wird oder für den Kanal nicht unterstützt wird, wird SSH_MSG_CHANNEL_FAILURE zurückgegeben.

Diese Nachricht verbraucht keinen Fensterplatz und kann auch dann gesendet werden, wenn kein Fensterplatz verfügbar ist. Die Werte von request type sind lokal für jeden Kanaltyp.

Der Client darf weitere Nachrichten senden, ohne auf die Antwort auf die Anfrage zu warten.

request type-Namen folgen der DNS-Erweiterbarkeits-Namenskonvention, die in [SSH-ARCH] und [SSH-NUMBERS] beschrieben ist.

byte      SSH_MSG_CHANNEL_SUCCESS
uint32    recipient channel

byte      SSH_MSG_CHANNEL_FAILURE
uint32    recipient channel

Diese Nachrichten verbrauchen keinen Fensterplatz und können auch dann gesendet werden, wenn kein Fensterplatz verfügbar ist.