git-credential-keepassxc
git-credential-keepassxc copied to clipboard
Helper that allows Git (and shell scripts) to use KeePassXC as credential store
git-credential-keepassxc
git-credential-keepassxc
is a Git credential helper that allows Git (and shell scripts) to get/store logins from/to KeePassXC.
It communicates with KeePassXC using keepassxc-protocol which is originally designed for browser extensions.
How to install
Quick
- Install Rust compiler via rustup or your favourite package manager
- Run
cargo install --locked git-credential-keepassxc
(orcargo install --locked --git https://github.com/Frederick888/git-credential-keepassxc.git
for the latest development version)
Note: Make sure $CARGO_INSTALL_ROOT
is in your search path.
Pre-Built Binaries (Experimental)
Pre-built binaries are now available at the GitHub release page.
The *-minimal
ones are built with no features enabled, and *-full
ones are built with all.
Optional features
git-credential-keepassxc
currently has got the following features that you can choose to opt in:
Feature | Description |
---|---|
all |
Enable all features |
notification |
Desktop notifications, helpful if git-credential-keepassxc is used in scripts |
yubikey |
Allow encrypting configuration file using YubiKey HMAC-SHA1 |
strict-caller |
Enforce caller limiting when there are associated databases (read the Limiting callers section for details) |
It is suggested to use cargo-update to make the features you've enabled persistent across updates.
# install cargo-update first
$ cargo install --locked cargo-update
# enable and persist features
$ cargo install --locked --features <FEATURE>... git-credential-keepassxc
# note the flipped order of package name and --feature flag
$ cargo install-update-config git-credential-keepassxc --enforce-lock --feature <FEATURE>...
# later when you update
$ cargo install-update git-credential-keepassxc
Configuration
Similar to the browser extensions, git-credential-keepassxc
needs to be associated with KeePassXC first.
Run:
$ git-credential-keepassxc configure
$ git config --global credential.helper keepassxc
A group (by default Git
) will be created to store new logins.
For more options, run git-credential-keepassxc -h
to show the help message.
Limiting callers
git-credential-keepassxc
allows you to limit callers (though you should probably have a look at some MAC systems to properly achieve this), for instance:
# don't forget to add yourself first
$ git-credential-keepassxc caller me
Gonna save current caller to allowed callers list:
{
"path": "/usr/bin/zsh",
"uid": 1000,
"gid": 1000,
"canonicalize": false
}
Press Enter to continue...
# then allow Git to access KeePassXC when sending emails via SMTP
$ git-credential-keepassxc caller add --uid "$(id -u)" --gid "$(id -g)" "$(command -v git)"
# also add other Git executables if you want to e.g. clone via HTTPS
$ git-credential-keepassxc caller add --uid "$(id -u)" --gid "$(id -g)" /usr/lib/git-core/git-remote-http
$ sh -c 'printf "url=https://example.com\nusername=foo\n" | git-credential-keepassxc get'
May 10 12:51:56.108 ERRO /usr/bin/bash (uid=1000, gid=1000) is not allowed to call git-credential-keepassxc, Caused by: N/A
$ printf 'url=https://example.com\nusername=foo\n' | git credential fill
May 10 12:52:53.995 WARN Request get-logins failed. Error: No logins found, Error Code: 15
May 10 12:52:53.995 ERRO Request get-logins failed, Caused by: N/A, Message: Request get-logins failed
# disable this function
$ git-credential-keepassxc caller clear
Note: If you've enabled strict-caller
, you must add caller profiles before configuring databases, otherwise you won't be able to run git-credential-keepassxc
afterwards.
Encrypting KeePassXC keys using YubiKey
By default the keys for authentication are stored in plaintext, which means it's possible for malware to extract the keys and request credentials from KeePassXC directly. This can be particularly dangerous if you've allowed clients to retrieve any credentials without confirmation.
git-credential-keepassxc
is capable of encrypting KeePassXC keys using YubiKey Challenge-Response. First make sure you've enabled yubikey
feature, then:
# encrypt using YubiKey slot 2 and a randomly generated challenge
$ git-credential-keepassxc encrypt challenge-response
To decrypt the keys and then disable this feature:
$ git-credential-keepassxc decrypt
For more details, see: wiki/Encryption
Ignoring certain entries
Although currently it's not possible to return entries only from the Git group, you may still want to hide specific ones from Git (for instance GitLab allows only access tokens to clone over HTTPS when 2FA is enabled, so your password may conflict with the token). This can be done by adding a magic attribute to those entries.
- In KeePassXC, go to Tools -> Settings -> Browser Integration -> Advanced, enable
Return advanced string fields which start with "KPH: "
(this is enabled by default) - Open the entry you'd like to hide
- Go to Advanced
- Add an additional attribute
KPH: git
(the space after colon is necessary) of which the value isfalse
Scripting
git-credential-keepassxc
can also help manage credentials in shell scripts. You can send a request via standard input in git-credential input/output format then process the response.
Currently accepted fields in input (unknown fields are ignored):
-
url
-
username
-
password
(store
requests only)
Responses are in the same format. Alternatively get
, totp
, store
, and generate-password
responses can also be formatted in JSON by providing --json
flag; get
and totp
also support --raw
flag.
For instance, to connect to a Remote Desktop service:
#!/usr/bin/env bash
trap 'notify-send "RDP Failure" "Failed to connect to Remote Desktop service"' ERR
HOST="example.com"
PORT="3389"
USERNAME="Administrator"
PASSWORD="$(printf 'url=rdp://%s:%s\nusername=%s\n' "$HOST" "$PORT" "$USERNAME" | git-credential-keepassxc get | sed -n 's/^password=//p')"
xfreerdp /v:"$HOST:$PORT" /cert-tofu /cert:ignore \
/size:2560x1620 /smart-sizing /scale:140 /scale-desktop:140 /scale-device:140 \
+compression /compression-level:2 +clipboard +themes +wallpaper \
/t:Example +decorations /u:"$USERNAME" /p:"$PASSWORD"
Security
See: wiki/Security