Merge branch...

Merge branch '207167-docs-fy2021-q1-okr-audit-and-improve-high-traffic-access-documentation' into 'master'

Update our GitLab and SSH documentation

See merge request gitlab-org/gitlab!27933

doc/ssh/README.md

@@ -4,158 +4,192 @@ type: howto, reference
 
 # GitLab and SSH keys
 
-Git is a distributed version control system, which means you can work locally
-but you can also share or "push" your changes to other servers.
-Before you can push your changes to a GitLab server
-you need a secure communication channel for sharing information.
+Git is a distributed version control system, which means you can work locally.
+In addition, you can also share or "push" your changes to other servers.
+GitLab supports secure communication between Git and its servers using SSH keys.
 
 The SSH protocol provides this security and allows you to authenticate to the
 GitLab remote server without supplying your username or password each time.
 
-For a more detailed explanation of how the SSH protocol works, read
-[this nice tutorial by DigitalOcean](https://www.digitalocean.com/community/tutorials/understanding-the-ssh-encryption-and-connection-process).
+This page can help you configure secure SSH keys which you can use to help secure
+connections to GitLab repositories.
+
+- If you need information on creating SSH keys, start with our [options for SSH keys](#options-for-ssh-keys).
+- If you have SSH keys dedicated for your GitLab account, you may be interested in [Working with non-default SSH key pair paths](#working-with-non-default-ssh-key-pair-paths).
+- If you already have an SSH key pair, you can go to how you can [add an SSH key to your GitLab account](#adding-an-ssh-key-to-your-gitlab-account).
 
 ## Requirements
 
-The only requirement is to have the OpenSSH client installed on your system. This
+To support SSH, GitLab requires the installation of the OpenSSH client, which
 comes pre-installed on GNU/Linux and macOS, but not on Windows.
 
-Depending on your Windows version, there are different methods to work with
-SSH keys.
+Make sure that your system includes SSH version 6.5 or newer, as that excludes
+the now insecure MD5 signature scheme. The following command returns the version of
+SSH installed on your system:
 
-### Windows 10: Windows Subsystem for Linux
+```shell
+ssh -V
+```
 
-Starting with Windows 10, you can
-[install the Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
-where you can run Linux distributions directly on Windows, without the overhead
-of a virtual machine. Once installed and set up, you'll have the Git and SSH
-clients at your disposal.
+While GitLab does [not support installation on Microsoft Windows](../install/requirements.md#microsoft-windows),
+you can set up SSH keys to set up Windows [as a client](#options-for-microsoft-windows).
 
-### Windows 10, 8.1, and 7: Git for Windows
+## Options for SSH keys
 
-The easiest way to install Git and the SSH client on Windows 8.1 and Windows 7
-is [Git for Windows](https://gitforwindows.org). It provides a Bash
-emulation (Git Bash) used for running Git from the command line and the
-`ssh-keygen` command that is useful to create SSH keys as you'll learn below.
+GitLab supports the use of RSA, DSA, ECDSA, and ED25519 keys.
 
-NOTE: **Alternative tools:**
-Although not explored in this page, you can use some alternative tools.
-[Cygwin](https://www.cygwin.com) is a large collection of GNU and open source
-tools which provide functionality similar to a Unix distribution.
-[PuttyGen](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html)
-provides a graphical user interface to [create SSH keys](https://tartarus.org/~simon/putty-snapshots/htmldoc/Chapter8.html#pubkey-puttygen).
+- GitLab has [deprecated](https://about.gitlab.com/releases/2018/06/22/gitlab-11-0-released/#support-for-dsa-ssh-keys) DSA keys in GitLab 11.0.
+- 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.
 
-## Types of SSH keys and which to choose
+TIP: **Tip:**
+Available documentation suggests that ED25519 is more secure. If you use an RSA key, the US National Institute of Science and Technology in [Publication 800-57 Part 3 (PDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf) recommends a key size of at least 2048 bits.
 
-GitLab supports RSA, DSA, ECDSA, and ED25519 keys. Their difference lies on
-the signing algorithm, and some of them have advantages over the others. For
-more information, you can read this
-[nice article on ArchWiki](https://wiki.archlinux.org/index.php/SSH_keys#Choosing_the_authentication_key_type).
-We'll focus on ED25519 and RSA here.
+Therefore, our documentation focuses on the use of ED25519 and RSA keys.
 
-NOTE: **Note:**
-As an admin, you can [restrict which keys should be permitted and their minimum length](../security/ssh_keys_restrictions.md).
-By default, all keys are permitted, which is also the case for
-[GitLab.com](../user/gitlab_com/index.md#ssh-host-keys-fingerprints).
+Administrators can [restrict which keys should be permitted and their minimum lengths](../security/ssh_keys_restrictions.md).
+
+## Review existing SSH keys
+
+If you have existing SSH keys, you may be able to use them to help secure connections with GitLab
+repositories. By default, SSH keys on Linux and macOS systems are stored in the user's home directory,
+in the `.ssh/` subdirectory. The following table includes default filenames for each SSH key algorithm:
+
+| Algorithm | Public key | Private key |
+| --------- | ---------- | ----------- |
+|  ED25519 (preferred)  | `id_ed25519.pub` | `id_ed25519` |
+|  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` |
+
+For recommendations, see [options for SSH keys](#options-for-ssh-keys).
+
+## Generating a new SSH key pair
+
+If you want to create:
+
+- An ED25519 key, read [ED25519 SSH keys](#ed25519-ssh-keys).
+- An RSA key, read [RSA SSH keys](#rsa-ssh-keys).
 
 ### ED25519 SSH keys
 
-Following [best practices](https://linux-audit.com/using-ed25519-openssh-keys-instead-of-dsa-rsa-ecdsa/),
-you should always favor [ED25519](https://ed25519.cr.yp.to/) SSH keys, since they
-are more secure and have better performance over the other types.
+The book [Practical Cryptography With Go](https://leanpub.com/gocrypto/read#leanpub-auto-chapter-5-digital-signatures)
+suggests that [ED25519](https://ed25519.cr.yp.to/) keys are more secure and performant than RSA keys.
 
-ED25519 SSH keys were introduced in OpenSSH 6.5,
-so any modern OS should include the option to create them.
-If for any reason your OS or the GitLab instance you interact with doesn't
-support ED25519, you can fallback to RSA.
+As OpenSSH 6.5 introduced ED25519 SSH keys in 2014, they should be available on any current
+operating system.
 
-NOTE: **Note:**
-Omnibus does not ship with OpenSSH, so it uses the version on your GitLab server. If using
-Omnibus, ensure the version of OpenSSH installed is version 6.5 or newer if you want to use ED25519 SSH keys.
+You can create and configure an ED25519 key with the following command:
+
+```shell
+ssh-keygen -t ed25519 -C "<comment>"
+```
+
+The `-C` flag, with a quoted comment such as an email address, is an optional way to label your SSH keys.
+
+You'll see a response similar to:
+
+```plaintext
+Generating public/private ed25519 key pair.
+Enter file in which to save the key (/home/user/.ssh/id_ed25519):
+```
+
+For guidance, proceed to the [common steps](#common-steps-for-generating-an-ssh-key-pair).
 
 ### RSA SSH keys
 
-RSA keys are the most common ones and therefore the most compatible with
-servers that may have an old OpenSSH version. Use them if the GitLab server
-doesn't work with ED25519 keys.
+If you use RSA keys for SSH, the US National Institute of Standards and Technology recommends
+that you use a key size of [at least 2048 bits](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf).
+By default, the `ssh-keygen` command creates an 1024-bit RSA key.
 
-The minimum key size is 1024 bits, defaulting to 2048. If you wish to generate a
-stronger RSA key pair, specify the `-b` flag with a higher bit value than the
-default.
+You can create and configure an RSA key with the following command, substituting if desired for the minimum recommended key size of `2048`:
 
-## Generating a new SSH key pair
+```shell
+ssh-keygen -t rsa -b 2048 -C "email@example.com"
 
-Before creating an SSH key pair, make sure to understand the
-[different types of keys](#types-of-ssh-keys-and-which-to-choose).
+The `-C` flag, with a quoted comment such as an email address, is an optional way to label your SSH keys.
 
-To create a new SSH key pair:
+You'll see a response similar to:
 
-1. Open a terminal on Linux or macOS, or Git Bash / WSL on Windows.
-1. Generate a new ED25519 SSH key pair:
+```plaintext
+Generating public/private rsa key pair.
+Enter file in which to save the key (/home/user/.ssh/id_rsa):
+```
 
-   ```shell
-   ssh-keygen -t ed25519 -C "email@example.com"
-   ```
+For guidance, proceed to the [common steps](#common-steps-for-generating-an-ssh-key-pair).
 
-   Or, if you want to use RSA:
+NOTE: **Note:**
+If your have OpenSSH version 7.8 or below, consider the problems associated
+with [encoding](#rsa-keys-and-openssh-from-versions-65-to-78).
 
-   ```shell
-   ssh-keygen -t rsa -b 4096 -C "email@example.com"
-   ```
+### Common steps for generating an SSH key pair
 
-   The `-C` flag adds a comment in the key in case you have multiple of them
-   and want to tell which is which. It is optional.
+Whether you're creating a [ED25519](#ed25519-ssh-keys) or an [RSA](#rsa-ssh-keys) key, you've started with the `ssh-keygen` command.
+At this point, you'll see the following message in the command line (for ED25519 keys):
 
-1. Next, you will be prompted to input a file path to save your SSH key pair to.
-   If you don't already have an SSH key pair and aren't generating a [deploy key](#deploy-keys),
-   use the suggested path by pressing
-   <kbd>Enter</kbd>. Using the suggested path will normally allow your SSH client
-   to automatically use the SSH key pair with no additional configuration.
+```plaintext
+Generating public/private ed25519 key pair.
+Enter file in which to save the key (/home/user/.ssh/id_rsa):
+```
 
-   If you already have an SSH key pair with the suggested file path, you will need
-   to input a new file path and [declare what host](#working-with-non-default-ssh-key-pair-paths)
-   this SSH key pair will be used for in your `~/.ssh/config` file.
+If you don't already have an SSH key pair and are not generating a [deploy key](#deploy-keys),
+accept the suggested file and directory. Your SSH client will use
+the resulting SSH key pair with no additional configuration.
 
-1. Once the path is decided, you will be prompted to input a password to
-   secure your new SSH key pair. It's a best practice to use a password,
-   but it's not required and you can skip creating it by pressing
-   <kbd>Enter</kbd> twice.
+Alternatively, you can save the new SSH key pair in a different location.
+You can assign the directory and file name of your choice.
+You can also dedicate that SSH key pair to a [specific host](#working-with-non-default-ssh-key-pair-paths).
 
-   If, in any case, you want to add or change the password of your SSH key pair,
-   you can use the `-p` flag:
+After assigning a file to save your SSH key, you'll get a chance to set up
+a [passphrase](https://www.ssh.com/ssh/passphrase) for your SSH key:
 
-   ```shell
-   ssh-keygen -p -f <keyname>
-   ```
+```plaintext
+Enter passphrase (empty for no passphrase):
+Enter same passphrase again:
+```
+
+If successful, you'll see confirmation of where the `ssh-keygen` command
+saved your identification and private key.
+
+When needed, you can update the passphrase with the following command:
+
+```shell
+ssh-keygen -p -f /path/to/ssh_key
+```
 
-### OpenSSH < v7.8
+### RSA keys and OpenSSH from versions 6.5 to 7.8
 
-Pre OpenSSH 7.8, default password encoding for SSH private keys was
-[insecure](https://latacora.micro.blog/the-default-openssh/);
-it's only a single round of an MD5 hash. For OpenSSH version 6.5 to version 7.8, you should
-use the `-o` option to `ssh-keygen` to [encode your private key in a new, more
-secure format.](https://superuser.com/questions/1455735/what-does-ssh-keygen-o-do#answer-1455738)
+Before OpenSSH 7.8, the default public key fingerprint for RSA keys was based on MD5,
+and is therefore insecure.
+
+If your version of OpenSSH lies between version 6.5 to version 7.8 (inclusive),
+run `ssh-keygen` with the `-o` option to save your private SSH keys in the more secure
+OpenSSH format.
 
 If you already have an RSA SSH key pair to use with GitLab, consider upgrading it
-to use the more secure password encryption format by using the following command
-on the private key:
+to use the more secure password encryption format. You can do so with the following command:
 
 ```shell
 ssh-keygen -o -f ~/.ssh/id_rsa
 ```
 
-Or generate a new RSA key:
+Alternatively, you can generate a new RSA key with the more secure encryption format with
+the following command:
 
 ```shell
 ssh-keygen -o -t rsa -b 4096 -C "email@example.com"
 ```
 
-Now, it's time to add the newly created public key to your GitLab account.
+NOTE: **Note:**
+As noted in the `ssh-keygen` man page, ED25519 already encrypts keys to the more secure
+OpenSSH format.
 
 ## Adding an SSH key to your GitLab account
 
-1. Copy your **public** SSH key to the clipboard by using one of the commands below
-   depending on your Operating System:
+Now you can copy the SSH key you created to your GitLab account. To do so, follow these steps:
+
+1. Copy your **public** SSH key to a location that saves information in text format.
+   The following options saves information for ED25519 keys to the clipboard
+   for the noted operating system:
 
    **macOS:**
 
@@ -163,7 +197,7 @@ Now, it's time to add the newly created public key to your GitLab account.
    pbcopy < ~/.ssh/id_ed25519.pub
    ```
 
-   **WSL / GNU/Linux (requires the xclip package):**
+   **Linux (requires the xclip package):**
 
    ```shell
    xclip -sel clip < ~/.ssh/id_ed25519.pub
@@ -175,25 +209,24 @@ Now, it's time to add the newly created public key to your GitLab account.
    cat ~/.ssh/id_ed25519.pub | clip
    ```
 
-   You can also open the key in a graphical editor and copy it from there,
-   but be careful not to accidentally change anything.
-
-   NOTE: **Note:**
-   If you opted to create an RSA key, the name might differ.
+   If you're using an RSA key, substitute accordingly.
 
-1. Add your **public** SSH key to your GitLab account by:
-   1. Clicking your avatar in the upper right corner and selecting **Settings**.
-   1. Navigating to **SSH Keys** and pasting your **public** key from the clipboard into the **Key** field. If you:
-      - Created the key with a comment, this will appear in the **Title** field.
-      - Created the key without a comment, give your key an identifiable title like _Work Laptop_ or _Home Workstation_.
-   1. Choose an (optional) expiry date for the key under "Expires at" section. (Introduced in [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/36243))
-   1. Click the **Add key** button.
+1. Navigate to `http://gitlab.com` and sign in.
+1. Select your avatar in the upper right corner, and click **Settings**
+1. Click **SSH Keys**.
+1. Paste the public key that you copied into the **Key** text box.
+1. Make sure your key includes a descriptive name in the **Title** text box, such as _Work Laptop_ or
+   _Home Workstation_.
+1. Include an (optional) expiry date for the key under "Expires at" section. (Introduced in [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/36243).)
+1. Click the **Add key** button.
 
-SSH keys that have "expired" using this procedure will still be valid in GitLab workflows. As the GitLab-configured expiration date is not included in the SSH key itself, you can still export public SSH keys as needed.
+SSH keys that have "expired" using this procedure will still be valid in GitLab workflows.
+As the GitLab-configured expiration date is not included in the SSH key itself,
+you can still export public SSH keys as needed.
 
-   NOTE: **Note:**
-   If you manually copied your public SSH key make sure you copied the entire
-   key starting with `ssh-ed25519` (or `ssh-rsa`) and ending with your email.
+NOTE: **Note:**
+If you manually copied your public SSH key make sure you copied the entire
+key starting with `ssh-ed25519` (or `ssh-rsa`) and ending with your email address.
 
 ## Testing that everything is set up correctly
 
@@ -205,7 +238,7 @@ ssh -T git@gitlab.com
 ```
 
 The first time you connect to GitLab via SSH, you will be asked to verify the
-authenticity of the GitLab host you are connecting to.
+authenticity of the GitLab host that you're connecting to.
 For example, when connecting to GitLab.com, answer `yes` to add GitLab.com to
 the list of trusted hosts:
 
@@ -219,35 +252,34 @@ Warning: Permanently added 'gitlab.com' (ECDSA) to the list of known hosts.
 NOTE: **Note:**
 For GitLab.com, consult the
 [SSH host keys fingerprints](../user/gitlab_com/index.md#ssh-host-keys-fingerprints),
-to make sure you're connecting to the correct server.
+section to make sure you're connecting to the correct server. For example, you'll see
+the ECDSA key fingerprint shown above in the linked section.
 
 Once added to the list of known hosts, you won't be asked to validate the
 authenticity of GitLab's host again. Run the above command once more, and
 you should only receive a _Welcome to GitLab, `@username`!_ message.
 
-If the welcome message doesn't appear, run SSH's verbose mode by replacing `-T`
-with `-vvvT` to understand where the error is.
+If the welcome message doesn't appear, you can troubleshoot the problem by running `ssh`
+in verbose mode with the following command:
+
+```shell
+ssh -Tvvv git@gitlab.com
+```
 
 ## Working with non-default SSH key pair paths
 
 If you used a non-default file path for your GitLab SSH key pair,
-you must configure your SSH client to find your GitLab private SSH key
-for connections to GitLab.
+configure your SSH client to point to your GitLab private SSH key.
 
-Open a terminal and use the following commands
-(replacing `other_id_rsa` with your private SSH key):
+To make these changes, run the following commands:
 
 ```shell
 eval $(ssh-agent -s)
-ssh-add ~/.ssh/other_id_rsa
+ssh-add <path to private SSH key>
 ```
 
-To retain these settings, you'll need to save them to a configuration file.
-For OpenSSH clients this is configured in the `~/.ssh/config` file. In this
-file you can set up configurations for multiple hosts, like GitLab.com, your
-own GitLab instance, GitHub, Bitbucket, etc.
-
-Below are two example host configurations using their own SSH key:
+Now save these settings to the `~/.ssh/config` file. Two examples
+for SSH keys dedicated to GitLab are shown here:
 
 ```conf
 # GitLab.com
@@ -441,7 +473,6 @@ to this section if your server is configured like this, e.g.:
 ```shell
 $ gitlab-rake gitlab:check
 
-# ...
 Git user has default SSH configuration? ... no
   Try fixing it:
   mkdir ~/gitlab-check-backup-1504540051
@@ -455,6 +486,19 @@ Git user has default SSH configuration? ... no
 Remove the custom configuration as soon as you're able to. These customizations
 are *explicitly not supported* and may stop working at any time.
 
+### Options for Microsoft Windows
+
+If you're running Windows 10, the [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10), and its latest [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install) version,
+support the installation of different Linux distributions, which include the Git and SSH clients.
+
+For current versions of Windows, you can also install the Git and SSH clients with
+[Git for Windows](https://gitforwindows.org).
+
+Alternative tools include:
+
+- [Cygwin](https://www.cygwin.com)
+- [PuttyGen](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html)
+
 ## Troubleshooting
 
 If on Git clone you are prompted for a password like `git@gitlab.com's password:`

doc/user/gitlab_com/index.md

@@ -5,11 +5,12 @@ In this page you will find information about the settings that are used on
 
 ## SSH host keys fingerprints
 
-Below are the fingerprints for GitLab.com's SSH host keys.
+Below are the fingerprints for GitLab.com's SSH host keys. The first time you connect
+to a GitLab.com repository, you'll see one of these keys in the output.
 
-| Algorithm | MD5 | SHA256  |
+| Algorithm | MD5 (deprecated) | SHA256  |
 | --------- | --- | ------- |
-|  DSA      | `7a:47:81:3a:ee:89:89:64:33:ca:44:52:3d:30:d4:87` | `p8vZBUOR0XQz6sYiaWSMLmh0t9i8srqYKool/Xfdfqw` |
+|  DSA (deprecated)      | `7a:47:81:3a:ee:89:89:64:33:ca:44:52:3d:30:d4:87` | `p8vZBUOR0XQz6sYiaWSMLmh0t9i8srqYKool/Xfdfqw` |
 |  ECDSA    | `f1:d0:fb:46:73:7a:70:92:5a:ab:5d:ef:43:e2:1c:35` | `HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw` |
 |  ED25519  | `2e:65:6a:c8:cf:bf:b2:8b:9a:bd:6d:9f:11:5c:12:16` | `eUXGGm1YGsMAS7vkcx6JOJdOGHPem5gQp4taiCfCLB8` |
 |  RSA      | `b6:03:0e:39:97:9e:d0:e7:24:ce:a3:77:3e:01:42:09` | `ROQFvPThGrW4RuWLoL9tq9I9zJ42fK4XywyRtbOz/EQ` |