1. Overview
In this tutorial, we’ll learn about the GNOME keyring software application in Linux. Specifically, we’ll learn how to set up our Git to use GNOME keyring as the credentials provider.
2. GNOME Keyring
The GNOME keyring is a password manager service in Linux. It comes with any Linux distribution with a GNOME desktop environment, such as Ubuntu, Debian, and SUSE Linux. For Linux distributions that don’t use GNOME, we can install it by installing the gnome-keyring package.
As a password manager, the GNOME keyring stores secrets and makes them available for application that requires it. These secrets range from plain text to usernames, passwords, and cryptographic keys. When we store secrets using the GNOME keyring, it encrypts these secrets and stores them in a keyring file in the home directory. By default, GNOME keyring uses the system user’s login password as the master password to encrypt all the secrets.
The GNOME keyring contains several components that work together to provide the functionality we use. In the subsequent section, we’ll look at some of the important components of the GNOME keyring application.
2.1. gnome-keyring-daemon
The gnome-keyring-daemon is a process that runs in the background, reacting to the commands to store and retrieve the password. Inside the gnome-keyring-daemon process, multiple modules work together to provide functionalities, such as encrypting and decrypting secrets when we store and retrieve secrets, respectively. The daemon process also contains modules that can manage the cryptographic keys automatically from the default SSH key directory.
In a nutshell, the gnome-keyring-daemon is the daemon process that serves the core functionality of the GNOME keyring.
By default, the GNOME keyring service is started when the system boots up. To validate if the gnome-keyring-daemon is running, we can use the pgrep command find process with the name gnome-keyring-daemon:
$ pgrep -f --list-full gnome-keyring-daemon
2913 /usr/bin/gnome-keyring-daemon --daemonize --login
In the example above, we use the -f option to match the full name. Additionally, the –list-full option will return the whole command for the process instead of just the PID.
With the daemon process up and running, we can start storing and retrieving secrets using the secret-tool CLI.
2.2. The secret-tool CLI
The secret-tool is a command-line interface that serves as the front-end for the gnome-keyring-daemon process. Through the secret-tool, we can store and retrieve secrets on the command-line terminal.
To obtain the secret-tool command, we can install the libsecret-tools package using the package manager of our system:
$ sudo apt-get install -y libsecret-tools
To store a secret, we can run the store subcommand and specify the attributes and label:
$ secret-tool store --label="My db password" server mydb
Password:
In the example above, we store a secret with an attribute server=mydb and the label “My db password“. The attribute is an important piece of information that serves as the key to the password. Then, we specify a free-text label for our password through the –label option. Notably, the –label option is mandatory when creating the password.
To retrieve the password, we can use the search subcommand followed by the attribute key and value:
$ secret-tool search server mydb
[/org/freedesktop/secrets/collection/login/3]
label = My db password
secret = mydbpassword
created = 2024-02-01 16:09:12
modified = 2024-02-01 16:09:12
schema = org.freedesktop.Secret.Generic
attribute.server = mydb
From the output, we can see that the search command shows various metadata along with the password we’ve stored. To obtain just the password without other metadata, we can use the lookup subcommand instead:
$ secret-tool lookup server mydb
mydbpassword
2.3. The libsecret Library
The libsecret is a library that the application can use to store and retrieve secrets from any process that implements Secret Service API, such as the GNOME keyring service.
For example, the git-credential-libsecret is one such program that uses the libsecret library. Specifically, the git-credential-libsecret is a program that uses the libsecret library to store and retrieve secrets from the GNOME keyring service.
3. Integrating GNOME Keyring With git Command
When we interact with remote Git repositories using the git command, oftentimes, we’ll need to authenticate ourselves with the remote server. Typically, the git command will prompt the user for their username and password so that it can relay that information to the remote server for authentication.
The git-credential-libsecret program is a program that the git invokes to resolve authentication information from the GNOME keyring process. In the subsequent section, we’ll learn how can we integrate the git command with the GNOME keyring process using the git-credential-libsecret program.
3.1. Installing git-credential-libsecret Binary
Firstly, we’ll have to build the git-credential-libsecret binary. To do that, we’ll need to install several dependencies:
$ sudo apt-get install -y gcc make libsecret-1-0 libsecret-1-dev
The gcc is the compiler that allows us to compile the git-credential-libsecret source code. Then, the make command is needed to run the build script that’s written in the Makefile. Finally, the libsecret-1-0 and libsecret-1-dev depend on the git-credential-libsecret binary.
After the installation of the pre-requisites, we can build the git-credential-libsecret binary by running the make command:
$ cd /usr/share/doc/git/contrib/credential/libsecret
$ sudo make
When the command runs successfully without any error, we can proceed to configure our git command to use git-credential-libsecret as its credential helper.
3.2. Configuring Git’s Credential Helper
In Git terminology, a credential helper is a program that resolves credentials to authenticate the user against a remote Git repository. There are various different credential helper programs that integrate with different secret managers. For example, the git-credential-osxkeychain for Mac OS’s keychain, git-credential-lastpass for LastPass password manager, and git-credential-winred for Windows Credential Manager.
In Linux, the git-credential-libsecret is the credential helper that stores and retrieves passwords from Linux secret services such as the GNOME keyring.
To set up the credential helper, we’ll configure the credential.helper configuration key for our git command:
$ git config --global credential.helper /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret
In the command above, we use the git-credential-libsecret as our credential helper.
3.3. In Action
To demonstrate the integration, we can clone a repository from the GitHub.com remote:
$ git clone https://github.com/userbob/private-repo-1.git
Cloning into 'private-repo-1'...
Username for 'https://github.com': userbob
Password for 'https://[email protected]':
remote: Enumerating objects: 152, done.
...
As we’ve not stored any authentication information in the keyring before, we’ll be prompted for the authentication information.
After successfully authenticating once, the git command stores the authentication information to the GNOME keyring using the git-credential-libsecret program.
We can verify it by checking the presence of a password with an attribute server=github.com using the secret-tool CLI:
$ secret-tool search server github.com
[/org/freedesktop/secrets/collection/login/4]
label = Git: https://github.com/
secret = github_pat_(TRUNCATED)
created = 2024-02-03 06:12:35
modified = 2024-02-03 06:12:35
schema = org.gnome.keyring.NetworkPassword
attribute.protocol = https
attribute.user = userbob
attribute.server = github.com
Subsequently, we can clone another private repository from the same account from GitHub.com:
$ git clone https://github.com/userbob/private-repo-2.git
Cloning into 'private-repo-2'...
remote: Enumerating objects: 28, done.
...
This time around, we don’t get prompted for username and password anymore when we clone. This is because the git command has successfully resolved it using the git-credential-libsecret.
4. Conclusion
In this tutorial, we’ve first learned that GNOME keyring is a password manager service in Linux. Then, we introduced the gnome-keyring-daemon as the core background process for the GNOME keyring application. Then, we’ve also learned about the secret-tool CLI and the libsecret library for integrating with GNOME keyring.
Subsequently, we’ve learned that we can integrate the git command with the GNOME keyring to automatically resolve authentication information through the git-credential-libsecret. Finally, we demonstrated the integration by cloning two different private repositories from GitHub.com.