apple/swift-nio-sshSwiftNIO SSH est une implémentation programmatique de SSH utilisant SwiftNIO.
Ce projet contient le support SSH utilisant SwiftNIO.
SwiftNIO SSH est une implémentation programmatique de SSH : c'est-à-dire un ensemble d'API permettant aux programmeurs d'implémenter des points de terminaison parlant SSH. Point crucial, cela signifie qu'il ressemble davantage à libssh2 qu'à openssh. SwiftNIO SSH ne fournit pas de clients et serveurs SSH prêts pour la production, mais fournit plutôt les briques de base pour construire ce type de client et de serveur.
Plusieurs raisons justifient de fournir une implémentation programmatique de SSH. L'une d'elles est que SSH entretient une relation unique avec l'interactivité avec l'utilisateur. Les utilisateurs techniques sont très habitués à interagir avec SSH de manière interactive, que ce soit pour exécuter des commandes sur des machines distantes ou pour ouvrir des shells interactifs. Pouvoir répondre programmatiquement à ces requêtes permet d'envisager des modes d'interaction alternatifs intéressants. Comme exemples précédents, on peut citer Manhole de Twisted, qui utilise une implémentation programmatique de SSH appelée conch pour fournir un interpréteur Python interactif au sein d'un serveur Python en cours d'exécution, ou ssh-chat, un serveur SSH qui propose un salon de discussion au lieu des fonctionnalités habituelles de shell SSH. Des usages innovants peuvent également être imaginés pour la redirection TCP.
Une autre bonne raison de fournir un SSH programmatique est qu'il n'est pas rare que des services aient besoin d'interagir avec d'autres services d'une manière qui implique l'exécution de commandes. Bien que Process résolve ce problème pour le cas local, il arrive parfois que les commandes à invoquer soient distantes. Bien que Process puisse lancer un client ssh comme sous-processus pour effectuer cette invocation, il peut être nettement plus simple d'invoquer directement SSH. C'est le cas d'usage cible de libssh2. SwiftNIO SSH fournit l'équivalent de la couche réseau et cryptographique de libssh2, permettant aux utilisateurs motivés de piloter des sessions SSH directement depuis des services Swift.
Les versions les plus récentes de SwiftNIO SSH prennent en charge Swift 5.9 et versions ultérieures. Les versions minimales de Swift prises en charge par les versions de SwiftNIO SSH sont détaillées ci-dessous :
SwiftNIO SSH prend en charge SSHv2 avec l'ensemble de fonctionnalités suivant :
SwiftNIO SSH fournit un ChannelHandler SwiftNIO, NIOSSHHandler. Ce handler implémente directement l'essentiel du protocole SSH. Les utilisateurs ne sont pas censés générer directement les messages SSH : ils interagissent plutôt avec NIOSSHHandler par l'intermédiaire de canaux enfants et de délégués.
SSH est un protocole multiplexé : chaque connexion SSH est subdivisée en plusieurs canaux de communication bidirectionnels appelés, comme il se doit, canaux. SwiftNIO SSH reflète cette construction en utilisant une abstraction de « canal enfant ». Lorsqu'un pair crée un nouveau canal SSH, SwiftNIO SSH crée un nouveau Channel NIO qui sert à représenter tout le trafic sur ce canal SSH. Dans ce Channel enfant, tous les événements sont strictement ordonnés les uns par rapport aux autres : cependant, les événements de différents Channel peuvent être entrelacés librement par l'implémentation.
Une connexion SSH active ressemble donc à ceci :
┌ ─ NIO Channel ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
│ ┌────────────────────────────────┐ │
│ │
│ │ │ │
│ │
│ │ │ │
│ NIOSSHHandler │───────────────────────┐
│ │ │ │ │
│ │ │
│ │ │ │ │
│ │ │
│ └────────────────────────────────┘ │ │
│
└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ │
│
│
│
│
▼
┌── SSH Child Channel ─────────────────────────────────────────────────────────────┐
│ │
│ ┌────────────────────────────────┐ ┌────────────────────────────────┐ ├───┐
│ │ │ │ │ │ │
│ │ │ │ │ │ ├───┐
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ User Handler │ │ User Handler │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ └────────────────────────────────┘ └────────────────────────────────┘ │ │ │
│ │ │ │
└───┬──────────────────────────────────────────────────────────────────────────────┘ │ │
│ │ │
└───┬──────────────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────────┘
Un canal SSH est invoqué avec un type de canal. NIOSSH en prend en charge trois : session, directTCPIP et forwardedTCPIP. Le type de canal le plus courant est session : session est utilisé pour représenter l'invocation d'un programme, qu'il s'agisse d'un programme nommé spécifique ou d'un shell. Les deux autres types de canal sont liés à la redirection de ports TCP et seront abordés plus tard.
Un canal SSH opère sur un seul type de donnée : SSHChannelData. Cette structure encapsule le fait que SSH prend en charge à la fois les données de canal normales et « étendues ». Les données de canal normales (SSHChannelData.DataType.channel) sont utilisées pour la grande majorité des données principales. Dans les canaux session, le type de donnée .channel est utilisé pour l'entrée standard et la sortie standard : le type de donnée .stdErr est utilisé pour l'erreur standard (naturellement). Dans les canaux de redirection TCP, le type de donnée .channel est le seul utilisé et représente les données redirigées.
Un canal session représente l'invocation d'une commande. La manière exacte dont le canal fonctionne est communiquée via un certain nombre d'événements utilisateur entrants. Les événements suivants sont importants :
SSHChannelRequestEvent.PseudoTerminalRequest : demande l'allocation d'un pseudo-terminal.SSHChannelRequestEvent.EnvironmentRequest : demande une variable d'environnement unique pour l'invocation de la commande. Toujours envoyé avant la commande elle-même.SSHChannelRequestEvent.ShellRequest : demande que la commande à invoquer soit le shell de l'utilisateur authentifié.SSHChannelRequestEvent.ExecRequest : demande l'invocation d'une commande spécifique.SSHChannelRequestEvent.ExitStatus : utilisé pour signaler que la commande distante s'est terminée et pour communiquer le code de sortie.SSHChannelRequestEvent.ExitSignal : utilisé pour indiquer que la commande distante a été interrompue en réponse à un signal, et quel était ce signal.SSHChannelRequestEvent.SignalRequest : utilisé pour envoyer un signal à la commande distante.SSHChannelRequestEvent.LocalFlowControlRequest : utilisé pour indiquer si le client est capable d'effectuer lui-même le contrôle de flux Ctrl-Q/Ctrl-S.SSHChannelRequestEvent.WindowChangeRequest : utilisé pour communiquer un changement de taille de la fenêtre du terminal côté client au pseudo-terminal alloué.Ces événements ne sont pas utilisés dans les messages de redirection de ports. Les implémentations SSH qui prennent en charge les canaux de type .session doivent être prêtes à gérer la plupart ou la totalité d'entre eux de diverses manières.
Chacun de ces événements possède également un champ wantReply. Celui-ci indique si la requête a besoin d'une réponse pour indiquer un succès ou un échec. Si c'est le cas, les deux événements suivants sont utilisés :
ChannelSuccessEvent, pour communiquer un succès.ChannelFailureEvent, pour communiquer un échec.Le protocole réseau SSH utilise de manière omniprésente la demi-fermeture dans les canaux enfants. Les Channel NIO ont généralement la prise en charge de la demi-fermeture désactivée par défaut, et SwiftNIO SSH respecte également cette valeur par défaut dans ses canaux enfants. Cependant, si vous laissez ce réglage à sa valeur par défaut, les canaux enfants SSH se comporteront de manière extrêmement inattendue. Pour cette raison, il est fortement recommandé que tous les canaux enfants aient la prise en charge de la demi-fermeture activée :
channel.setOption(ChannelOptions.allowRemoteHalfClosure, true)
Cela utilise alors la prise en charge standard de la demi-fermeture de NIO. L'envoi d'EOF par le pair distant sera communiqué via un événement utilisateur entrant, ChannelEvent.inputClosed. Pour envoyer vous-même un EOF, appelez close(mode: .output).
L'authentification utilisateur est un élément vital de SSH. Pour la gérer, SwiftNIO SSH utilise deux protocoles délégués : NIOSSHClientUserAuthenticationDelegate et NIOSSHServerUserAuthenticationDelegate. Les clients et les serveurs doivent fournir des implémentations de ces protocoles délégués pour gérer l'authentification utilisateur.
Le protocole côté client est simple : SwiftNIO SSH invoquera la méthode nextAuthenticationType(availableMethods:nextChallengePromise:) sur le délégué. availableMethods sera une instance de NIOSSHAvailableUserAuthenticationMethods indiquant quelles méthodes d'authentification le serveur a suggérées comme acceptables. Le délégué peut ensuite compléter nextChallengePromise avec soit une nouvelle requête d'authentification, soit nil pour indiquer que le client n'a plus rien à essayer.
Le protocole côté serveur est plus complexe. Le délégué doit fournir une propriété supportedAuthenticationMethods qui indique quelles méthodes d'authentification sont prises en charge par le délégué. Ensuite, chaque fois que le client envoie une requête d'authentification utilisateur, la méthode requestReceived(request:responsePromise:) est invoquée. Elle peut être invoquée plusieurs fois en parallèle, car les clients sont autorisés à émettre des requêtes d'authentification en parallèle. responsePromise doit être complétée avec succès avec le résultat de l'authentification. Il y a trois résultats : .success et .failure sont simples, mais en principe le serveur peut exiger plusieurs défis en utilisant .partialSuccess(remainingMethods:).
La redirection de port directe est une redirection de port du client vers le serveur. Dans ce mode, le client écoute traditionnellement sur un port local et redirige les connexions entrantes vers le serveur. Il demande au serveur de rediriger ces connexions en tant que connexions sortantes vers un hôte et un port spécifiques.
Ces canaux peuvent être directement ouverts par les clients en utilisant le type de canal .directTCPIP.
La redirection de port distante est une situation moins courante dans laquelle le client demande au serveur d'écouter sur une adresse et un port spécifiques, et de rediriger toutes les connexions entrantes vers le client. Comme le client doit demander ce comportement, il le fait à l'aide de requêtes globales.
Les requêtes globales sont initiées à l'aide de NIOSSHHandler.sendGlobalRequest, et sont reçues et traitées par l'intermédiaire d'un GlobalRequestDelegate. Deux requêtes globales sont actuellement prises en charge :
GlobalRequest.TCPForwardingRequest.listen(host:port:) : une requête demandant au serveur d'écouter sur un hôte et un port donnés.GlobalRequest.TCPForwardingRequest.cancel(host:port:) : une requête demandant d'annuler l'écoute sur l'hôte et le port donnés.Les serveurs peuvent être notifiés de ces requêtes et y répondre à l'aide d'un GlobalRequestDelegate. La méthode à implémenter ici est tcpForwardingRequest(_:handler:promise:). Cette méthode déléguée est invoquée à chaque fois qu'une requête globale est reçue. La réponse à la requête est transmise dans promise.
Les canaux redirigés sont ensuite envoyés du serveur au client en utilisant le type de canal .forwardedTCPIP.
| SwiftNIO SSH | Version Swift minimale |
|---|
0.0.0 ..< 0.3.0 | 5.1 |
0.3.0 ..< 0.4.0 | 5.2 |
0.4.0 ..< 0.5.0 | 5.4 |
0.5.0 ..< 0.6.2 | 5.5.2 |
0.6.2 ..< 0.9.0 | 5.6 |
0.9.0 ..< 0.9.2 | 5.8 |
0.9.2 ..< 0.10.0 | 5.9 |
0.10.0 ... 0.12.0 | 5.10 |
0.12.0 ..< 0.13.0 | 6.0 |
0.13.0 ..< | 6.1 |
SSHChannelRequestEvent.SubsystemRequest : utilisé pour demander l'invocation d'un sous-système spécifique. Sa signification est propre à chaque cas d'utilisation.