{"id":42604912,"url":"https://github.com/zabojeb/phpgp","last_synced_at":"2026-01-29T01:49:45.348Z","repository":{"id":264932182,"uuid":"894699295","full_name":"zabojeb/phpgp","owner":"zabojeb","description":"phPGP - tool to store your PGP keys on the physical storage (USB, flash drive etc.)","archived":false,"fork":false,"pushed_at":"2025-04-19T20:01:18.000Z","size":78,"stargazers_count":5,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-29T01:09:07.218Z","etag":null,"topics":["cryptography","cybersecurity","encoding","gnupg","gpg","pgp","pypi","python","security","usb"],"latest_commit_sha":null,"homepage":"https://pypi.org/p/phpgp","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zabojeb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-26T20:32:45.000Z","updated_at":"2025-04-25T18:38:44.000Z","dependencies_parsed_at":"2024-11-26T21:42:50.809Z","dependency_job_id":null,"html_url":"https://github.com/zabojeb/phpgp","commit_stats":null,"previous_names":["zabojeb/phgpg","zabojeb/phpgp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zabojeb/phpgp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zabojeb%2Fphpgp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zabojeb%2Fphpgp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zabojeb%2Fphpgp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zabojeb%2Fphpgp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zabojeb","download_url":"https://codeload.github.com/zabojeb/phpgp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zabojeb%2Fphpgp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28859935,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T22:56:21.783Z","status":"ssl_error","status_checked_at":"2026-01-28T22:56:00.861Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptography","cybersecurity","encoding","gnupg","gpg","pgp","pypi","python","security","usb"],"created_at":"2026-01-29T01:49:43.161Z","updated_at":"2026-01-29T01:49:45.339Z","avatar_url":"https://github.com/zabojeb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# phPGP\n\n**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.\n\nThis README covers installation, usage, configuration, and other important details for working with **phpgp**.\n\n---\n\n## Table of Contents\n\n- [phPGP](#phpgp)\n  - [Table of Contents](#table-of-contents)\n  - [Features](#features)\n  - [Requirements](#requirements)\n  - [Installation](#installation)\n  - [Configuration](#configuration)\n  - [Usage](#usage)\n    - [Mounting and Unmounting](#mounting-and-unmounting)\n    - [Loading and Unloading Keys Locally](#loading-and-unloading-keys-locally)\n  - [Cryptographic Operations](#cryptographic-operations)\n    - [Signing Files](#signing-files)\n    - [Encrypting and Decrypting Files](#encrypting-and-decrypting-files)\n  - [How It Works](#how-it-works)\n  - [Project Structure](#project-structure)\n  - [Contributing](#contributing)\n  - [License](#license)\n\n---\n\n## Features\n\n- **Secure PGP key storage on external drives** (USB or similar)\n- **Server-based cryptographic operations**: signing, encryption, and decryption happen in memory, reducing key exposure\n- **Automatic passphrase prompt** when mounting the external drive.\n- **Detachable signatures** or encryption of files using your private key, stored only on the external drive\n- **Cross-platform**:\n  - Windows uses a TCP socket (default port 65432)\n  - macOS and Linux use a Unix Domain Socket (`/tmp/phpgp.sock` by default)\n- **PID management in an OS-specific cache directory** (e.g., `%LOCALAPPDATA%\\phpgp` on Windows, `~/Library/Caches/phpgp` on macOS, `~/.cache/phpgp` on Linux)\n\n---\n\n## Requirements\n\n- **Python 3.7+** (recommended)\n- **[GNUPG](https://gnupg.org/)** installed for local key imports (`load`, `unload`)\n- **[psutil](https://pypi.org/project/psutil/)** for detecting removable drives\n- **[Click](https://pypi.org/project/click/)** for building the CLI\n- **[PGPy](https://pypi.org/project/PGPy/)** library for handling PGP operations in Python\n\n---\n\n## Installation\n\nSimply install it via pip:\n\n```bash\npip install phpgp\n```\n\nor via pipx (recommended):\n\n```bash\npipx install phpgp\n```\n\n---\n\n## Configuration\n\n1. **Create or Obtain Your PGP Keys**:\n\n   - For testing, you can generate keys with GnuPG:\n\n     ```bash\n     gpg --full-generate-key\n     gpg --armor --export-secret-keys \u003e private_key.asc\n     gpg --armor --export \u003e public_key.asc\n     ```\n\n   - Alternatively, you may have existing keys in `.asc` format.\n\n2. **Configure an External Drive**:\n   - Make sure your USB drive or removable storage is mounted.\n   - Run:\n\n     ```bash\n     phpgp configure\n     ```\n\n   - 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`).\n   - You can choose to delete the keys from your local disk for extra security (which is recommended).\n\n---\n\n## Usage\n\nOnce installed, you have access to the `phpgp` command with various subcommands.\n\nWith phPGP you can either `mount` your USB or `load` keys from it.\n\nWhen 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.\n\nLet's take a closer look at this.\n\n### Mounting and Unmounting\n\n- **Mount**:\n\n  ```bash\n  phpgp mount\n  ```\n\n  1. Select the external drive.\n  2. Enter your passphrase to unlock your private key.\n  3. The server starts in your terminal window.\n  4. Optionally remove the key from the external drive.\n\n- **Unmount**:\n\n  ```bash\n  phpgp unmount\n  ```\n\n  1. Reads the server PID from the OS cache directory (e.g., `~/.cache/phpgp/phpgp_server.pid`).\n  2. Terminates the server process.\n  3. Removes the PID file.\n\n### Loading and Unloading Keys Locally\n\n- **Load**:\n\n  ```bash\n  phpgp load\n  ```\n\n  Imports keys from your external drive into your local GPG instance, allowing you to use GnuPG commands locally with those keys.\n\n- **Unload**:\n\n  ```bash\n  phpgp unload\n  ```\n\n  Removes the locally imported secret key from your GPG instance.\n\n\u003e [!NOTE]\n\u003e 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.\n\n## Cryptographic Operations\n\nWhen 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`.\n\n\u003e [!IMPORTANT]\n\u003e These commands will only work when the server is started with `phpgp mount`.\n\n### Signing Files\n\n1. Make sure the server is running (`phpgp mount`).\n2. Sign a file:\n\n   ```bash\n   phpgp sign path/to/file.txt\n   ```\n\n   - Reads `file.txt` in binary mode, base64-encodes it, sends it to the server.\n   - A detached signature is saved to `file.txt.sig`.\n\n3. Verify with GnuPG:\n\n   ```bash\n   gpg --verify file.txt.sig file.txt\n   ```\n\n### Encrypting and Decrypting Files\n\n- **Encrypt**:\n\n  ```bash\n  phpgp encrypt path/to/file.txt path/to/recipient_public_key.asc\n  ```\n\n  - The encrypted data is saved to `file.txt.enc`.\n\n- **Decrypt**:\n\n  ```bash\n  phpgp decrypt path/to/file.txt.enc\n  ```\n\n  - Decrypted data is saved to `file.txt.enc.dec`.\n\n---\n\n## How It Works\n\n1. **Configuration**:\n   - Creates a `.phpgp` folder on your external drive containing `private` and `public` folders with the appropriate keys.\n2. **Mounting**:\n   - Starts a background server (`phpgp.server`) with your private key loaded in memory.\n   - For security, you can remove the key files from the USB drive after mounting (recommended).\n3. **Server**:\n   - Listens on a socket (TCP on Windows, Unix Domain Socket elsewhere).\n   - Receives JSON requests for `sign`, `encrypt`, `decrypt`.\n   - PGP operations happen in memory; the private key is **never** saved on local disk after mounting and **never** exposed until the `unmount` operation.\n4. **Client Commands** (subcommands in `cli.py`):\n   - Communicate with the server using JSON messages.\n   - Return results (signatures, encrypted data, decrypted data).\n\n---\n\n## Project Structure\n\n```\nphpgp/\n├── __init__.py            # Metadata\n├── cli.py                 # Main CLI implemented with Click\n├── server.py              # The server handling sign/encrypt/decrypt\n└── utils.py               # Helper functions for drive selection \u0026 cache path\n```\n\n---\n\n## Contributing\n\nThere is some issues now, feel free to fix them!\n\n1. **Fork** the repository on GitHub.\n2. **Create a Feature Branch** from `main`.\n3. **Implement** your feature or bug fix.\n4. **Add Tests** where and if applicable.\n5. **Open a Pull Request** describing your changes.\n\n---\n\n## License\n\nphpgp is licensed under the GNU General Public License v3.0.\n\nYou should have received a copy of the GNU General Public License along with this program. If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n\n---\n\n**Enjoy secure and convenient PGP key usage with phPGP!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzabojeb%2Fphpgp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzabojeb%2Fphpgp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzabojeb%2Fphpgp/lists"}