Add latest changes from gitlab-org/gitlab@14-8-stable-eev14.8.0-rc42

1 files changed, 85 insertions, 4 deletions

diff --git a/doc/ssh/index.md b/doc/ssh/index.md
index 6196ee5465b..35ca9a23179 100644
--- a/doc/ssh/index.md
+++ b/doc/ssh/index.md
@@ -1,6 +1,6 @@
 ---
 stage: Manage
-group: Authentication & Authorization
+group: Authentication and Authorization
 info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
 type: howto, reference
 ---
@@ -28,6 +28,8 @@ To view the version of SSH installed on your system, run `ssh -V`.
 To communicate with GitLab, you can use the following SSH key types:
 
 - [ED25519](#ed25519-ssh-keys)
+- [ED25519_SK](#ed25519_sk-ssh-keys) (Available in GitLab 14.8 and later.)
+- [ECDSA_SK](#ecdsa_sk-ssh-keys) (Available in GitLab 14.8 and later.)
 - [RSA](#rsa-ssh-keys)
 - DSA ([Deprecated](https://about.gitlab.com/releases/2018/06/22/gitlab-11-0-released/#support-for-dsa-ssh-keys) in GitLab 11.0.)
 - ECDSA (As noted in [Practical Cryptography With Go](https://leanpub.com/gocrypto/read#leanpub-auto-ecdsa), the security issues related to DSA also apply to ECDSA.)
@@ -42,6 +44,20 @@ suggests that [ED25519](https://ed25519.cr.yp.to/) keys are more secure and perf
 OpenSSH 6.5 introduced ED25519 SSH keys in 2014 and they should be available on most
 operating systems.
 
+### ED25519_SK SSH keys
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78934) in GitLab 14.8.
+
+To use ED25519_SK SSH keys on GitLab, your local client and GitLab server
+must have [OpenSSH 8.2](https://www.openssh.com/releasenotes.html#8.2) or later installed.
+
+### ECDSA_SK SSH keys
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78934) in GitLab 14.8.
+
+To use ECDSA_SK SSH keys on GitLab, your local client and GitLab server
+must have [OpenSSH 8.2](https://www.openssh.com/releasenotes.html#8.2) or later installed.
+
 ### RSA SSH keys
 
 Available documentation suggests that ED25519 is more secure than RSA.
@@ -64,6 +80,8 @@ Before you create a key pair, see if a key pair already exists.
    | Algorithm | Public key | Private key |
    | --------- | ---------- | ----------- |
    |  ED25519 (preferred)  | `id_ed25519.pub` | `id_ed25519` |
+   |  ED25519_SK | `id_ed25519_sk.pub` | `id_ed25519_sk` |
+   |  ECDSA_SK | `id_ecdsa_sk.pub` | `id_ecdsa_sk` |
    |  RSA (at least 2048-bit key size)     | `id_rsa.pub` | `id_rsa` |
    |  DSA (deprecated)      | `id_dsa.pub` | `id_dsa` |
    |  ECDSA    | `id_ecdsa.pub` | `id_ecdsa` |
@@ -177,6 +195,67 @@ OpenSSH format.
    ssh-keygen -o -t rsa -b 4096 -C "<comment>"
    ```
 
+## Generate an SSH key pair for a FIDO/U2F hardware security key
+
+To generate ED25519_SK or ECDSA_SK SSH keys, you must use OpenSSH 8.2 or later.
+
+1. Insert a hardware security key into your computer.
+1. Open a terminal.
+1. Type `ssh-keygen -t` followed by the key type and an optional comment.
+   This comment is included in the `.pub` file that's created.
+   You may want to use an email address for the comment.
+
+   For example, for ED25519_SK:
+
+   ```shell
+   ssh-keygen -t ed25519-sk -C "<comment>"
+   ```
+
+   For ECDSA_SK:
+
+   ```shell
+   ssh-keygen -t ecdsa-sk -C "<comment>"
+   ```
+
+   If your security key supports FIDO2 resident keys, you can enable this when
+   creating your SSH key:
+
+   ```shell
+   ssh-keygen -t ed25519-sk -O resident -C "<comment>"
+   ```
+
+   `-O resident` indicates that the key should be stored on the FIDO authenticator itself.
+   Resident key is easier to import to a new computer because it can be loaded directly
+   from the security key by [`ssh-add -K`](https://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man1/ssh-add.1#K)
+   or  [`ssh-keygen -K`](https://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man1/ssh-keygen#K).
+
+1. Select Enter. Output similar to the following is displayed:
+
+   ```plaintext
+   Generating public/private ed25519-sk key pair.
+   You may need to touch your authenticator to authorize key generation.
+   ```
+
+1. Touch the button on the hardware security key.
+
+1. Accept the suggested filename and directory:
+
+   ```plaintext
+   Enter file in which to save the key (/home/user/.ssh/id_ed25519_sk):
+   ```
+
+1. Specify a [passphrase](https://www.ssh.com/academy/ssh/passphrase):
+
+   ```plaintext
+   Enter passphrase (empty for no passphrase):
+   Enter same passphrase again:
+   ```
+
+1. A confirmation is displayed, including information about where your files are stored.
+
+A public and private key are generated.
+[Add the public SSH key to your GitLab account](#add-an-ssh-key-to-your-gitlab-account).
+
 ## Add an SSH key to your GitLab account
 
 To use SSH with GitLab, copy your public key to your GitLab account.
@@ -210,7 +289,8 @@ To use SSH with GitLab, copy your public key to your GitLab account.
 1. On the left sidebar, select **SSH Keys**.
 1. In the **Key** box, paste the contents of your public key.
    If you manually copied the key, make sure you copy the entire key,
-   which starts with `ssh-ed25519` or `ssh-rsa`, and may end with a comment.
+   which starts with `ssh-rsa`, `ssh-dss`, `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`,
+   `ssh-ed25519`, `sk-ecdsa-sha2-nistp256@openssh.com`, or `sk-ssh-ed25519@openssh.com`, and may end with a comment.
 1. In the **Title** box, type a description, like `Work Laptop` or
    `Home Workstation`.
 1. Optional. In the **Expires at** box, select an expiration date. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36243) in GitLab 12.9.)
@@ -219,7 +299,7 @@ To use SSH with GitLab, copy your public key to your GitLab account.
      you from using the key. Administrators can view expiration dates and use them for
      guidance when [deleting keys](../user/admin_area/credentials_inventory.md#delete-a-users-ssh-key).
    - GitLab 14.0 and later, the expiration date is enforced. Administrators can
-     [allow expired keys to be used](../user/admin_area/settings/account_and_limit_settings.md#allow-expired-ssh-keys-to-be-used).
+     [allow expired keys to be used](../user/admin_area/settings/account_and_limit_settings.md#allow-expired-ssh-keys-to-be-used-deprecated).
    - GitLab checks all SSH keys at 02:00 AM UTC every day. It emails an expiration notice for all SSH keys that expire on the current date. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.11.)
    - GitLab checks all SSH keys at 01:00 AM UTC every day. It emails an expiration notice for all SSH keys that are scheduled to expire seven days from now. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.11.)
 1. Select **Add key**.
@@ -318,7 +398,8 @@ on the files make them readable to you but not accessible to others.
 ## Configure two-factor authentication (2FA)
 
 You can set up two-factor authentication (2FA) for
-[Git over SSH](../security/two_factor_authentication.md#2fa-for-git-over-ssh-operations).
+[Git over SSH](../security/two_factor_authentication.md#2fa-for-git-over-ssh-operations). We recommend using
+[ED25519_SK](#ed25519_sk-ssh-keys) or [ECDSA_SK](#ecdsa_sk-ssh-keys) SSH keys.
 
 ## Use EGit on Eclipse