Encryption

Introduction

git-credential-keepassxc allows encrypting the database and caller profiles stored in the configuration file. Currently YubiKey HMAC-SHA1 challenge-response is the only supported method.

How it works

Each challenge-response encryption profile essentially consists of a challenge, a nonce and an encrypted copy of the master key.

During decryption, git-credential-keepassxc first tries to locate a best-matching encryption profile using YubiKey's serial number before performing challenge-response. The response then is used to decrypt the master key, which finally is used to decrypt the database and caller profiles.

                                            Master Key Ciphertext  Database/Caller Ciphertext
                                                     │                        │
                                                     v                        v
Challenge (64B) => YubiKey => Response (20B) => AES Key (32B) =====> Master Key (32B) => Database/Caller Plaintext
                                    ^                ^                        ^
                                    │                │                        │
                               Padding (12B)     Nonce (12B)        Database/Caller Nonce (12B)

How to use

One or multiple YubiKeys with the same secret (and same master key)

This is the recommended way to utilise git-credential-keepassxc encryption for its simplicity.

Encryption

After you've done configuring git-credential-keepassxc, run:

$ git-credential-keepassxc encrypt challenge-response

You only need to run this command once. When a different YubiKey with the same secret is used, git-credential-keepassxc will automatically fall back to the existing encryption profile.

Or, you can also directly encrypt the database/caller profiles during configuration:

$ git-credential-keepassxc configure --encrypt "challenge-response"
$ git-credential-keepassxc caller add --encrypt "challenge-response" --uid $(id -u) --gid $(id -g) /usr/bin/git
# you can also leave --encrypt empty here, since there has already been an existing encryption profile
$ git-credential-keepassxc caller add --encrypt "" --uid $(id -u) --gid $(id -g) /usr/lib/git-core/git-remote-http

Decryption

$ git-credential-keepassxc decrypt

Multiple YubiKeys with different secrets (but the same master key)

Since database/caller profiles are encrypted using a master key (rather than the response directly), secondary YubiKeys with different secrets can be added to the configuration as long as the master key can be extracted from an existing encryption profile first.

Encryption

For example, after configuring all the databases and callers,

# Plug in your primary YubiKey
$ git-credential-keepassxc -vv encrypt challenge-response
# Keep your primary Yubikey plugged in, now configure the secondary YubiKey
$ git-credential-keepassxc -vv encrypt challenge-response
# You will be asked to confirm that the primary YubiKey is plugged in first
# Then after extracting the master key, git-credential-keepassxc will ask you to plug in the secondary one to continue

Decryption

You can fully decrypt the configuration file using any of the YubiKeys.

Multiple YubiKeys with different secrets (and different master keys)

Since partial decryption may happen in this scenario, it's usually NOT recommended to use this method.

Encryption

For example, we'd like to configure two encrypted database profiles using a different YubiKey each. User can only decrypt the corresponding database profile while using.

# Plug in the first YubiKey
$ git-credential-keepassxc -vv configure --encrypt "challenge-response"
# Now remove the first YubiKey and plug in the second one
$ git-credential-keepassxc -vv configure --encrypt "challenge-response"

Note: Avoid adding encrypted caller profiles when using this method. Since all caller profiles must be decrypted when verifying the calling program, they must also be encrypted using the same master key. Hence you may end up with a YubiKey that can decrypt one or more databases but not the callers, rendering it unusable.

Decryption

git-credential-keepassxc decrypt adopts a best-effort mechanism here and you must run the command with all the YubiKeys one by one to fully decrypt the configuration file.