SSH stands for Secure Shell. SSH offers a secure way to remotely log in to another computer and issue commands, e.g. your website’s server.

SSL stands for Secure Sockets Layer. While most people still refer to SSL, SSL is technically the older version of the more modern Transport Layer Security (TLS) protocol. SSL is a protocol that’s primarily designed to protect the transmission of data between two parties with encryption and authentication.

You can use the ssh command line tool to debug your git connection:

  ssh -T git@gitlab.com 

For more debug output, you can add up to three levels of verbosity (-v or -vv or -vvv):

  ssh -v -T git@gitlab.com 

To establish a secure connection between your computer and the repository server via Secure Shell (SSH) you will need to create and install SSH keys. The private key resides on your computer and must never be shared, the public key is stored at the remote server.

Since Windows ships an SSH client by default since a few years, the steps and commands for all platforms (Mac, Linux, Windows) are the same. Only the paths in the following example differ. It is no longer recommended to use Putty on Windows.

1. Open a Terminal (on Windows press Win + R and type cmd).
2. To generate a new SSH key pair, use the following command.

     ssh-keygen -t ed25519 -C "your_email@example.com"
    

   • -t ed25519: Specifies the type of key to create, in this case, ed25519.
   • -C “your_email@example.com”: Adds a comment to the key, typically your email address. This is optional!
3. The system will prompt you to specify the file to save the key. Press Enter to accept the default location, which is usually C:\Users\YourUsername\.ssh\id_ed25519.
4. Enter a Passphrase. This adds an extra layer of security to the private key and is obligatory at HSE.
5. If you accepted the default location, you can find your private key at C:\Users\YourUsername\.ssh\id_ed25519 and the public key at C:\Users\YourUsername\.ssh\id_ed25519.pub.
6. To display and copy the public key from the Terminal, use the following command:

     cat C:\Users\YourUsername\.ssh\id_ed25519.pub
    

Add your key by navigating to the 'SSH Keys' section in your user profile, selecting 'Add SSH Key', and copy-pasting the public key to the 'key' field. Please copy the complete key (a long string starting with ssh- and ending with the comment you specified, usually your email address). The expiration period of 12 Month should be kept.

For server certificate errors, see 04 Debugging.

You can configure various options for the ssh client permanently in ~/.ssh/config (for the current user):

  Host 192.168.*.*
     StrictHostKeyChecking no
     UserKnownHostsFile=/dev/null

The SSH client matches the most specific configuration block, so you need to define the more specific configurations first. The bit about two different accounts on the same host is untested!

  # Work account
  Host code.hampel-soft.com
  HostName code.hampel-soft.com
  IdentityFile ~/.ssh/id_rsa_work
  User git
  IdentitiesOnly yes
  
  # Personal account
  Host gitlab.com
  HostName gitlab.com
  IdentityFile ~/.ssh/id_rsa_personal
  User git
  IdentitiesOnly yes
  
  # Customer 1 account on bitbucket.org
  Host bitbucket.org-customer1
  HostName bitbucket.org
  IdentityFile ~/.ssh/customer1_id_rsa
  User git
  IdentitiesOnly yes
  
  # Customer 2 account on bitbucket.org
  Host bitbucket.org-customer2
  HostName bitbucket.org
  IdentityFile ~/.ssh/customer2_id_rsa
  User git
  IdentitiesOnly yes
  
  # Use id_rsa_rest for all other hosts
  Host *
  IdentityFile ~/.ssh/id_rsa_rest
  User git
  IdentitiesOnly yes

• Host: This specifies the alias or nickname for the host you're connecting to. It's just for your reference and convenience.
• HostName: This is the actual hostname or IP address of the SSH server.
• IdentityFile: This specifies the path to the private key file to be used for authentication when connecting to the specified host.
• User: This specifies the username you will use when connecting to the SSH server.
• IdentitiesOnly yes: This tells SSH to only use the specified identity (private key) files and not attempt any others.

For added security, you might choose a passphrase for your SSH key. In this case, you usually have to enter the passphrase manually each time. This of course hinders automatisation.

The solution is to use ssh-agent. Which securely stores your passphrase, so you don`t need to enter it again.

See https://docs.github.com/de/authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases.

If this doesn't work, you can try the following alternatives.

To keep things as native as possible, we opted to use the built-in OpenSSH capabilities. This applies to: Windows Server 2022, Windows Server 2019, Windows 10 (build 1809 and later). Alternatively, you may use the SSH capabilities of Git for Windows.

1. Try using ssh-agent as described in the next session, if needed, install it via:
2. Open Settings, select Apps > Apps & Features, then select Optional Features.
3. Scan the list to see if the OpenSSH is already installed. If not, at the top of the page, select Add a feature, then:

   1. Find OpenSSH Client, then click Install
   2. Find OpenSSH Server, then click Install

Now that you have installed OpenSSH, you must set up the ssh-agent service.

Open a Powershell instance with Administrator rights and run the following script:

# By default the ssh-agent service is disabled. Allow it to be 
# manually started for the next step to work. (*)
# Make sure you're running as an Administrator.
Get-Service ssh-agent | Set-Service -StartupType Manual
 
# Start the service
Start-Service ssh-agent
 
# This should return a status of Running
Get-Service ssh-agent
 
# Now load your key files into ssh-agent
ssh-add \path\to\user\privatekey
 
# Now enable automatic starting (*)
Set-Service -StartupType Automatic 

(*) Setting the start type to manual means that as soon as you run ssh-agent, it'll start the service. Setting it to automatic will start the ssh-agent when booting the system.

If you have Git for Windows previously installed, you have to explicitly change which OpenSSH instance to use. During the original installation, it was possible to choose between the GfW's SSH implementation or the native Windows implementation. If you chose the former, you need to change the default SSH implementation, with the following Powershell command:

git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exe

After the ssh-agent is configured, use it once manually to see if it works as expected (git clone some-private-repo). Some pop-up may arise only once. Then restart your computer and try it again.