diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..ebcbc7387 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,48 @@ +name: Docs + +on: + push: + branches: ["master"] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Pages + uses: actions/configure-pages@v4 + + - name: Setup .NET 8.0 + uses: actions/setup-dotnet@v4 + with: + dotnet-version: 8.x + + - name: Setup docfx + run: dotnet tool update -g docfx + + - name: Build documentation + run: docfx ./docfx/docfx.json + + - name: Upload documentation + uses: actions/upload-pages-artifact@v3 + with: + path: './docfx/_site' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 5311c022d..b174a53f6 100644 --- a/.gitignore +++ b/.gitignore @@ -485,3 +485,12 @@ $RECYCLE.BIN/ # Build outputs build/target/ + +# Docs +docfx/_site/** +docfx/net462/** +docfx/netstandard2.0/** +docfx/netstandard2.1/** +docfx/net6.0/** +docfx/net7.0/** +docfx/net8.0/** diff --git a/README.md b/README.md index 84e665bd9..fd869601d 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,13 @@ SSH.NET is a Secure Shell (SSH-2) library for .NET, optimized for parallelism. [![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. ## 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) @@ -26,6 +28,7 @@ invited to read the source, Luke, and highly encouraged to generate a pull reque the missing test once you figure things out. 🤓 ## 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 @@ -121,6 +124,7 @@ Private keys can be encrypted using one of the following cipher methods: * hmac-sha2-512-etm@openssh.com ## Framework Support + **SSH.NET** supports the following target frameworks: * .NETFramework 4.6.2 (and higher) * .NET Standard 2.0 and 2.1 diff --git a/docfx/docfx.json b/docfx/docfx.json new file mode 100644 index 000000000..1911fe923 --- /dev/null +++ b/docfx/docfx.json @@ -0,0 +1,124 @@ +{ + "metadata": [ + { + "src": [ + { + "src": "../src", + "files": [ + "**/*.csproj" + ] + } + ], + "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" + } + } + ], + "build": { + "content": [ + { + "files": "**/*.{md,yml}", + "exclude": [ + "_site/**" + ] + } + ], + "resource": [ + { + "files": [ + "images/**" + ] + } + ], + "output": "_site", + "template": [ + "default", + "modern" + ], + "globalMetadata": { + "_appName": "SSH.NET", + "_appTitle": "SSH.NET - A Secure Shell (SSH) library for .NET, optimized for parallelism", + "_appLogoPath": "images/logo.png", + "_appFaviconPath": "images/icon.png", + "_appFooter": "Copyright (c) Renci, Oleg Kapeljushnik, Gert Driesen and contributors", + "_enableSearch": true + } + } +} diff --git a/docfx/docs/features.md b/docfx/docs/features.md new file mode 100644 index 000000000..229296f53 --- /dev/null +++ b/docfx/docs/features.md @@ -0,0 +1,102 @@ +# 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@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@openssh.com +* hmac-md5-96-etm@openssh.com +* hmac-sha1-etm@openssh.com +* hmac-sha1-96-etm@openssh.com +* hmac-sha2-256-etm@openssh.com +* hmac-sha2-512-etm@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) diff --git a/docfx/docs/foreword.md b/docfx/docs/foreword.md new file mode 100644 index 000000000..574c20572 --- /dev/null +++ b/docfx/docs/foreword.md @@ -0,0 +1,14 @@ +# 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. 🤓 diff --git a/docfx/docs/toc.yml b/docfx/docs/toc.yml new file mode 100644 index 000000000..35a71c825 --- /dev/null +++ b/docfx/docs/toc.yml @@ -0,0 +1,6 @@ +- name: Foreword + href: foreword.md +- name: Features + href: features.md +- name: Usage + href: usage.md diff --git a/docfx/docs/usage.md b/docfx/docs/usage.md new file mode 100644 index 000000000..e7d9bec03 --- /dev/null +++ b/docfx/docs/usage.md @@ -0,0 +1,34 @@ +# 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(); +} +``` diff --git a/docfx/images/icon.png b/docfx/images/icon.png new file mode 100644 index 000000000..3e993a749 Binary files /dev/null and b/docfx/images/icon.png differ diff --git a/docfx/images/logo.png b/docfx/images/logo.png new file mode 100644 index 000000000..0d034115d Binary files /dev/null and b/docfx/images/logo.png differ diff --git a/docfx/index.md b/docfx/index.md new file mode 100644 index 000000000..da3c1be30 --- /dev/null +++ b/docfx/index.md @@ -0,0 +1,19 @@ +--- +_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. diff --git a/docfx/toc.yml b/docfx/toc.yml new file mode 100644 index 000000000..575116eeb --- /dev/null +++ b/docfx/toc.yml @@ -0,0 +1,14 @@ +- 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/ diff --git a/src/Renci.SshNet/Common/AsyncResult{TResult}.cs b/src/Renci.SshNet/Common/AsyncResult`1.cs similarity index 100% rename from src/Renci.SshNet/Common/AsyncResult{TResult}.cs rename to src/Renci.SshNet/Common/AsyncResult`1.cs diff --git a/src/Renci.SshNet/MessageEventArgs.cs b/src/Renci.SshNet/MessageEventArgs`1.cs similarity index 100% rename from src/Renci.SshNet/MessageEventArgs.cs rename to src/Renci.SshNet/MessageEventArgs`1.cs diff --git a/stylecop.json b/stylecop.json index ff7c9dbfb..ba2a35715 100644 --- a/stylecop.json +++ b/stylecop.json @@ -3,7 +3,8 @@ "settings": { "documentationRules": { "xmlHeader": false, - "documentInternalElements": false + "documentInternalElements": false, + "fileNamingConvention": "metadata" }, "layoutRules": { "newlineAtEndOfFile": "require" diff --git a/test/Renci.SshNet.IntegrationTests/Common/ArrayBuilder.cs b/test/Renci.SshNet.IntegrationTests/Common/ArrayBuilder`1.cs similarity index 100% rename from test/Renci.SshNet.IntegrationTests/Common/ArrayBuilder.cs rename to test/Renci.SshNet.IntegrationTests/Common/ArrayBuilder`1.cs diff --git a/test/Renci.SshNet.Tests/Common/ArrayBuilder.cs b/test/Renci.SshNet.Tests/Common/ArrayBuilder`1.cs similarity index 100% rename from test/Renci.SshNet.Tests/Common/ArrayBuilder.cs rename to test/Renci.SshNet.Tests/Common/ArrayBuilder`1.cs