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.
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.
A Secure Shell (SSH2) client and server protocol library, implemented in both C# and TypeScript.
- 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.
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.
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.
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.
| 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.
See README-dev.md.
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.
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 |
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