short explanation why to use SSH
This commit is contained in:
René Wagner
parent
b82d39de3e
commit
e26265cf78
|
|
@ -8,7 +8,7 @@ eleventyNavigation:
|
|||
|
||||
Before you are able to use SSH for git you need to [add an SSH key to your account](/security/ssh-key).
|
||||
|
||||
> **Warning**
|
||||
> **Warning**
|
||||
> Please make sure that before connecting to Codeberg via SSH,
|
||||
> you have [verified Codeberg's SSH fingerprint](/security/ssh-fingerprint)!
|
||||
|
||||
|
|
|
|||
|
|
@ -9,4 +9,12 @@ eleventyNavigation:
|
|||
On these pages, you will learn how to use the Git version control system
|
||||
with Codeberg.
|
||||
|
||||
Please note that this is a Work in Progress.
|
||||
There are 3 ways to interact with a git repository hosted on Codeberg:
|
||||
1. [via the SSH protocol](/git/clone-commit-via-ssh)
|
||||
2. [via the HTTPS protocol](/git/clone-commit-via-http)
|
||||
3. [Using the website](/git/clone-commit-via-web/)
|
||||
|
||||
Option 1 and 2 require a git client (CLI or GUI, your choice) installed on your local system.
|
||||
|
||||
On clients regularly used to access codeberg we recommend the use of the [SSH protocol](https://de.wikipedia.org/wiki/Secure_Shell).
|
||||
It offers improved security through key-based access (stronger protection than a regular password) and better usability (no need to provide credentials on every git action).
|
||||
|
|
|
|||
|
|
@ -6,4 +6,6 @@ Welcome to the Codeberg Documentation pages!
|
|||
<span class="wide-only">Please choose a section from the main menu on the left.</span>
|
||||
<span class="narrow-only">Please choose a section from the main menu, which you can access by clicking/touching the three stripes at the top right.</span>
|
||||
|
||||
If you're new to Codeberg, consider reading the [Getting Started Guide](/getting-started).
|
||||
If you're new to Codeberg, consider reading the [Getting Started Guide](/getting-started).
|
||||
|
||||
> Please note that this is a **Work in Progress**.
|
||||
|
|
|
|||
|
|
@ -1,90 +1,92 @@
|
|||
---
|
||||
eleventyNavigation:
|
||||
key: SSHKey
|
||||
title: Adding an SSH key to your account
|
||||
parent: Security
|
||||
---
|
||||
|
||||
It is recommended to use one key per client. It means if you access your Codeberg repository from your home PC, your laptop and your office PC you should generate separate keys for each machine.
|
||||
|
||||
## Generating an SSH key (pair)
|
||||
|
||||
1. Open a shell (e.g. `git-bash` on Windows or `bash` on Linux).
|
||||
|
||||
2. Paste the text below, substituting in your Codeberg email address.
|
||||
|
||||
```shell
|
||||
$ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
|
||||
```
|
||||
|
||||
This creates a new ssh key, using the provided email as a label:
|
||||
|
||||
```shell
|
||||
> Generating public/private rsa key pair.
|
||||
```
|
||||
|
||||
3. When you're prompted to "Enter a file in which to save the key," press <kbd>Enter</kbd>. This accepts the default file location:
|
||||
|
||||
```shell
|
||||
> Enter a file in which to save the key (/c/Users/you/.ssh/id_rsa):[Press enter]
|
||||
```
|
||||
|
||||
4. Enter a passphrase if you want.
|
||||
|
||||
The private key part of your SSH key can be protected by a passphrase. This adds an additional layer of authentication which increases security. Be aware that this will only be helpful for certain attack scenarios and does not offer 100% protection. It is recommended to keep your private key safe and - well - private.
|
||||
|
||||
## Add the SSH key to Codeberg
|
||||
1. Copy the SSH key to your clipboard. Attention: Copy only the public part of the key not the private one. You can identify it by the `.pub` extension. By default, you can find the public key in `$HOME/.ssh/id_rsa.pub`.
|
||||
|
||||
On Linux you can use the `xclip` command like this
|
||||
```shell
|
||||
$ xclip -sel clip < ~/.ssh/id_rsa.pub
|
||||
```
|
||||
|
||||
On Windows use a text editor (e.g. Notepad) or `clip` on the command line
|
||||
```shell
|
||||
$ type .ssh/id_rsa.pub | clip
|
||||
```
|
||||
2. Navigate to your user settings
|
||||
<picture>
|
||||
<source srcset="/assets/images/security/user-settings.webp" type="image/webp">
|
||||
<img src="/assets/images/security/user-settings.png" alt="User Settings">
|
||||
</picture>
|
||||
|
||||
3. Go to the settings section __SSH / GPG Keys__ and click on __Add key__.
|
||||
|
||||
<picture>
|
||||
<source srcset="/assets/images/security/ssh-key/add-ssh-key.webp" type="image/webp">
|
||||
<img src="/assets/images/security/ssh-key/add-ssh-key.png" alt="SSH Key Settings">
|
||||
</picture>
|
||||
|
||||
4. Give an appropriate name for the key.
|
||||
5. Paste your key string from the clipboard into __content__ field.
|
||||
|
||||
## Test the SSH connection
|
||||
Do this simple test:
|
||||
|
||||
```shell
|
||||
$ ssh -T git@codeberg.org
|
||||
```
|
||||
|
||||
The output should look like this:
|
||||
|
||||
```shell
|
||||
Hi there, You've successfully authenticated, but Gitea does not provide shell access.
|
||||
If this is unexpected, please log in with password and setup Gitea under another user.
|
||||
```
|
||||
|
||||
*Note: All codeberg users share a single unix user named `git` which is used to check out repositories. Depending on the key provided, permission is granted or denied. You can check out all repositories with your key which you have permission for. You can push code to all repositories where you have write access.*
|
||||
|
||||
## Avoid re-typing the passphrase
|
||||
|
||||
Assuming you've created a secure key with passphrase, SSH will prompt you for your passphrase for every connection. Common desktop environments like OSX or Gnome will offer you to cache your passphrase via an SSH agent.
|
||||
|
||||
If you are working at the command line, you can alternatively do this directly:
|
||||
|
||||
```shell
|
||||
$ eval `ssh-agent`
|
||||
$ ssh-add
|
||||
## enter your passphrase once, this is then cached.
|
||||
```
|
||||
---
|
||||
eleventyNavigation:
|
||||
key: SSHKey
|
||||
title: Adding an SSH key to your account
|
||||
parent: Security
|
||||
---
|
||||
|
||||
It is recommended to use one key per client. It means if you access your Codeberg repository from your home PC, your laptop and your office PC you should generate separate keys for each machine.
|
||||
|
||||
## Generating an SSH key (pair)
|
||||
|
||||
1. Open a shell (e.g. `git-bash` on Windows or `bash` on Linux).
|
||||
|
||||
2. Paste the text below, substituting in your Codeberg email address.
|
||||
|
||||
```shell
|
||||
$ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
|
||||
```
|
||||
|
||||
This creates a new ssh key, using the provided email as a label:
|
||||
|
||||
```shell
|
||||
> Generating public/private rsa key pair.
|
||||
```
|
||||
|
||||
3. When you're prompted to "Enter a file in which to save the key," press <kbd>Enter</kbd>. This accepts the default file location:
|
||||
|
||||
```shell
|
||||
> Enter a file in which to save the key (/c/Users/you/.ssh/id_rsa):[Press enter]
|
||||
```
|
||||
|
||||
4. Enter a passphrase if you want.
|
||||
|
||||
The private key part of your SSH key can be protected by a passphrase. This adds an additional layer of authentication which increases security. Be aware that this will only be helpful for certain attack scenarios and does not offer 100% protection. It is recommended to keep your private key safe and - well - private.
|
||||
|
||||
If you are using a passphrase-protected SSH key the use of a ssh agent is strongly encouraged for improved usability. You need to enter the passphrase only once during a session.
|
||||
|
||||
## Add the SSH key to Codeberg
|
||||
1. Copy the SSH key to your clipboard. Attention: Copy only the public part of the key not the private one. You can identify it by the `.pub` extension. By default, you can find the public key in `$HOME/.ssh/id_rsa.pub`.
|
||||
|
||||
On Linux you can use the `xclip` command like this
|
||||
```shell
|
||||
$ xclip -sel clip < ~/.ssh/id_rsa.pub
|
||||
```
|
||||
|
||||
On Windows use a text editor (e.g. Notepad) or `clip` on the command line
|
||||
```shell
|
||||
$ type .ssh/id_rsa.pub | clip
|
||||
```
|
||||
2. Navigate to your user settings
|
||||
<picture>
|
||||
<source srcset="/assets/images/security/user-settings.webp" type="image/webp">
|
||||
<img src="/assets/images/security/user-settings.png" alt="User Settings">
|
||||
</picture>
|
||||
|
||||
3. Go to the settings section __SSH / GPG Keys__ and click on __Add key__.
|
||||
|
||||
<picture>
|
||||
<source srcset="/assets/images/security/ssh-key/add-ssh-key.webp" type="image/webp">
|
||||
<img src="/assets/images/security/ssh-key/add-ssh-key.png" alt="SSH Key Settings">
|
||||
</picture>
|
||||
|
||||
4. Give an appropriate name for the key.
|
||||
5. Paste your key string from the clipboard into __content__ field.
|
||||
|
||||
## Test the SSH connection
|
||||
Do this simple test:
|
||||
|
||||
```shell
|
||||
$ ssh -T git@codeberg.org
|
||||
```
|
||||
|
||||
The output should look like this:
|
||||
|
||||
```shell
|
||||
Hi there, You've successfully authenticated, but Gitea does not provide shell access.
|
||||
If this is unexpected, please log in with password and setup Gitea under another user.
|
||||
```
|
||||
|
||||
*Note: All codeberg users share a single unix user named `git` which is used to check out repositories. Depending on the key provided, permission is granted or denied. You can check out all repositories with your key which you have permission for. You can push code to all repositories where you have write access.*
|
||||
|
||||
## Avoid re-typing the passphrase
|
||||
|
||||
Assuming you've created a secure key with passphrase, SSH will prompt you for your passphrase for every connection. Common desktop environments like OSX or Gnome will offer you to cache your passphrase via an SSH agent.
|
||||
|
||||
If you are working at the command line, you can alternatively do this directly:
|
||||
|
||||
```shell
|
||||
$ eval `ssh-agent`
|
||||
$ ssh-add
|
||||
## enter your passphrase once, this is then cached.
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue