phPGP

phpgp is a command-line utility designed for secure storage and usage of PGP keys on external drives (such as USB flash drives). The project provides a server component to handle cryptographic operations (sign, encrypt, decrypt) in memory, ensuring private keys do not remain on the host machine.

This README covers installation, usage, configuration, and other important details for working with phpgp.

Table of Contents

• phPGP
  • Table of Contents
  • Features
  • Requirements
  • Installation
  • Configuration
  • Usage
    • Mounting and Unmounting
    • Loading and Unloading Keys Locally
  • Cryptographic Operations
    • Signing Files
    • Encrypting and Decrypting Files
  • How It Works
  • Project Structure
  • Contributing
  • License

Features

• Secure PGP key storage on external drives (USB or similar)
• Server-based cryptographic operations: signing, encryption, and decryption happen in memory, reducing key exposure
• Automatic passphrase prompt when mounting the external drive.
• Detachable signatures or encryption of files using your private key, stored only on the external drive
• Cross-platform:
  • Windows uses a TCP socket (default port 65432)
  • macOS and Linux use a Unix Domain Socket (/tmp/phpgp.sock by default)
• PID management in an OS-specific cache directory (e.g., %LOCALAPPDATA%\phpgp on Windows, ~/Library/Caches/phpgp on macOS, ~/.cache/phpgp on Linux)

Requirements

• Python 3.7+ (recommended)
• GNUPG installed for local key imports (load, unload)
• psutil for detecting removable drives
• Click for building the CLI
• PGPy library for handling PGP operations in Python

Installation

Simply install it via pip:

pip install phpgp

or via pipx (recommended):

pipx install phpgp

Configuration

1. Create or Obtain Your PGP Keys:

   • For testing, you can generate keys with GnuPG:

     gpg --full-generate-key
     gpg --armor --export-secret-keys > private_key.asc
     gpg --armor --export > public_key.asc
     

   • Alternatively, you may have existing keys in .asc format.

2. Configure an External Drive:

   • Make sure your USB drive or removable storage is mounted.

   • Run:

     phpgp configure
     

   • This will prompt you for paths to your private and public keys and copy them to the drive (e.g., X:\.phpgp\private and X:\.phpgp\public).

   • You can choose to delete the keys from your local disk for extra security (which is recommended).

Usage

Once installed, you have access to the phpgp command with various subcommands.

With phPGP you can either mount your USB or load keys from it.

When mounted, phPGP starts local server on your machine so you can do all PGP operations using this server and phpgp commands. This is better for security than just loading keys from USB.

Let's take a closer look at this.

Mounting and Unmounting

• Mount:

  phpgp mount
  

  1. Select the external drive.
  2. Enter your passphrase to unlock your private key.
  3. The server starts in your terminal window.
  4. Optionally remove the key from the external drive.

• Unmount:

  phpgp unmount
  

  1. Reads the server PID from the OS cache directory (e.g., ~/.cache/phpgp/phpgp_server.pid).
  2. Terminates the server process.
  3. Removes the PID file.

Loading and Unloading Keys Locally

• Load:

  phpgp load
  

  Imports keys from your external drive into your local GPG instance, allowing you to use GnuPG commands locally with those keys.

• Unload:

  phpgp unload
  

  Removes the locally imported secret key from your GPG instance.

[!NOTE] For greater security, you can set your computer to delete the private key automatically with this command when you disconnect the USB. You can do the same with key downloading for convenience.

Cryptographic Operations

When you run the phPGP server via mount, you will want to perform operations using phpgp instead of gpg. This can be done with the appropriate commands: phpgp sign, phpgp encrypt, phpgp decrypt.

[!IMPORTANT] These commands will only work when the server is started with phpgp mount.

Signing Files

1. Make sure the server is running (phpgp mount).

2. Sign a file:

   phpgp sign path/to/file.txt
   

   • Reads file.txt in binary mode, base64-encodes it, sends it to the server.
   • A detached signature is saved to file.txt.sig.

3. Verify with GnuPG:

   gpg --verify file.txt.sig file.txt
   

Encrypting and Decrypting Files

• Encrypt:

  phpgp encrypt path/to/file.txt path/to/recipient_public_key.asc
  

  • The encrypted data is saved to file.txt.enc.

• Decrypt:

  phpgp decrypt path/to/file.txt.enc
  

  • Decrypted data is saved to file.txt.enc.dec.

How It Works

1. Configuration:
   • Creates a .phpgp folder on your external drive containing private and public folders with the appropriate keys.
2. Mounting:
   • Starts a background server (phpgp.server) with your private key loaded in memory.
   • For security, you can remove the key files from the USB drive after mounting (recommended).
3. Server:
   • Listens on a socket (TCP on Windows, Unix Domain Socket elsewhere).
   • Receives JSON requests for sign, encrypt, decrypt.
   • PGP operations happen in memory; the private key is never saved on local disk after mounting and never exposed until the unmount operation.
4. Client Commands (subcommands in cli.py):
   • Communicate with the server using JSON messages.
   • Return results (signatures, encrypted data, decrypted data).

Project Structure

phpgp/
├── __init__.py            # Metadata
├── cli.py                 # Main CLI implemented with Click
├── server.py              # The server handling sign/encrypt/decrypt
└── utils.py               # Helper functions for drive selection & cache path

Contributing

There is some issues now, feel free to fix them!

1. Fork the repository on GitHub.
2. Create a Feature Branch from main.
3. Implement your feature or bug fix.
4. Add Tests where and if applicable.
5. Open a Pull Request describing your changes.

License

phpgp is licensed under the GNU General Public License v3.0.

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

Enjoy secure and convenient PGP key usage with phPGP!