Software Developer Blog |

Store Git SSH key pair in Linux with Libsecret to skip asking for credentials

2019-11-04T10:00:00+00:00

If you have to connect to Git via SSH, your usual credential manager may be not enough. Read how to avoid entering password every time on your Linux device.

I have already introduced Libsecret Git credential manager, which works fine if you connect to remote repo via http(s), which is what we usually do. But sometimes we are forced to use SSH protocol, and once again we need to write password every time we interact with remote repo. Luckily it can be solved in secure way quite easily, but unfortunately descriptions which I found on the internet are not clear, moreover usually skip securing private keys. My goal is to explain it in this article in simple words, so you can apply it and understand what you do.

How automate SSH connection works

Mechanism which is used in SSH to automate connections is really simple. You generate public-private keys pair (those keys are not related to credentials nor any other data), hide private key with you and share public key with server. Then when you try to connect to server, your clients uses private key as prove that you’re allowed to connect - that’s it.

It sounds quite magically, but it’s really simple. Those keys are just text files, stored somewhere on your device, usually in ~/.ssh directory. They are not related to any data, it’s just a pair which suits each other, in mathematical meaning, you generate it with OpenSSH tool. Look at this example (with default file names id_rsa and id_rsa.pub):

Private key file: ~/.ssh/id_rsa

Public key file: ~/.ssh/id_rsa.pub

You store both files in your device and save public one in server which you want to connect, at proper path - that’s it. If you want to read more about key pair mechanism, article on ssh.com explains it nice.

How to configure automatic SSH connection

Once you know the theory, it’s time to try automated connection in practice. First I will show you the process with Seahorse tool which I find convenient for this task, but of course you can achieve the same with command line, which I will show later.

In Ubuntu and Linux Mint Seahorse comes pre installed with OS and you can find it as Seahorse or Passwords and Keys. I’m pretty sure it’s not difficult to install it in other distros, so if you don’t have it already, just search how to install it in your case. It uses libsecret abstraction which was created to unify access to sensitive data, so it should work on all popular Linux distributions.

If you don’t see secrets categories on the left side of Seahorse, set View » By Keyring.

Create SSH keys

Choose OpenSSH Keys category and press + button

Select Secure Shell Key

Now give your keys some description, to remember what is this for. This name will be seen on server, so you can write here your email address, to simplify server administration (so maintainer could know who uses this and if it’s still required).

Choose encryption type - at the time of writing the only available options in Seahorse are RSA and DSA - it’s a bit subjective, but I suggest choosing RSA as explained on security.stackexchange.com. There is a way to choose Ed25519 algorithm which is more secure and gives better performance, but currently only from command line.

RSA key strength can be left 2048 bits as is by default. You can increase it, but be aware that some devices may not support it and that it takes a bit more of resources to work with bigger number. But if you insist, 4096bits should be fine. Here is nice article which explains RSA key size topic with details.

From this point you can choose two options:

Just Create Key
Create and Set Up

With second option you will populate newly created key to server right from this wizard, so that’s what we will do. If you don’t have access to server at this moment, you can just create key and populate it later from command line.

Encrypt SSH keys with password

Next you will be asked to write passphrase for new secure shell key. It may be a bit confusing - you may wonder if this password must match SSH user password - it doesn’t need to, moreover - it shouldn’t - it is different password so it should be different (you won’t need to remember it). If you leave it blank your private key will be saved on disk unencrypted, which causes security risks. Despite some people advice to leave it this way I don’t see any reason not to encrypt it, that way or another you won’t need to remember it - we will use keyring for that (but it this moment save it somewhere, preferably in some password manager). Enter strong passphrase, I recommend using some tool which will generate it (I use KeepassXC), then enter it again as confirmation.

Check created keys files

Now you should have new files in ~/.ssh directory, as described earlier - id_rsa with private key and id_rsa.pub with public key. If you skipped encrypting private key you will see it in plain text, otherwise it will be encrypted and will contain header which indicates encryption, for example: Proc-Type: 4,ENCRYPTED.

Send public key to server

If you decided to create key and set it up, you will now see new Window - Set Up Computer for SSH Connection. Write your server address and a port in format server:port then your login name and press Set Up button. You will be asked for given user password.

Connect and store encryption password in keyring

If setting up succeeds, then in user directory on server will be copy of your public key in ~/.ssh directory in authorized_keys file - connect to server and check if it is there. It may look like this:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCxGhrhgMsQqOvXf+M1z04toa65/8vY6b+lzjAas7YJqut65o0ONWItpz2UHXSl0mFlbN49UR6VDR9jesUKW+vfuIRUaPs+8/bNEP5tIzPq3lSvw1msYNBT2kbQWO5+Qqiy7EXf/RJ7z4BGiBDEZ4rRhjxIrPAuaxeOpWU6KEDlsxCczxZWgl2xcldhk5oJwzItNd2piQlr7r2CYibHU36XtELvAhlTI1/p11rfSf/BwGtCxb25dApg8k/yRw2zpdV/JD0nfNQiESnCSmLxDr66WK5dScpXQ8zRMRSM3ekoo2ElkDEl9gQ9PhrqdKDLiPqgbobhi22ro4GKsHHAy2VF GitGitRsa

Do it as usual, just: ssh user@server.com -p 22 To see file you can for example write: cat ~/.ssh/authorized_keys

When you try to connect for the first time, you should be asked for password to Unlock private key. Set Automatically unlock this key whenever I’m logged in checkbox and since now it will be unlocked along with your login keyring, when you log in. You will no longer see this window and your private key will be encrypted - like I told, there is no reason not to encrypt it, it’s secure and convenient at the same time.

In my view if Seahorse works in your case, it’s convenient to use it’s wizard, but there is one exception: when you want to use Ed25519 algorithm which, like I told earlier in this article, is more secure and gives better performance, you must use command line, as at the time of writing it’s not supported in Seahorse wizard.

Bellow steps are exact equivalent of previous from Seahorse tool, just written from command line 😺

First generate a new Ed25519 SSH key pair (if you haven’t done it already):

ssh-keygen -t ed25519 -C "description or your email"

If server which you want to reach doesn’t support Ed25519 or if you have old version of OpenSSH on your PC (Ed25519 was introduced to OpenSSH in version 6.5), use RSA instead:

ssh-keygen -t rsa -b 2048 -C "description or your email"

Description or email is optional, but it’s good to put some convenient information here, because as I described earlier, this name will be seen on server, so it should identify you, so administrator will know who uses it.
If you wonder how many bits should have RSA key size (in above example 2048 bits), it’s the same case which I described during key creation with Seahorse tool. The bigger number you choose, the better security you have, but it comes with a bit bigger resources usage, and with risk, that it will not work - some devices don’t support length bigger than 2048. I recommend good article about RSA key size length, for those who want to understand choice better.

First you will be asked about path where to save keys - use default option by hitting Enter. If you’re warned that key already exist, you must choose custom path and later set up ~/.ssh/config file.

Next you will be asked for encryption password. This is not your SSH user password, so create strong password, different than user’s one, the best option is to generate it with some tool. You won’t need to remember it, but before you configure everything, save it somewhere - the best option is to use passwords manager - I recommend KeepassXC. I described why to do that in earlier part of this article.

Now you can check created keys files to ensure everything worked as expected.

If you had to enter custom path for keys, now you should configure it:

# Only if created keys at custom path 
eval $(ssh-agent -s)
ssh-add ~/.ssh/YOUR_NEW_PRIVATE_KEY

And save ~/.ssh/config file as in below example:

# Only if created keys at custom path 
Host gitlab.com
  Preferredauthentications publickey
  IdentityFile ~/.ssh/GITLAB_COM_KEY

Host github.com
  Preferredauthentications publickey
  IdentityFile ~/.ssh/GITHUB_COM_KEY

Next you need to copy your public key to server, this can be done with one command:

ssh-copy-id user@server

or if ssh-copy-id utility is not available on your device, you can use plain ssh solution
(change PUBLIC_KEY.pub to what you have generated, for example id_rsa.pub):

cat ~/.ssh/PUBLIC_KEY.pub | ssh <user>@<hostname> 'cat >> .ssh/authorized_keys && echo "Key copied"'

Next check if public key is copied as expected and store encryption password in keyring.

Troubleshooting SSH key pairing

If automate connection doesn’t work and you don’t know what has failed, and you have only one remote SSH server, you may want to try everything from scratch - maybe you made some mistake? That is what helped me, but use it only if you’re sure you don’t have any other keys already and just in case copy files as backup.

Remove all files from local ~/.ssh directory.
Remove all files from remote (server) ~/.ssh directory.
Try setting up everything again. I suggest reading short description how key pair automation works, to know what is happening during process.

If you see that keys are generated correctly, but copying to server failed, try to copy it manually (it may require sudo access):

Copy public key to server, for example with scp - scp ~/.ssh/PUBLIC_KEY.pub user@server:/home/user/PUBLIC_KEY.pub
Login to server as usual, for example: ssh user@server.com -p 22
Create .ssh directory, for example with command: mkdir ~/.ssh
Append the public key content to authorized_keys file: cat ~/PUBLIC_KEY.pub >> ~/.ssh/authorized_keys

If your key is copied to ~/.ssh/authorized_keys file on server but automate connection doesn’t work, try changing remote user permissions to 711 (some people advice to do it as well for user home directory) - you may need sudo access:

Login to server as usual, for example: ssh user@server.com -p 22
cd ~
chmod 711 .
chmod 711 .ssh/
chmod 711 .ssh/authorized_keys
chown -R USERANAME .ssh/

Summary

If you have any questions feel free to ask them in comments, or just to tell if this article has helped you. If you know someone who also uses SSH protocol to manage remote Git repo, don’t hesitate to send him or her link, it may help yet another person and I will be glad too :)

TFS Linux Agent with error: The user’s home directory could not be determined

2019-06-08T06:00:00+00:00

How to fix problem with dotnet restore on TFS 2017 Linux agent - The user’s home directory could not be determined.

I have recently configured Linux agent for Team Foundation Server 2017 to be able to run dotnet core project there. But during dotnet restore step error was thrown: Error: /usr/bin/dotnet failed with return code: 1 with more explanation: The user’s home directory could not be determined. Set the ‘DOTNET_CLI_HOME’ environment variable to specify the directory to use. It may occur also on newer versions of TFS and on its online version - Visual Studio Team Services (VSTS), currently called Azure DevOps.

After quick search I knew that dotnet needs to know where home is located for some operations.

Agent logs

Full agent logs for dotnet restore step:

[section]Starting: Restore
==============================================================================
Task         : .NET Core
Description  : Build, test and publish using dotnet core command-line.
Version      : 1.0.1
Author       : Microsoft Corporation
Help         : [More Information](https://go.microsoft.com/fwlink/?linkid=832194)
==============================================================================
[command] /usr/bin/dotnet restore /home/tfs-agent/PS-TFS-AGENT-LNX01_agent01/_work/2/s/ProjectName/ProjectName.csproj
The user's home directory could not be determined. Set the 'DOTNET_CLI_HOME' environment variable to specify the directory to use.
[error] Error: /usr/bin/dotnet failed with return code: 1
[error] Dotnet command failed with non-zero exit code on the following projects : /home/tfs-agent/PS-TFS-AGENT-LNX01_agent01/_work/2/s/ProjectName/ProjectName.csproj
[section] Finishing: Restore

What didn’t help

First I checked if $HOME variable can be seen on this Linux Machine, logged in as user which is given for TFS. It was ok. Then I set DOTNET_CLI_HOME as Linux environment variable, pointing to $HOME. It didn’t help. There were much more solutions to check, looking through the internet, but next one worked for me.

Solution

This solutions is not elegant, but it works and in my view is acceptable, and it has one big advantage - it doesn’t require access to Linux Machine ssh. I set DOTNET_CLI_HOME as build definition variable, pointing to /tmp directory. That’s it, now dotnet restore and build works :)

Summary

I don’t know if this solution will work for everyone, but it takes only 2 clicks to try, so definitely it’s good to start with :)

Libsecret - remember Git credentials in Linux Mint and Ubuntu securely

2019-03-06T06:00:00+00:00

Typing username and password every push is burdensome and irritating… libsecret git credential storage to the rescue.

When you want to use external git repository hosting service, like Gitlab or GitHub you need to authorise yourself. Git has built in credential helper mechanism, which allows choosing the way you have credentials persisted. It gives you two options out of the box, but you’re not limited to them - you can install third party solution.

Cache credential helper (out of the box)

Cache is quite secure because keeps data only in memory. It’s fine for security, but every time you open new session, you need to type credentials again. Memory is purged after 900 seconds (15 min) by default, but it can be changed with optional timeout parameter.

If for some reason you don’t want to install anything, at least use cache :)

git config --global credential.helper 'cache --timeout=300'

Official description - git-scm.com/docs/git-credential-cache

Store credential helper (out of the box)

Store keeps your username and password in… plain text file! It’s totally insecure and use it only if you don’t care about your account (for example during some kind of workshops).

git config --global credential.helper store

Official description - git-scm.com/docs/git-credential-store

Git Credential Manager for Mac and Linux (by Microsoft)

Windows users are familiar with convenient Git Credential Manager for Windows which is integrated with OS way of storing credentials. It can be installed with official wizard or during git installation on Windows (there is checkbox to select). And recently Microsoft announced release of… Git Credential Manager for Mac and Linux. I was positively surprised, till I tried to use it on my Linux Mint 19 Tara. Installation was successful (but not without complications) and attempt to use it ended up with error:

Fatal: java.lang.RuntimeException encountered. Details: 
Secure credential storage is not available on this operating system. You may opt-in to store credentials in an unencrypted file under your user home directory by running 'git config --global credential.canFallBackToInsecureStore true'.
fatal: credential helper '!/usr/lib/jvm/java-11-openjdk-amd64/bin/java -Ddebug=false -Djava.net.useSystemProxies=true -jar /home/linuxbrew/.linuxbrew/Cellar/git-credential-manager/2.0.4/libexec/git-credential-manager-2.0.4.jar' told us to quit

I have opened the issue and till now I haven’t received any response (more than 2 months) and recently I have seen the same issue created for Ubuntu 18.04. So currently it doesn’t work on Linux Mint and Ubuntu.

Official description - github.com/Microsoft/Git-Credential-Manager-for-Mac-and-Linux

Libsecret git credential storage (by GNOME)

The best way to store Git credentials on Linux used to be GNOME Keyring (libgnome-keyring), but as it is specific to GNOME, it is deprecated since January 2014. For Git versions 2.11+ you should use credential helper based on libsecret. Installation and configuration takes only 4 bash commands :)

sudo apt-get install libsecret-1-0 libsecret-1-dev
cd /usr/share/doc/git/contrib/credential/libsecret
sudo make
git config --global credential.helper /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret

That’s all, next time when you’ll be asked for your username and password will be the last time on this device :)

Official description - wiki.gnome.org/Projects/Libsecret

How to secure SSH credentials

Above credential managers work only if you use http(s), which is usual case. If you have to use SSH protocol, I have described how to skip asking for credentials with SSH key-pair in safe manner, in another article.

Summary

As you see it’s not difficult to protect your credentials and not have to type them all the time. If it doesn’t work for you or you have some question or unusual case, feel free to ask me in comments, I will do my best to help you.
If you know someone who uses unsafe credential manager or doesn’t use manager at all, send him this article, I will appreciate it :)

Software Developer Blog |

Store Git SSH key pair in Linux with Libsecret to skip asking for credentials

How automate SSH connection works

How to configure automatic SSH connection

Create SSH keys

Encrypt SSH keys with password

Check created keys files

Send public key to server

Connect and store encryption password in keyring

Automate SSH login using command line

Troubleshooting SSH key pairing

Summary

TFS Linux Agent with error: The user’s home directory could not be determined

Agent logs

What didn’t help

Solution

Summary

Libsecret - remember Git credentials in Linux Mint and Ubuntu securely

Cache credential helper (out of the box)

Store credential helper (out of the box)

Git Credential Manager for Mac and Linux (by Microsoft)

Libsecret git credential storage (by GNOME)

How to secure SSH credentials

Summary