5. Channel Mechanism (Meccanismo dei canali)

Tutte le comunicazioni terminali, i trasferimenti di file, i trasferimenti di connessioni di porta TCP/IP, ecc., vengono effettuati all'interno di canali. Può essere aperto un singolo canale o più canali attraverso una singola connessione. I canali sono multiplexati in un'unica connessione dal protocollo di trasporto SSH.

Una connessione SSH può contenere un numero arbitrario di canali. Più canali possono eseguire programmi diversi simultaneamente. I canali sono identificati da numeri locali su ciascuna estremità della connessione. Un'estremità fa riferimento a un canale utilizzando il numero di canale che ha allocato essa stessa, e l'altra estremità utilizzando il numero che ha allocato.

Entrambe le estremità iniziano con un numero di canale definito in modo indipendente (ciò consente di utilizzare numeri dispari per l'una e pari per l'altra, e di trattare i numeri dispari come allocati dal client e i pari come allocati dal server). Le richieste per un canale vengono indirizzate correttamente utilizzando il numero di canale.

I numeri di canale possono essere riutilizzati. Una volta chiuso un canale, il numero di canale locale può essere riutilizzato. Si raccomanda l'uso di numeri di canale bassi per efficienza.

I messaggi di canale contengono i seguenti campi.

uint32    recipient channel

Questo è il numero di canale assegnato dall'estremità locale per il canale a cui si riferisce il messaggio.

5.1. Opening a Channel (Apertura di un canale)

Per aprire un canale, l'invio di un SSH_MSG_CHANNEL_OPEN viene effettuato dall'entità che desidera avviare il canale. I campi pertinenti sono i seguenti.

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

L'estremità remota ha quindi la possibilità di accettare o rifiutare il canale. Se l'iniziatore del canale riceve SSH_MSG_CHANNEL_OPEN_CONFIRMATION come risposta, il canale è aperto. Se l'iniziatore riceve SSH_MSG_CHANNEL_OPEN_FAILURE, l'apertura del canale non è riuscita.

Se il canale richiesto non può essere aperto, viene restituito SSH_MSG_CHANNEL_OPEN_FAILURE. Il campo "reason code" contiene la spiegazione dell'errore.

byte      SSH_MSG_CHANNEL_OPEN_FAILURE
uint32    recipient channel
uint32    reason code
string    description (ISO-10646 UTF-8)
string    language tag (come definito in [RFC3066])

I codici di motivo attualmente definiti sono i seguenti.

#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

I codici di motivo devono essere trattati come sconosciuti se non vengono riconosciuti. Possono essere definiti ulteriori codici di motivo in futuro.

Se l'estremità remota accetta la sessione, restituisce 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 (Trasferimento dati)

Una volta aperto un canale, i dati possono essere inviati utilizzando i messaggi SSH_MSG_CHANNEL_DATA e SSH_MSG_CHANNEL_EXTENDED_DATA.

byte      SSH_MSG_CHANNEL_DATA
uint32    recipient channel
string    data

Ogni messaggio di dati contiene una quantità di dati che non supera il pacchetto massimo per il canale. Si raccomanda una dimensione iniziale della finestra di almeno 2^31.

byte      SSH_MSG_CHANNEL_EXTENDED_DATA
uint32    recipient channel
uint32    data type code
string    data

Il codice di tipo di dati SSH_EXTENDED_DATA_STDERR è definito per i dati stderr (errore standard).

L'estremità remota non deve inviare più dati di quanto consentito dalla finestra. La finestra viene diminuita del numero di byte di payload inviati ogni volta che viene inviato un messaggio di dati e aumentata del numero di byte di payload trasferiti ogni volta che viene ricevuto un SSH_MSG_CHANNEL_WINDOW_ADJUST.

byte      SSH_MSG_CHANNEL_WINDOW_ADJUST
uint32    recipient channel
uint32    bytes to add

5.3. Closing a Channel (Chiusura di un canale)

Quando un'estremità non ha più alcun utilizzo per un canale, lo chiude inviando SSH_MSG_CHANNEL_CLOSE. Quando un'estremità riceve questo messaggio, a sua volta invia SSH_MSG_CHANNEL_CLOSE, a meno che non lo abbia già inviato.

byte      SSH_MSG_CHANNEL_CLOSE
uint32    recipient channel

Una volta chiuso un canale, non devono essere inviate ulteriori informazioni su quel canale. I dati di canale non letti possono essere ignorati.

Se un'estremità ha il compito di chiudere la connessione al livello di trasporto, ciò avviene solo dopo che tutti i canali sono stati chiusi.

5.4. Channel-Specific Requests (Richieste specifiche del canale)

Molti canali richiedono richieste specifiche. Tutte le richieste specifiche del canale utilizzano i seguenti formati di messaggio.

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

Se want reply è FALSE, non verrà inviata alcuna risposta alla richiesta. In caso contrario, l'estremità remota risponde con SSH_MSG_CHANNEL_SUCCESS o SSH_MSG_CHANNEL_FAILURE, a seconda che la richiesta sia riuscita o meno.

byte      SSH_MSG_CHANNEL_SUCCESS
uint32    recipient channel

byte      SSH_MSG_CHANNEL_FAILURE
uint32    recipient channel

Se l'estremità locale ha inviato un messaggio SSH_MSG_CHANNEL_REQUEST con want reply impostato su TRUE e non ha ricevuto risposta entro un tempo ragionevole (ad esempio, 10 secondi), la sessione PUÒ essere interrotta. Se il motore di gestione delle richieste non è ancora pronto a elaborare la richiesta e se want reply è impostato, deve rispondere con SSH_MSG_CHANNEL_FAILURE.