Project

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Dev Tunnels SSH Library

A Secure Shell (SSH2) client and server protocol library, implemented in both C# and TypeScript.

Feature Highlights

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:

microsoft/dev-tunnels-ssh