Documentation updates (#1395)

- Update README to point to https://sshnet.github.io/SSH.NET rather than the CHM file
- Add a CONTRIBUTING.md with some how-tos

For https://sshnet.github.io/SSH.NET:

- Use the repo README as the landing page to keep them in sync
- Combine the API-per-TFM pages to just one "API" page
- Add a couple more examples
- Add a GitHub link in the header.

.gitignore

@@ -487,10 +487,5 @@ $RECYCLE.BIN/
 build/target/
 
 # Docs
-docfx/_site/**
-docfx/net462/**
-docfx/netstandard2.0/**
-docfx/netstandard2.1/**
-docfx/net6.0/**
-docfx/net7.0/**
-docfx/net8.0/**
+docfx/_site/
+docfx/api/

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+Contributions in the form of issues, pull requests (PRs) and discussions are welcome to this repository. Please consider that the library is currently maintained as a hobby by a small number of individuals. As such, depending on the weather, work, private lives etc., your PR may wait an indeterminate amount of time before being addressed. Generally speaking, the more targeted and better tested the change, the quicker it can be merged.
+
+## Building
+
+The library has no special requirements to build, other than an up-to-date .NET SDK, and can be built from within the IDE or with `dotnet build` at the command line.
+
+This repository also hosts the source for https://sshnet.github.io/SSH.NET/, which is built using [docfx](https://dotnet.github.io/docfx/index.html) and whose source files are in the `docfx/` directory. In order to build the site, install the docfx dotnet tool with `dotnet tool update -g docfx` and then run `docfx docfx/docfx.json --serve` from the root of the repository. When it completes, you should see e.g.
+
+```
+Serving "E:\github\SSH.NET\docfx\_site" on http://localhost:8080. Press Ctrl+C to shut down.
+```
+
+from which you can view the local version of the site. When making iterative changes, run `docfx docfx/docfx.json` from a separate command line and refresh the browser.
+
+## Testing
+
+The library has a test project for unit tests and a test project for integration tests. The latter uses [Testcontainers](https://dotnet.testcontainers.org/) which has a dependency on Docker. Practically, on Windows, an installation of Docker Desktop is all that is required, without any additional configuration. With Docker Desktop running, the integration tests can run like normal tests from within the IDE or with `dotnet test` at the command line.
+
+Code coverage information can be generated for all test projects at once or for individual test projects. From the root of the repository or from the individual test project directory, run `dotnet test --collect:"XPlat Code Coverage"`.
+
+The coverage information can be visualised using e.g. [ReportGenerator](https://reportgenerator.io/). Install the ReportGenerator dotnet tool with `dotnet tool update -g dotnet-reportgenerator-globaltool` and then run
+
+```
+reportgenerator -reports:**/coverage.cobertura.xml -targetdir:TestResults/CoverageReport -assemblyfilters:+Renci.SshNet
+```
+
+View the report by opening TestResults/CoverageReport/index.html in the browser.
+
+Before subsequent coverage collections, delete the previous collections with `git clean -fX test/` to prevent previous coverage files from being included in the subsequent generated report.
+
+## CI
+
+The repository makes use of continuous integration (CI) on [AppVeyor](https://ci.appveyor.com/project/drieseng/ssh-net/history) to validate builds and tests on PR branches and non-PR branches. At the time of writing, some tests can occasionally fail in CI due to a dependency on timing or a dependency on networking/socket code. If you see an existing test which is unrelated to your changes occasionally failing in CI but passing locally, you probably don't need to worry about it. If you see one of your newly-added tests failing, it is probably worth investigating why and whether it can be made more stable.
+
+## Good to know
+
+### TraceSource logging
+
+The Debug build of SSH.NET contains rudimentary logging functionality via `System.Diagnostics.TraceSource`. See `Renci.SshNet.Abstractions.DiagnosticAbstraction` for usage examples.
+
+### Wireshark
+
+Wireshark is able to dissect initial connection packets, such as key exchange, before encryption happens. Enter "ssh" as the display filter. See https://wiki.wireshark.org/SSH.md for more information.

README.md

@@ -14,15 +14,8 @@ to achieve the best performance possible.
 
 ## Documentation
 
-There is MSDN-style class documentation in a .chm file for each release, which you can find in the Assets section
-of the [latest release](https://github.com/sshnet/SSH.NET/releases/latest) page.  Please note that you will need
-to [right-click and "unblock"](https://support.microsoft.com/en-us/help/2021383/some-chm-files-may-not-render-properly-on-windows-vista-and-windows-7)
-the CHM file after you download it.
-
-Currently (4/18/2020), the documentation is very sparse.  Fortunately, there are a large number of tests in
-[Renci.SshNet.Tests](https://github.com/sshnet/SSH.NET/tree/develop/test/Renci.SshNet.Tests) that demonstrate
-usage with working code.
-
+Documentation is hosted at https://sshnet.github.io/SSH.NET/. Currently (4/18/2020), the documentation is very sparse.
+Fortunately, there are a large number of [tests](https://github.com/sshnet/SSH.NET/tree/develop/test/) that demonstrate usage with working code.
 If the test for the functionality you would like to see documented is not complete, then you are cordially
 invited to read the source, Luke, and highly encouraged to generate a pull request for the implementation of
 the missing test once you figure things out.  🤓
@@ -45,13 +38,15 @@ the missing test once you figure things out.  🤓
 ## Encryption Method
 
 **SSH.NET** supports the following encryption methods:
+* aes128-ctr
+* aes192-ctr
 * aes256-ctr
-* 3des-cbc
+* aes128-gcm<span></span>@openssh.com (.NET 6 and higher)
+* aes256-gcm<span></span>@openssh.com (.NET 6 and higher)
 * aes128-cbc
 * aes192-cbc
 * aes256-cbc
-* aes128-gcm<span></span>@openssh.com (.NET 6 and higher)
-* aes256-gcm<span></span>@openssh.com (.NET 6 and higher)
+* 3des-cbc
 * blowfish-cbc
 * twofish-cbc
 * twofish192-cbc
@@ -61,8 +56,6 @@ the missing test once you figure things out.  🤓
 * arcfour128
 * arcfour256
 * cast128-cbc
-* aes128-ctr
-* aes192-ctr
 
 ## Key Exchange Method
 
@@ -82,10 +75,10 @@ the missing test once you figure things out.  🤓
 ## Public Key Authentication
 
 **SSH.NET** supports the following private key formats:
-* RSA in OpenSSL PEM and ssh.com format
-* DSA in OpenSSL PEM and ssh.com format
-* ECDSA 256/384/521 in OpenSSL PEM format
-* ECDSA 256/384/521, ED25519 and RSA in OpenSSH key format
+* RSA in OpenSSL PEM ("BEGIN RSA PRIVATE KEY") and ssh.com ("BEGIN SSH2 ENCRYPTED PRIVATE KEY") format
+* DSA in OpenSSL PEM ("BEGIN DSA PRIVATE KEY") and ssh.com ("BEGIN SSH2 ENCRYPTED PRIVATE KEY") format
+* ECDSA 256/384/521 in OpenSSL PEM format ("BEGIN EC PRIVATE KEY")
+* ECDSA 256/384/521, ED25519 and RSA in OpenSSH key format ("BEGIN OPENSSH PRIVATE KEY")
 
 Private keys can be encrypted using one of the following cipher methods:
 * DES-EDE3-CBC
@@ -110,21 +103,20 @@ Private keys can be encrypted using one of the following cipher methods:
 ## Message Authentication Code
 
 **SSH.NET** supports the following MAC algorithms:
-* hmac-md5
-* hmac-md5-96
-* hmac-sha1
-* hmac-sha1-96
 * hmac-sha2-256
-* hmac-sha2-256-96
 * hmac-sha2-512
 * hmac-sha2-512-96
-* hmac-md5-etm<span></span>@openssh.com
-* hmac-md5-96-etm<span></span>@openssh.com
-* hmac-sha1-etm<span></span>@openssh.com
-* hmac-sha1-96-etm<span></span>@openssh.com
+* hmac-sha2-256-96
+* hmac-sha1
+* hmac-sha1-96
+* hmac-md5
+* hmac-md5-96
 * hmac-sha2-256-etm<span></span>@openssh.com
 * hmac-sha2-512-etm<span></span>@openssh.com
-
+* hmac-sha1-etm<span></span>@openssh.com
+* hmac-sha1-96-etm<span></span>@openssh.com
+* hmac-md5-etm<span></span>@openssh.com
+* hmac-md5-96-etm<span></span>@openssh.com
 
 ## Compression
 
@@ -174,6 +166,10 @@ using (var client = new SshClient("sftp.foo.com", "guest", "pwd"))
 }
 ```
 
+## Building the library
+
+The library has no special requirements to build, other than an up-to-date .NET SDK. See also [CONTRIBUTING.md](https://github.com/sshnet/SSH.NET/blob/develop/CONTRIBUTING.md).
+
 ## Supporting SSH.NET
 
 Do you or your company rely on **SSH.NET** in your projects? If you want to encourage us to keep on going and show us that you appreciate our work, please consider becoming a [sponsor](https://github.com/sponsors/sshnet) through GitHub Sponsors.

docfx/docfx.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
   "metadata": [
     {
       "src": [
@@ -10,85 +11,7 @@
         }
       ],
       "outputFormat": "apiPage",
-      "dest": "net462",
-      "properties": {
-        "TargetFramework": "net462"
-      }
-    },
-    {
-      "src": [
-        {
-          "src": "../src",
-          "files": [
-            "**/*.csproj"
-          ]
-        }
-      ],
-      "outputFormat": "apiPage",
-      "dest": "netstandard2.0",
-      "properties": {
-        "TargetFramework": "netstandard2.0"
-      }
-    },
-    {
-      "src": [
-        {
-          "src": "../src",
-          "files": [
-            "**/*.csproj"
-          ]
-        }
-      ],
-      "outputFormat": "apiPage",
-      "dest": "netstandard2.1",
-      "properties": {
-        "TargetFramework": "netstandard2.1"
-      }
-    },
-    {
-      "src": [
-        {
-          "src": "../src",
-          "files": [
-            "**/*.csproj"
-          ]
-        }
-      ],
-      "outputFormat": "apiPage",
-      "dest": "net6.0",
-      "properties": {
-        "TargetFramework": "net6.0"
-      }
-    },
-    {
-      "src": [
-        {
-          "src": "../src",
-          "files": [
-            "**/*.csproj"
-          ]
-        }
-      ],
-      "outputFormat": "apiPage",
-      "dest": "net7.0",
-      "properties": {
-        "TargetFramework": "net7.0"
-      }
-    },
-    {
-      "src": [
-        {
-          "src": "../src",
-          "files": [
-            "**/*.csproj"
-          ]
-        }
-      ],
-      "outputFormat": "apiPage",
-      "dest": "net8.0",
-      "properties": {
-        "TargetFramework": "net8.0"
-      }
+      "output": "api"
     }
   ],
   "build": {
@@ -110,7 +33,8 @@
     "output": "_site",
     "template": [
       "default",
-      "modern"
+      "modern",
+      "template"
     ],
     "globalMetadata": {
       "_appName": "SSH.NET",

docfx/docs/features.md

@@ -1,102 +0,0 @@
-# Features
-
-* Execution of SSH command using both synchronous and asynchronous methods
-* Return command execution exit status and other information
-* Provide SFTP functionality for both synchronous and asynchronous operations
-* Provides SCP functionality
-* Provide status report for upload and download sftp operations to allow accurate progress bar implementation
-* Remote, dynamic and local port forwarding
-* Shell/Terminal implementation
-* Specify key file pass phrase
-* Use multiple key files to authenticate
-* Supports publickey, password and keyboard-interactive authentication methods
-* Supports two-factor or higher authentication
-* Supports SOCKS4, SOCKS5 and HTTP Proxy
-
-## Encryption Method
-
-**SSH.NET** supports the following encryption methods:
-* aes256-ctr
-* 3des-cbc
-* aes128-cbc
-* aes192-cbc
-* aes256-cbc
-* blowfish-cbc
-* twofish-cbc
-* twofish192-cbc
-* twofish128-cbc
-* twofish256-cbc
-* arcfour
-* arcfour128
-* arcfour256
-* cast128-cbc
-* aes128-ctr
-* aes192-ctr
-
-## Key Exchange Method
-
-**SSH.NET** supports the following key exchange methods:
-* curve25519-sha256
-* curve25519-sha256<span></span>@libssh.org
-* ecdh-sha2-nistp256
-* ecdh-sha2-nistp384
-* ecdh-sha2-nistp521
-* diffie-hellman-group-exchange-sha256
-* diffie-hellman-group-exchange-sha1
-* diffie-hellman-group16-sha512
-* diffie-hellman-group14-sha256
-* diffie-hellman-group14-sha1
-* diffie-hellman-group1-sha1
-
-## Public Key Authentication
-
-**SSH.NET** supports the following private key formats:
-* RSA in OpenSSL PEM and ssh.com format
-* DSA in OpenSSL PEM and ssh.com format
-* ECDSA 256/384/521 in OpenSSL PEM format
-* ECDSA 256/384/521, ED25519 and RSA in OpenSSH key format
-
-Private keys can be encrypted using one of the following cipher methods:
-* DES-EDE3-CBC
-* DES-EDE3-CFB
-* DES-CBC
-* AES-128-CBC
-* AES-192-CBC
-* AES-256-CBC
-
-## Host Key Algorithms
-
-**SSH.NET** supports the following host key algorithms:
-* ssh-ed25519
-* ecdsa-sha2-nistp256
-* ecdsa-sha2-nistp384
-* ecdsa-sha2-nistp521
-* rsa-sha2-512
-* rsa-sha2-256
-* ssh-rsa
-* ssh-dss
-
-## Message Authentication Code
-
-**SSH.NET** supports the following MAC algorithms:
-* hmac-md5
-* hmac-md5-96
-* hmac-sha1
-* hmac-sha1-96
-* hmac-sha2-256
-* hmac-sha2-256-96
-* hmac-sha2-512
-* hmac-sha2-512-96
-* hmac-md5-etm<span></span>@openssh.com
-* hmac-md5-96-etm<span></span>@openssh.com
-* hmac-sha1-etm<span></span>@openssh.com
-* hmac-sha1-96-etm<span></span>@openssh.com
-* hmac-sha2-256-etm<span></span>@openssh.com
-* hmac-sha2-512-etm<span></span>@openssh.com
-
-## Framework Support
-
-**SSH.NET** supports the following target frameworks:
-* .NETFramework 4.6.2 (and higher)
-* .NET Standard 2.0 and 2.1
-* .NET 6 (and higher)

docfx/docs/foreword.md

@@ -1,14 +0,0 @@
-# Foreword
-
-There is MSDN-style class documentation in a .chm file for each release, which you can find in the Assets section
-of the [latest release](https://github.com/sshnet/SSH.NET/releases/latest) page.  Please note that you will need
-to [right-click and "unblock"](https://support.microsoft.com/en-us/help/2021383/some-chm-files-may-not-render-properly-on-windows-vista-and-windows-7)
-the CHM file after you download it.
-
-Currently (4/18/2020), the documentation is very sparse.  Fortunately, there are a large number of tests in
-[Renci.SshNet.Tests](https://github.com/sshnet/SSH.NET/tree/develop/test/Renci.SshNet.Tests) that demonstrate
-usage with working code.
-
-If the test for the functionality you would like to see documented is not complete, then you are cordially
-invited to read the source, Luke, and highly encouraged to generate a pull request for the implementation of
-the missing test once you figure things out.  🤓

docfx/docs/toc.yml

@@ -1,6 +0,0 @@
-- name: Foreword
-  href: foreword.md
-- name: Features
-  href: features.md
-- name: Usage
-  href: usage.md

docfx/docs/usage.md

@@ -1,34 +0,0 @@
-# Usage
-
-## Multi-factor authentication
-
-Establish a SFTP connection using both password and public-key authentication:
-
-```cs
-var connectionInfo = new ConnectionInfo("sftp.foo.com",
-                                        "guest",
-                                        new PasswordAuthenticationMethod("guest", "pwd"),
-                                        new PrivateKeyAuthenticationMethod("rsa.key"));
-using (var client = new SftpClient(connectionInfo))
-{
-    client.Connect();
-}
-
-```
-
-## Verify host identify
-
-Establish a SSH connection using user name and password, and reject the connection if the fingerprint of the server does not match the expected fingerprint:
-
-```cs
-string expectedFingerPrint = "LKOy5LvmtEe17S4lyxVXqvs7uPMy+yF79MQpHeCs/Qo";
-
-using (var client = new SshClient("sftp.foo.com", "guest", "pwd"))
-{
-    client.HostKeyReceived += (sender, e) =>
-        {
-            e.CanTrust = expectedFingerPrint.Equals(e.FingerPrintSHA256);
-        };
-    client.Connect();
-}
-```

docfx/examples.md

@@ -0,0 +1,89 @@
+Think this page is lacking? Help wanted! Click "Edit this page" at the bottom to begin contributing more examples.
+
+### Upload and list files
+
+```cs
+using (var client = new SftpClient("sftp.foo.com", "guest", "pwd"))
+{
+    client.Connect();
+
+    using (FileStream fs = File.OpenRead(@"C:\tmp\test-file.txt"))
+    {
+        client.UploadFile(fs, "/home/guest/test-file.txt");
+    }
+
+    foreach (ISftpFile file in client.ListDirectory("/home/guest/"))
+    {
+        Console.WriteLine($"{file.FullName} {file.LastWriteTime}");
+    }
+}
+```
+
+### Multi-factor authentication
+
+Establish an SFTP connection using both password and public-key authentication:
+
+```cs
+var connectionInfo = new ConnectionInfo("sftp.foo.com",
+                                        "guest",
+                                        new PasswordAuthenticationMethod("guest", "pwd"),
+                                        new PrivateKeyAuthenticationMethod("path/to/my/key"));
+using (var client = new SftpClient(connectionInfo))
+{
+    client.Connect();
+}
+```
+
+### Verify host identify
+
+Establish an SSH connection using user name and password, and reject the connection if the fingerprint of the server does not match the expected fingerprint:
+
+```cs
+string expectedFingerPrint = "LKOy5LvmtEe17S4lyxVXqvs7uPMy+yF79MQpHeCs/Qo";
+
+using (var client = new SshClient("sftp.foo.com", "guest", "pwd"))
+{
+    client.HostKeyReceived += (sender, e) =>
+        {
+            e.CanTrust = expectedFingerPrint.Equals(e.FingerPrintSHA256);
+        };
+    client.Connect();
+}
+```
+
+### Run a command
+
+Establish an SSH connection and run a command:
+
+```cs
+using (var client = new SshClient("sftp.foo.com", "guest", new PrivateKeyFile("path/to/my/key")))
+{
+    client.Connect();
+    SshCommand cmd = client.RunCommand("echo 'Hello World!'");
+    Console.WriteLine(cmd.Result); // "Hello World!\n"
+}
+```
+
+### Stream data to a command
+
+```cs
+using (var client = new SshClient("sftp.foo.com", "guest", "pwd"))
+{
+    client.Connect();
+
+    // Make the server echo back the input file with "cat"
+    using (SshCommand command = client.CreateCommand("cat"))
+    {
+        IAsyncResult asyncResult = command.BeginExecute();
+
+        using (Stream inputStream = command.CreateInputStream())
+        {
+            inputStream.Write("Hello World!"u8);
+        }
+
+        string result = command.EndExecute(asyncResult);
+
+        Console.WriteLine(result); // "Hello World!"
+    }
+}
+```

docfx/index.md

@@ -2,18 +2,4 @@
 _layout: landing
 ---
 
-SSH.NET is a Secure Shell (SSH-2) library for .NET, optimized for parallelism.
-
-[![Version](https://img.shields.io/nuget/vpre/SSH.NET.svg)](https://www.nuget.org/packages/SSH.NET)
-[![NuGet download count](https://img.shields.io/nuget/dt/SSH.NET.svg)](https://www.nuget.org/packages/SSH.NET)
-[![Build status](https://ci.appveyor.com/api/projects/status/ih77qu6tap3o92gu/branch/develop?svg=true)](https://ci.appveyor.com/api/projects/status/ih77qu6tap3o92gu/branch/develop)
-
-## Introduction
-
-This project was inspired by **Sharp.SSH** library which was ported from java and it seems like was not supported
-for quite some time. This library is a complete rewrite, without any third party dependencies, using parallelism
-to achieve the best performance possible.
-
-## Supporting SSH.NET
-
-Do you or your company rely on **SSH.NET** in your projects? If you want to encourage us to keep on going and show us that you appreciate our work, please consider becoming a [sponsor](https://github.com/sponsors/sshnet) through GitHub Sponsors.
+[!INCLUDE [README](../README.md)]

docfx/template/public/main.js

@@ -0,0 +1,9 @@
+export default {
+    iconLinks: [
+      {
+        icon: 'github',
+        href: 'https://github.com/sshnet/SSH.NET',
+        title: 'GitHub'
+      }
+    ]
+  }

docfx/toc.yml

@@ -1,14 +1,6 @@
-- name: Docs
-  href: docs/
-- name: .NET Framework 4.6.2
-  href: net462/
-- name: .NET Standard 2.0
-  href: netstandard2.0/
-- name: .NET Standard 2.1
-  href: netstandard2.1/
-- name: .NET 6.0
-  href: net6.0/
-- name: .NET 7.0
-  href: net7.0/
-- name: .NET 8.0
-  href: net8.0/
+- name: Overview
+  href: index.md
+- name: Examples
+  href: examples.md
+- name: API
+  href: api/

src/Renci.SshNet/HashInfo.cs

@@ -19,7 +19,7 @@ namespace Renci.SshNet
         public int KeySize { get; private set; }
 
         /// <summary>
-        /// Gets a value indicating whether enable encrypt-then-MAC or use encrypt-and-MAC.
+        /// Gets a value indicating whether the MAC algorithm will use encrypt-then-MAC ordering.
         /// </summary>
         /// <value>
         /// <see langword="true"/> to enable encrypt-then-MAC, <see langword="false"/> to use encrypt-and-MAC.
@@ -27,7 +27,8 @@ namespace Renci.SshNet
         public bool IsEncryptThenMAC { get; private set; }
 
         /// <summary>
-        /// Gets the cipher.
+        /// Gets the method for creating a <see cref="System.Security.Cryptography.HashAlgorithm"/> instance
+        /// given a key.
         /// </summary>
         public Func<byte[], HashAlgorithm> HashAlgorithm { get; private set; }