#git #keepass #command-line #keepassxc

app git-credential-keepassxc

Helper that allows Git to use KeePassXC as credential store

11 unstable releases (3 breaking)

0.4.1 Aug 15, 2020
0.4.0 Aug 8, 2020
0.3.3 Jul 20, 2020
0.3.0 Jun 23, 2020
0.1.3 May 10, 2020

#5 in Authentication

Download history 14/week @ 2020-05-23 32/week @ 2020-05-30 12/week @ 2020-06-06 7/week @ 2020-06-13 17/week @ 2020-06-20 25/week @ 2020-06-27 12/week @ 2020-07-04 37/week @ 2020-07-11 45/week @ 2020-07-18 11/week @ 2020-07-25 1/week @ 2020-08-01 44/week @ 2020-08-08 32/week @ 2020-08-15 2/week @ 2020-08-22 16/week @ 2020-08-29 45/week @ 2020-09-05

87 downloads per month

GPL-3.0-or-later

120KB
3K SLoC

git-credential-keepassxc Travis CI status License: GPL v3 crates.io version

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

  1. Install Rust compiler via rustup or your favourite package manager
  2. Run cargo install git-credential-keepassxc (or cargo install --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.

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

It is suggested to use cargo-update to make the features you've enabled persistent across updates.

# install cargo-update first
$ cargo install cargo-update
# enable and persist features
$ cargo install --features <FEATURE>... git-credential-keepassxc
$ cargo install-update-config --feature <FEATURE>... git-credential-keepassxc

# later when you update
$ cargo install-update git-credential-keepassxc

Configuration

Similar as 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.

Limit 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 add --uid "$(id -u)" --gid "$(id -g)" "$(readlink -f "$0")"
# 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 You are not allowed to use this program, Caused by: N/A, Message: You are not allowed to use this program
$ 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.

Encrypt 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

Tip

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.

  1. In KeePassXC, go to Tools -> Settings -> Browser Integration -> Advanced, enable Return advanced string fields which start with "KPH: " (this is enabled by default)
  2. Open the entry you'd like to hide
  3. Go to Advanced
  4. Add an additional attribute KPH: git (the space after colon is necessary) of which the value is false

Scripting

git-credential-keepassxc can also help manage credentials in shell scripts. 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

Dependencies

~8.5MB
~169K SLoC