5. Channel Mechanism (Mécanisme de canal)

Toutes les communications terminales, les transferts de fichiers, les transferts de connexions de port TCP/IP, etc., sont effectués à l'intérieur de canaux. Soit un seul canal, soit plusieurs canaux peuvent être ouverts à travers une seule connexion. Les canaux sont multiplexés dans une seule connexion par le protocole de transport SSH.

Une connexion SSH peut comporter un nombre arbitraire de canaux. Plusieurs canaux peuvent exécuter des programmes différents simultanément. Les canaux sont identifiés par des numéros locaux sur chaque extrémité de la connexion. Une extrémité fait référence à un canal en utilisant le numéro de canal qu'elle a elle-même alloué, et l'autre extrémité en utilisant le numéro qu'elle a alloué.

Les deux extrémités démarrent à un numéro de canal défini de façon indépendante (ce qui permet d'utiliser des numéros impairs pour l'une et pairs pour l'autre, et de traiter les numéros impairs comme alloués par le client, les pairs comme alloués par le serveur). Les requêtes pour un canal sont correctement dirigées en utilisant le numéro de canal.

Les numéros de canal peuvent être réutilisés. Une fois qu'un canal est fermé, le numéro de canal local peut être réutilisé. L'utilisation de numéros de canal faibles est recommandée pour l'efficacité.

Les messages de canal contiennent les champs suivants.

uint32    recipient channel

Ceci est le numéro de canal attribué par l'extrémité locale pour le canal auquel le message fait référence.

5.1. Opening a Channel (Ouverture d'un canal)

Pour ouvrir un canal, l'envoi d'une SSH_MSG_CHANNEL_OPEN est effectué depuis la localité qui souhaite initier le canal. Les champs pertinents sont les suivants.

byte      SSH_MSG_CHANNEL_OPEN
string    channel type
uint32    sender channel
uint32    initial window size
uint32    maximum packet size

L'extrémité distante a alors la possibilité d'accepter ou de refuser le canal. Si l'initiateur du canal reçoit SSH_MSG_CHANNEL_OPEN_CONFIRMATION comme réponse, le canal est ouvert. Si l'initiateur reçoit SSH_MSG_CHANNEL_OPEN_FAILURE, l'ouverture de canal a échoué.

Si le canal demandé ne peut pas être ouvert, SSH_MSG_CHANNEL_OPEN_FAILURE est retourné. Le champ 'code de raison' contient l'explication de l'échec.

byte      SSH_MSG_CHANNEL_OPEN_FAILURE
uint32    recipient channel
uint32    reason code
string    description (ISO-10646 UTF-8)
string    language tag (comme défini dans [RFC3066])

Les codes de raison actuellement définis sont les suivants.

#define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED    1
#define SSH_OPEN_CONNECT_FAILED                 2
#define SSH_OPEN_UNKNOWN_CHANNEL_TYPE           3
#define SSH_OPEN_RESOURCE_SHORTAGE             4

Les codes de raison doivent être traités comme inconnus s'ils ne sont pas reconnus. Plus de codes de raison peuvent être définis dans le futur.

Si l'extrémité distante accepte la session, elle renvoie SSH_MSG_CHANNEL_OPEN_CONFIRMATION.

byte      SSH_MSG_CHANNEL_OPEN_CONFIRMATION
uint32    recipient channel
uint32    sender channel
uint32    initial window size
uint32    maximum packet size

5.2. Data Transfer (Transfert de données)

Une fois qu'un canal est ouvert, les données peuvent être envoyées en utilisant les messages SSH_MSG_CHANNEL_DATA et SSH_MSG_CHANNEL_EXTENDED_DATA.

byte      SSH_MSG_CHANNEL_DATA
uint32    recipient channel
string    data

Chaque message de données contient une quantité de données qui n'excède pas le paquet maximum pour le canal. Une valence de fenêtre initiale d'au moins 2^31 est recommandée.

byte      SSH_MSG_CHANNEL_EXTENDED_DATA
uint32    recipient channel
uint32    data type code
string    data

Le code de type de données SSH_EXTENDED_DATA_STDERR est défini pour les données stderr (erreur standard).

L'extrémité distante ne doit pas envoyer plus de données que ce qui est autorisé par la fenêtre. La fenêtre est diminuée par le nombre d'octets de charge utile envoyés chaque fois qu'un message de données est envoyé, et augmentée par le nombre d'octets de charge utile transférés chaque fois qu'un SSH_MSG_CHANNEL_WINDOW_ADJUST est reçu.

byte      SSH_MSG_CHANNEL_WINDOW_ADJUST
uint32    recipient channel
uint32    bytes to add

5.3. Closing a Channel (Fermeture d'un canal)

Lorsqu'une extrémité n'a plus aucune utilisation pour un canal, elle le ferme en envoyant SSH_MSG_CHANNEL_CLOSE. Lorsqu'une extrémité reçoit ce message, elle envoie à son tour SSH_MSG_CHANNEL_CLOSE, sauf si elle l'a déjà envoyé.

byte      SSH_MSG_CHANNEL_CLOSE
uint32    recipient channel

Une fois qu'un canal est fermé, aucune information supplémentaire ne doit être envoyée sur ce canal. Les données de canal non lues peuvent être ignorées.

Si l'une des extrémités a pour mandat de supprimer la connexion à la couche transport, cela se produit seulement après que tous les canaux ont été fermés.

5.4. Channel-Specific Requests (Requêtes spécifiques à un canal)

De nombreux canaux nécessitent des requêtes spécifiques. Toutes les requêtes spécifiques à un canal utilisent les formats de message suivants.

byte      SSH_MSG_CHANNEL_REQUEST
uint32    recipient channel
string    request type
boolean   want reply
....      type-specific data follows

Si want reply a la valeur FALSE, aucune réponse ne sera envoyée à la requête. Sinon, l'extrémité distante répond par SSH_MSG_CHANNEL_SUCCESS ou SSH_MSG_CHANNEL_FAILURE, selon que la requête a été réussie ou non.

byte      SSH_MSG_CHANNEL_SUCCESS
uint32    recipient channel

byte      SSH_MSG_CHANNEL_FAILURE
uint32    recipient channel

Si l'extrémité locale a envoyé un message SSH_MSG_CHANNEL_REQUEST avec want reply défini à TRUE et qu'elle n'a pas reçu de réponse dans un délai raisonnable (par exemple, 10 secondes), la session PEUT être interrompue. Si le moteur de requêtes n'est pas encore prêt à traiter la requête, et si want reply est défini, elle doit répondre par SSH_MSG_CHANNEL_FAILURE.