Secure Connections Made Easy: Dev Tunnels SSH Library
- SSH over any .NET Stream or JavaScript stream (including but not limited to TCP socket streams)
- Configurable, extensible, negotiated algorithms for key-exchange, encryption, integrity (HMAC), and public-key authentication
- Channel multiplexing, with ability to stream data to/from channels
- Port-forwarding, with ability to stream data to/from remote ports
- Piping between two sessions can relay all channels and port-forwarding
- Extensible channel request handling (for "exec", "shell", or custom requests)
- Supports reconnecting a disconnected session without disrupting channel streams.
- Compatible with common SSH software. (Tested against OpenSSH.)
- Supports importing and exporting several key formats, including password-protected keys.
Limitations
The following features are not implemented in this library, though they could be built on top of it:
- Allowing a client to login to a user account on the server
- Connecting to a shell on the server
- Invoking shell commands on the server
- Transferring files (SCP or SFTP)
- Rendering a terminal on the client side
Future development may add support for some of these capabilities, likely in the form of additional optional packages.
C# (.NET Framework, .NET Core, .NET 6)
The C# library targets .NET Framework 4.8, .NET Standard 2.1 (.NET Core 3.1, .NET 5), and .NET 6. It's tested on Windows, Mac, & Ubuntu. For details about the .NET library, see src/cs/Ssh/README.md.
TypeScript (Node.js or Browser)
The TypeScript implementation supports either Node.js (>= 14.x) or a browser environment. The Node.js version is tested on Windows, Mac & Ubuntu; the browser version is tested on Chrome & Edge Chromium, though it should work in any modern browser that supports the web crypto API. Note that since script on a web page cannot access native TCP sockets, the standard use of SSH over TCP is not possible; some other stream transport like a websocket may be used. For details about the TypeScript library, see src/ts/ssh/README.md.
Packages
| C# NuGet package | TS npm package | |
|---|---|---|
| SSH core protocol and crypto | Microsoft.DevTunnels.Ssh | @microsoft/dev-tunnels-ssh |
| SSH public/private key import/export | Microsoft.DevTunnels.Ssh.Keys | @microsoft/dev-tunnels-ssh-keys |
| SSH TCP connections and port-forwarding | Microsoft.DevTunnels.Ssh.Tcp | @microsoft/dev-tunnels-ssh-tcp |
The optional "keys" and "TCP" packages depend on the core package. All SSH packages in an app must be the same major and minor version; the patch version (3rd component) may differ if necessary. In other words, any changes that impact cross-package dependencies will increment at least the minor version.
Development
See README-dev.md.
SSH Algorithms Support
Crypto algorithms below rely on platform APIs in .NET (System.Security.Cryptography), Node.js (crypto module) or browsers (web crypto)). There is one use of a 3rd-party library: the diffie-hellman package is required in browsers because there is no corresponding web crypto API.
Legend:
✔✔✔ - Enabled and preferred in default session configuration.
✔✔ - Enabled (but not preferred) in default session configuration.
✔ - Supported and can be enabled in custom session configuration.
☑ - Coming soon (working in a branch or PR).
?? - Under consideration for the future.
| Type | Algorithm Name | Status |
|---|---|---|
| key-exchange | diffie-hellman-group16-sha512 | ✔✔ |
| key-exchange | diffie-hellman-group14-sha256 | ✔✔ |
| key-exchange | ecdh-sha2-nistp521 | ✔ |
| key-exchange | ecdh-sha2-nistp384 | ✔✔✔ |
| key-exchange | ecdh-sha2-nistp256 | ✔✔ |
| key-exchange | curve25519-sha256 | ?? [1] |
| public-key | rsa-sha2-512 | ✔✔✔ |
| public-key | rsa-sha2-256 | ✔✔ |
| public-key | ecdsa-sha2-nistp256 | ✔✔ |
| public-key | ecdsa-sha2-nistp384 | ✔✔ |
| public-key | ecdsa-sha2-nistp521 | ✔ |
| public-key | ssh-ed25519 | ?? [1] |
| public-key | *-cert-v01@openssh.com | ?? [2] |
| cipher | aes256-cbc | ✔✔ [3] |
| cipher | aes256-ctr | ✔✔ |
| cipher | aes192-cbc | ✔ |
| cipher | aes192-ctr | ✔ |
| cipher | aes128-cbc | ✔ |
| cipher | aes128-ctr | ✔ |
| cipher | aes256-gcm@openssh.com | ✔✔✔ |
| cipher | aes128-gcm@openssh.com | ✔ |
| cipher | chacha20-poly1305@openssh.com | ?? [1] |
| mac | hmac-sha2-512 | ✔✔ |
| mac | hmac-sha2-256 | ✔✔ |
| mac | hmac-sha2-512-etm@openssh.com | ✔✔✔ |
| mac | hmac-sha2-256-etm@openssh.com | ✔✔ |
[1] May require use of 3rd-party libs, though Curve25519 APIs are under consideration for .NET and web crypto.
[2] OpenSSH certificate support should be possible with some work.
[3] AES-CBC is not supported in browsers due to a limitation of the web crypto API. AES-CTR or AES-GCM works fine.
There is no plan to have built-in support for older algorithms known to be insecure (for example SHA-1), though in some cases these can be easily added by the application.
Key Format Support
Support for importing and exporting keys in various formats is provided in NuGet/npm packages separate from the core SSH functionality. Some key formats are only implemented in either the C# or TS libraries, not both. See also src/cs/SSH.Keys/README.md or src/ts/ssh-keys/README.md.
| Key Format | Key Algorithm | Password Protection | Format Description |
|---|---|---|---|
| SSH public key | RSA ECDSA | N/A | Single line key algorithm name, base64-encoded key bytes, and optional comment. Files conventionally end with .pub. |
| PKCS#1 | RSA | import only | Starts with one of:-----BEGIN RSA PUBLIC KEY----------BEGIN RSA PRIVATE KEY----- |
| SEC1 | ECDSA | import only | Starts with:-----BEGIN EC PRIVATE KEY----- |
| PKCS#8 | RSA ECDSA | ✔ | Starts with one of:-----BEGIN PUBLIC KEY----------BEGIN PRIVATE KEY----------BEGIN ENCRYPTED PRIVATE KEY----- |
| SSH2 C# only | RSA | ✔ | Starts with one of:---- BEGIN SSH2 PUBLIC KEY -------- BEGIN SSH2 ENCRYPTED PRIVATE KEY ---- |
| OpenSSH C# only | RSA ECDSA | ✔ | Starts with one of:-----BEGIN OPENSSH PUBLIC KEY----------BEGIN OPENSSH PRIVATE KEY----- |
| JWK TS only | RSA ECDSA | N/A | JSON with key algorithm name and parameters |
References
The following RFCs define the SSH protocol:
- RFC 4250 - SSH Protocol Assigned Numbers
- RFC 4251 - SSH Protocol Architecture
- RFC 4252 - SSH Authentication Protocol
- RFC 4253 - SSH Transport Layer Protocol
- RFC 4254 - SSH Connection Protocol
- RFC 4256 - Generic Message Exchange Authentication for SSH
- RFC 4716 - SSH Public Key File Format
- RFC 5647 - AES GCM for the SSH Protocol
- RFC 5656 - EC Algorithm Integration in SSH
- RFC 8308 - SSH Extension Negotiation
Download Details:
Author: microsoft
Official Github: https://github.com/microsoft/dev-tunnels-ssh
License: MIT
