keychain-interpose

This software makes it possible to store GPG secret key files in the
MacOS keychain
instead of in the ~/.gnupg/private-keys-v1.d directory.

Background

By default, gpg-agent(1) stores secret keys in the private-keys-v1.d directory inside
the gpg(1) home directory (typically ~/.gnupg). If the secret keys are password-protected,
these files are stored in a password-protected format. However, an attacker who obtains
these key files could hold onto them for potential later use. For example:

• The attacker could run offline brute-forcing techniques on the key files;
• As machines became more powerful or new algorithms are invented, it may become possible to
  decrypt the exfiltrated keys using techniques that are more advanced than brute-forcing; or
• If the paswords were later compromised, the compromised passwords could be used to decrypt
  the already-exfiltrated key files at the attacker's leisure.

Storing the secret key files in the keychain instead of in the private-keys-v1.d directory
makes it more difficult to exfiltrate the key files because access to the key files can be
limited to the authorized gpg-agent(1) process and its authorized dependencies.

How keychain-interpose works

There are four components involved in migrating the secret keys to the keychain:

1. A supplied program named migrate-keys reads the keys from the private-keys-v1.d
   directory, adds them to the keychain, and then replaces the keys in the private-keys-v1.d
   directory with empty files (placeholders). See src/migrate-keys.cpp.

2. A supplied library named keychain-interpose.dylib is designed to be injected into
   the gpg-agent(1) process when it starts up. This library causes gpg-agent(1) to
   attempt to find secret keys in the keychain before falling back to the filesystem.
   See src/keychain-interpose.cpp.

3. To prevent any unauthorized code from accessing the keychain entries, it is necessary
   to enable the Hardened Runtime
   environment for gpg-agent(1) and all of its dependencies (including keychain-interpose.dylib)
   and to sign gpg-agent(1) and its dependencies with a codesigning key or keys bearing
   a single Team ID.
   The Makefile in the repository properly signs migrate-keys and keychain-interpose.dylib
   as they are built. There also exists a make target (make sign-gpg-agent) to sign
   gpg-agent(1) and its other dependencies, assuming that gpg-agent(1) was installed using
   the Homebrew gnupg package.

4. The user's GPG configuration file (typically ~/.gnupg/gpg.conf) must be modified to
   set the agent-program to be a shell script that loads gpg-agent(1) with
   the keychain-interpose.dylib library injected into it. An example script can be
   found at testing/agent.sh in the repository.

Building the software

Clone the repository with git clone --recurse https://github.com/cathyjf/keychain-interpose.

Install the project's dependencies with Homebrew:
brew install boost fmt gnupg llvm.

Run make install -j in the project directory to build the software and sign it with your
codesigning identity. The codesign command, which is invoked several times by the Makefile,
may prompt you for your password.

The binaries will be installed at ~/.gnupg/keychain-interpose.dylib and ~/.gnupg/migrate-keys.

Difference between keychain-interpose and pinentry-mac

The pinentry-mac program can be configured to store the passwords for secret keys
in the keychain. This is unrelated to the purpose of keychain-interpose, which is to
store the password-protected secret keys themseleves in the keychain. The keychain-interpose
project is not a replacement for pinentry and works in conjunction with a pinentry
program like pinentry-mac, if you wish to use one.

Warning

This is experimental software that I made for my own use only. You should back up your
private keys and other valuable data before using this software. Although this software
is intended to be useful, I can make no guarantees that it will work correctly. If the
software has bugs (and it might), you may find yourself unable to use your local secret
keys at all, which is why you should have backups.

Licensing

License for keychain-interpose

The keychain-interpose project was created by Cathy J. Fitzpatrick <cathy@cathyjf.com> (copyright 2023).

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see https://www.gnu.org/licenses/.

License for libgpg-error

The keychain-interpose.dylib library (built from the source in this repository) links
against libgpg-error, which was released under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation, either version 2.1 of the License, or
any later version.

I have chosen to use libgpg-error under the terms of version 3 of the GNU Lesser General
Public License. A copy of version 3 of the GNU Lesser General Public License is available
at the following location: https://www.gnu.org/licenses/lgpl-3.0.en.html

This repository does not contain a copy of libgpg-error. You should generally obtain
libgpg-error by installing the gnupg package from Homebrew, as described above
under the heading "Building the software".

License for CoreFoundation++

This repository incorporates CoreFoundation++, which was
released by its author (@macmade) under the following license:

The MIT License (MIT)

Copyright (c) 2014 Jean-David Gadina - www.xs-labs.com / www.digidna.net

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.