[Ready to ship: May 10] SSH Security Key Support (GA) (#18557)

* add procedure for generating SSH for physical key

* Mention hardware security keys in "About SSH"

* Create troubleshooting article

* Add procedure for SHH key generation for sk

* fix broken link

* Incorporate reviewer feedback

* update versioning

* Clarify unknown error troubleshoot procedure

* Add troubleshooting to procedure

* Clean up inline links

* Update more inline links

* Update troubleshooting procedure

* fix broken link with versioning

* Add warning about installing OpenSSH

* Update note about algorithm for legacy key types

* Add last step for security keys

* Fix variable name

* Add reviewer feedback

* Include other error text

Co-authored-by: Kevin Jones <vcsjones@github.com>

* Include ref to OpenSSH release notes

* fix failing test

Co-authored-by: Kevin Jones <vcsjones@github.com>
Co-authored-by: Melanie Yarbrough <11952755+myarb@users.noreply.github.com>

content/github/authenticating-to-github/about-ssh.md

@@ -11,11 +11,13 @@ topics:
   - SSH
 ---
 
-When you set up SSH, you'll [generate an SSH key and add it to the ssh-agent](/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) and then [add the key to your {% data variables.product.product_name %} account](/articles/adding-a-new-ssh-key-to-your-github-account). Adding the SSH key to the ssh-agent ensures that your SSH key has an extra layer of security through the use of a passphrase. For more information, see "[Working with SSH key passphrases](/articles/working-with-ssh-key-passphrases)."
+When you set up SSH, you will need to generate a new SSH key and add it to the ssh-agent. You must add the SSH key to your account on {% data variables.product.product_name %} before you use the key to authenticate. For more information, see "[Generating a new SSH key and adding it to the ssh-agent](/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)" and "[Adding a new SSH key to your {% data variables.product.prodname_dotcom %} account](/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account)."
 
-{% if currentVersion == "free-pro-team@latest" %}To use your SSH key with a repository owned by an organization that uses SAML single sign-on, you'll need to authorize it first. For more information, see "[Authorizing an SSH key for use with SAML single sign-on](/articles/authorizing-an-ssh-key-for-use-with-saml-single-sign-on)."{% endif %}
+You can further secure your SSH key by using a hardware security key, which requires the physical hardware security key to be attached to your computer when the key pair is used to authenticate with SSH. You can also secure your SSH key by adding your key to the ssh-agent and using a passphrase. For more information, see "[Working with SSH key passphrases](/github/authenticating-to-github/working-with-ssh-key-passphrases)."
 
-We recommend that you regularly [review your SSH keys list](/articles/reviewing-your-ssh-keys) and revoke any that are invalid or have been compromised.
+{% if currentVersion == "free-pro-team@latest" %}To use your SSH key with a repository owned by an organization that uses SAML single sign-on, you must authorize the key. For more information, see "[Authorizing an SSH key for use with SAML single sign-on](/articles/authorizing-an-ssh-key-for-use-with-saml-single-sign-on)."{% endif %}
+
+To maintain account security, you can regularly review your SSH keys list and revoke any keys that are invalid or have been compromised. For more information, see "[Reviewing your SSH keys](/github/authenticating-to-github/reviewing-your-ssh-keys)."
 
 {% if currentVersion == "free-pro-team@latest" %}
 If you haven't used your SSH key for a year, then {% data variables.product.prodname_dotcom %} will automatically delete your inactive SSH key as a security precaution. For more information, see "[Deleted or missing SSH keys](/articles/deleted-or-missing-ssh-keys)."
@@ -27,8 +29,4 @@ If you're a member of an organization that provides SSH certificates, you can us
 
 - "[Checking for existing SSH keys](/articles/checking-for-existing-ssh-keys)"
 - "[Testing your SSH connection](/articles/testing-your-ssh-connection)"
-- "[Working with SSH key passphrases](/articles/working-with-ssh-key-passphrases)"
 - "[Troubleshooting SSH](/articles/troubleshooting-ssh)"
-{%- if currentVersion == "free-pro-team@latest" %}
-- "[Authorizing an SSH key for use with SAML single sign-on](/articles/authorizing-an-ssh-key-for-use-with-saml-single-sign-on)"
-{%- endif %}

content/github/authenticating-to-github/error-unknown-key-type.md

@@ -0,0 +1,35 @@
+---
+title: 'Error: Unknown key type'
+intro: 'This error means that the SSH key type you used was unrecognized or is unsupported by your SSH client. '
+versions:
+  free-pro-team: '*'
+  enterprise-server: '>=3.2'
+  github-ae: 'next'
+topics:
+  - SSH
+---
+
+### About the `unknown key type` error
+
+When you generate a new SSH key, you may receive an `unknown key type` error if your SSH client does not support the key type that you specify.{% mac %}To solve this issue on macOS, you can update your SSH client or install a new SSH client.
+
+### Prerequisites
+
+You must have Homebrew installed. For more information, see the [installation guide](https://docs.brew.sh/Installation) in the Homebrew documentation.
+
+### Solving the issue
+
+{% warning %}
+
+**Warning:** If you install OpenSSH, your computer will not be able to retrieve passphrases that are stored in the Apple keychain. You will need to enter your passphrase or interact with your hardware security key every time you authenticate with SSH to {% data variables.product.prodname_dotcom %} or another web service.
+
+If you remove OpenSSH, the passphrases that are stored in your keychain will once again be retrievable. You can remove OpenSSH by entering the command `brew uninstall openssh` in Terminal.
+
+{% endwarning %}
+
+1. Open Terminal.
+2. Enter the command `brew install openssh`.
+3. Quit and relaunch Terminal.
+4. Try the procedure for generating a new SSH key again. For more information, see "[Generating a new SSH key and adding it to the ssh-agent](/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key-for-a-hardware-security-key)."
+
+{% endmac %}{% linux %}To solve this issue on Linux, use the package manager for your Linux distribution to install a new version of OpenSSH, or compile a new version from source. If you install a different version of OpenSSH, the ability of other applications to authenticate via SSH may be affected. For more information, review the documentation for your distribution.{% endlinux %}

content/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent.md

@@ -13,9 +13,16 @@ topics:
   - SSH
 ---
 
-If you don't already have an SSH key, you must [generate a new SSH key](#generating-a-new-ssh-key). If you're unsure whether you already have an SSH key, check for [existing keys](/articles/checking-for-existing-ssh-keys).
+### About SSH key generation
 
-If you don't want to reenter your passphrase every time you use your SSH key, you can [add your key to the SSH agent](#adding-your-ssh-key-to-the-ssh-agent), which manages your SSH keys and remembers your passphrase.
+If you don't already have an SSH key, you must generate a new SSH key to use for authentication. If you're unsure whether you already have an SSH key, you can check for existing keys. For more information, see "[Checking for existing SSH keys](/github/authenticating-to-github/checking-for-existing-ssh-keys)."
+
+{% if currentVersion == "free-pro-team@latest" %}
+
+If you want to use a hardware security key to authenticate to {% data variables.product.product_name %}, you must generate a new SSH key for your hardware security key. You must connect your hardware security key to your computer when you authenticate with the key pair. For more information, see the [OpenSSH 8.2 release notes](https://www.openssh.com/txt/release-8.2).
+
+{% endif %}
+If you don't want to reenter your passphrase every time you use your SSH key, you can add your key to the SSH agent, which manages your SSH keys and remembers your passphrase.
 
 ### Generating a new SSH key
 
@@ -62,7 +69,7 @@ If you don't want to reenter your passphrase every time you use your SSH key, yo
 
   {% endlinux %}
 
-4. At the prompt, type a secure passphrase. For more information, see ["Working with SSH key passphrases"](/articles/working-with-ssh-key-passphrases).
+4. At the prompt, type a secure passphrase. For more information, see ["Working with SSH key passphrases](/articles/working-with-ssh-key-passphrases)."
   ```shell
   > Enter passphrase (empty for no passphrase): <em>[Type a passphrase]</em>
   > Enter same passphrase again: <em>[Type passphrase again]</em>
@@ -70,7 +77,7 @@ If you don't want to reenter your passphrase every time you use your SSH key, yo
 
 ### Adding your SSH key to the ssh-agent
 
-Before adding a new SSH key to the ssh-agent to manage your keys, you should have [checked for existing SSH keys](/articles/checking-for-existing-ssh-keys) and [generated a new SSH key](/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key). <span class="platform-mac">When adding your SSH key to the agent, use the default macOS `ssh-add` command, and not an application installed by [macports](https://www.macports.org/), [homebrew](http://brew.sh/), or some other external source.</span>
+Before adding a new SSH key to the ssh-agent to manage your keys, you should have checked for existing SSH keys and generated a new SSH key. <span class="platform-mac">When adding your SSH key to the agent, use the default macOS `ssh-add` command, and not an application installed by [macports](https://www.macports.org/), [homebrew](http://brew.sh/), or some other external source.</span>
 
 {% mac %}
 
@@ -137,7 +144,7 @@ Before adding a new SSH key to the ssh-agent to manage your keys, you should hav
 
   {% endnote %}
 
-4. [Add the SSH key to your GitHub account](/articles/adding-a-new-ssh-key-to-your-github-account).
+4. Add the SSH key to your account on {% data variables.product.product_name %}. For more information, see "[Adding a new SSH key to your {% data variables.product.prodname_dotcom %} account](/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account)."
 
 {% endmac %}
 
@@ -155,7 +162,7 @@ Before adding a new SSH key to the ssh-agent to manage your keys, you should hav
 2. Add your SSH private key to the ssh-agent. {% data reusables.ssh.add-ssh-key-to-ssh-agent %}
    {% data reusables.ssh.add-ssh-key-to-ssh-agent-commandline %}
 
-3. [Add the SSH key to your GitHub account](/articles/adding-a-new-ssh-key-to-your-github-account).
+3. Add the SSH key to your account on {% data variables.product.product_name %}. For more information, see "[Adding a new SSH key to your {% data variables.product.prodname_dotcom %} account](/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account)."
 
 {% endwindows %}
 
@@ -166,10 +173,65 @@ Before adding a new SSH key to the ssh-agent to manage your keys, you should hav
 2. Add your SSH private key to the ssh-agent. {% data reusables.ssh.add-ssh-key-to-ssh-agent %}
    {% data reusables.ssh.add-ssh-key-to-ssh-agent-commandline %}
 
-3. [Add the SSH key to your GitHub account](/articles/adding-a-new-ssh-key-to-your-github-account).
+3. Add the SSH key to your account on {% data variables.product.product_name %}. For more information, see "[Adding a new SSH key to your {% data variables.product.prodname_dotcom %} account](/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account)."
 
 {% endlinux %}
 
+{% if currentVersion == "free-pro-team@latest" or currentVersion == "github-ae@next" or currentVersion ver_gt "enterprise-server@3.1"  %}
+### Generating a new SSH key for a hardware security key
+
+If you are using macOS or Linux, you may need to update your SSH client or install a new SSH client prior to generating a new SSH key. For more information, see "[Error: Unknown key type](/github/authenticating-to-github/error-unknown-key-type)."
+
+1. Insert your hardware security key into your computer.
+{% data reusables.command_line.open_the_multi_os_terminal %}
+3. Paste the text below, substituting in the email address for your account on {% data variables.product.product_name %}.
+  ```shell
+  $ ssh-keygen -t ed25519-sk -C "<em>your_email@example.com</em>"
+  ```
+  {% note %}
+
+  **Note:** If the command fails and you receive the error `invalid format` or `feature not supported,` you may be using a hardware security key that does not support the Ed25519 algorithm. Enter the following command instead.
+  ```shell
+   $ ssh-keygen -t ecdsa-sk -C "your_email@example.com"
+  ```
+
+  {% endnote %}  
+4. When you are prompted, touch the button on your hardware security key.
+5. When you are prompted to "Enter a file in which to save the key," press Enter to accept the default file location.
+
+  {% mac %}
+
+  ```shell
+  > Enter a file in which to save the key (/Users/<em>you</em>/.ssh/id_ed25519_sk): <em>[Press enter]</em>
+  ```
+
+  {% endmac %}
+
+  {% windows %}
+
+  ```shell
+  > Enter a file in which to save the key (/c/Users/<em>you</em>/.ssh/id_ed25519_sk):<em>[Press enter]</em>
+  ```
+
+  {% endwindows %}
+
+  {% linux %}
+
+  ```shell
+  > Enter a file in which to save the key (/home/<em>you</em>/.ssh/id_ed25519_sk): <em>[Press enter]</em>
+  ```
+
+  {% endlinux %}
+
+6. When you are prompted to type a passphrase, press **Enter**.
+  ```shell
+  > Enter passphrase (empty for no passphrase): <em>[Type a passphrase]</em>
+  > Enter same passphrase again: <em>[Type passphrase again]</em>
+  ```
+7. Add the SSH key to your account on {% data variables.product.prodname_dotcom %}. For more information, see "[Adding a new SSH key to your {% data variables.product.prodname_dotcom %} account](/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account)."
+
+{% endif %}
+
 ### Further reading
 
 - "[About SSH](/articles/about-ssh)"

content/github/authenticating-to-github/index.md

@@ -79,6 +79,7 @@ topics:
     {% link_in_list /error-agent-admitted-failure-to-sign %}
     {% link_in_list /error-ssh-add-illegal-option----k %}
     {% link_in_list /error-ssl-certificate-problem-verify-that-the-ca-cert-is-ok %}
+    {% link_in_list /error-unknown-key-type %}
     {% link_in_list /error-were-doing-an-ssh-key-audit %}
 {% topic_link_in_list /managing-commit-signature-verification %}
     {% link_in_list /about-commit-signature-verification %}