Skip to content

G
gitlab-ce
Commit 8ceb4b83 authored by Mike Jang's avatar Mike Jang
Browse files
Options

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
parents c778a90a 0656ef91
Show whitespace changes
Inline Side-by-side
Showing with 177 additions and 132 deletions
doc/ssh/README.md
View file @ 8ceb4b83
......@@ -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
View file @ 8ceb4b83
......@@ -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` |
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7