Content-Security-Policy: default-src 'none' · Strict-Transport-Security & X-Content-Type-Options: provided by GitHub/PyPI edge infrastructure. Headers are verified in docs/HARDENING.md.

GUN-101-GKP — Ghost Key Protocol

Passwordless asymmetric encryption for files, using RSA-4096 key encapsulation and AES-256-GCM data encryption.

What problem does it solve?

Sending a sensitive file to a specific recipient usually means agreeing on a password or shared secret over a secure channel. GUN-101-GKP removes that step.

The recipient generates an RSA-4096 key pair and shares only a public Identity Token. Anyone holding that token can encrypt a file for the recipient, but only the holder of the matching private key can decrypt it — with no password and no shared secret exchanged.

Installation

Install GUN-101-GKP from PyPI:

pip install gun101-gkp

Bash completion

A Bash completion script is available at scripts/completions/bash/gun101gkp.bash.

To enable it for the current shell from a source checkout:

source scripts/completions/bash/gun101gkp.bash

For persistent per-user completion on systems using bash-completion:

mkdir -p ~/.local/share/bash-completion/completions
cp scripts/completions/bash/gun101gkp.bash ~/.local/share/bash-completion/completions/gun101gkp

Start a new Bash session after installing the completion file.

Quick start

# Recipient: generate an identity once
gun101gkp generate-identity

# Sender: encrypt a file for the recipient
gun101gkp encrypt report.pdf --recipient GUN101GKP-v2-...

# Recipient: decrypt
gun101gkp decrypt report.pdf.gkp

Full usage is documented in the README and the API reference.

How it protects data

• Confidentiality — RSA-4096 with OAEP (SHA-256) and AES-256-GCM protect the file contents.
• Integrity & authenticity — the AES-GCM tag detects any modification before decryption proceeds.
• Wrong-key rejection — a recipient public-key fingerprint is verified before any RSA operation.
• Fresh key per file — a random 256-bit data encryption key (DEK) is generated for every encryption.

Project status and security

• Security policy
• Threat model
• Security properties
• Architecture (high-level design)
• Roadmap
• Governance
• Code of conduct

Contributing

Contributions are welcome. Please read the contributing guide first. The authors are listed in AUTHORS.md.

• Start with a small task — see the starter-task list and the good first issue label.
• Report a bug or request a feature — open a GitHub issue.
• Submit changes — contribute via a pull request; sign off your commits per the DCO.
• Report a security vulnerability — email privately (see the security policy); do not open a public issue.

License

MIT. See the LICENSE file.