Secure secret sharing using gpg

Table of contents

  1. Abstract
  2. Use case
  3. Client-Side (Your Consumer)
    1. Step 1: Client Generates a PGP Key Pair
    2. Step 2: Upload Public Key to keys.openpgp.org
  4. Server-Side (Your System)
    1. Step 3: Fetch the Client’s Public Key
    2. Step 4: Verify the Key (Optional but Recommended)
    3. Step 5: Encrypt Secrets Using the Client’s Public Key
  5. Client-Side (Decrypting the Secrets)
  6. Optional Enhancements
  7. Summary

Abstract

This document outlines a complete workflow for securely exchanging sensitive information between a client and a server using PGP encryption. It details the step-by-step process for clients to generate a PGP key pair, verify their email, and publish their public key on keys.openpgp.org via command-line tools, graphical interfaces, or dedicated applications across different operating systems. On the server side, it describes how to fetch, verify, and use the client’s public key to encrypt confidential data before delivery, ensuring only the intended recipient can decrypt it. Additional recommendations include optional features such as one-time downloads, expiration metadata, signed payloads, and audit trails to enhance security and traceability. A final summary table consolidates the protocol steps for quick reference.

Use case

A secure protocol for delivering API credentials to a client using PGP (GPG) encryption. The client generates a PGP key pair, verifies their email, and uploads their public key to keys.openpgp.org. The API provider retrieves and verifies the public key, then encrypts the API credentials so only the client’s private key can decrypt them. Step-by-step instructions cover key generation for multiple platforms, key publishing, secure encryption, and decryption. Optional enhancements, such as one-time downloads, key expiry checks, and signed payloads, further strengthen confidentiality and integrity. This process ensures that API secrets are exchanged over untrusted channels without risk of exposure.

Client-Side (Your Consumer)

Step 1: Client Generates a PGP Key Pair

This is the foundation of the whole protocol — the client needs to generate a PGP key pair and upload their public key to https://keys.openpgp.org.

Required Info for All Methods:

  • Name: Client name or company name
  • Email: Must be real (used for verifying key with the server)
  • Key Type: RSA 2048+ or ECC
  • Passphrase: Strong and secure; protects the private key

Option A: Command Line (Linux & Windows WSL)

If comfortable with the terminal:

gpg --full-generate-key
  • Choose RSA and RSA
  • Key size: 2048 or 4096
  • Set expiry: (e.g. 1 year)
  • Enter name and verified email
  • Choose a strong passphrase

After creation:

gpg --armor --export client@example.com > pubkey.asc

Option B: GPG Suite (macOS)

Recommended for macOS users

  1. Download: https://gpgtools.org
  2. Open GPG Keychain
  3. Click ➕ to create a new key
  4. Enter name, email, and passphrase
  5. Click “Generate Key”

Export Public Key:

  • Right-click your key → Export…
  • Choose .asc format

Option C: Kleopatra (Windows GUI)

Recommended for Windows users

  1. Install Gpg4win: https://gpg4win.org
    • Includes Kleopatra GUI
  2. Launch Kleopatra
  3. Menu → File → New Key Pair
  4. Choose “Create a personal OpenPGP key pair”
  5. Fill name and email
  6. Set an expiration date and passphrase
  7. Finish the wizard

Export Public Key:

  • Right-click the key → Export…
  • Save as pubkey.asc

Step 2: Upload Public Key to keys.openpgp.org

Regardless of how the key was generated:

Option 1: Upload Manually

  1. Go to: https://keys.openpgp.org
  2. Click “Submit Key”
  3. Upload your pubkey.asc
  4. Click the verification link sent to your email

Option 2: From Terminal (if using GPG CLI)

gpg --send-keys --keyserver hkps://keys.openpgp.org <KEY_ID>

Replace <KEY_ID> with the key fingerprint or short ID:

gpg --list-keys

Then check your inbox and click the confirmation link to publish it.

You now have a PGP public key tied to an email address, hosted on keys.openpgp.org.

Server-Side (Your System)

Step 3: Fetch the Client’s Public Key

curl "https://keys.openpgp.org/vks/v1/by-email/client@example.com" > client_pubkey.asc

Or use your preferred HTTP client (Python, Go, etc.).

You may want to verify:

  • The UID contains the client’s expected email.
  • The key is not expired or revoked.
  • The key strength is sufficient (e.g., RSA 2048+).

Use GPG to import and inspect:

gpg --import client_pubkey.asc
gpg --list-keys client@example.com

Step 5: Encrypt Secrets Using the Client’s Public Key

Let’s say your secret is in a file:

echo "CLIENT_ID=abc123
CLIENT_SECRET=xyz789
API_KEY=api_key_456" > client_secrets.txt

Encrypt with GnuPG:

gpg --encrypt --armor --recipient client@example.com client_secrets.txt

This creates a file: client_secrets.txt.asc — an ASCII-armored, PGP-encrypted version.

You can now send this securely to the client:

  • Email
  • Dashboard download
  • One-time HTTPS link

Only the client with the private key can decrypt it.

Client-Side (Decrypting the Secrets)

When the client receives client_secrets.txt.asc, they run:

gpg --decrypt client_secrets.txt.asc

If their private key is loaded and passphrase is entered, it decrypts to:

CLIENT_ID=abc123
CLIENT_SECRET=xyz789
API_KEY=api_key_456

Optional Enhancements

FeatureDescription
One-Time DownloadHost the .asc file on a secure server, destroy it after first access.
Expiration MetadataInclude issue/expiration timestamps in the plaintext or as PGP notation.
Key Expiry CheckingBefore encrypting, check if the client’s key is still valid.
Signed PayloadOptionally sign the secret payload with your server’s private PGP key.
Audit TrailLog key fingerprints, timestamps, and delivery events.

Summary

StepPartyAction
1ClientGenerates PGP key and verifies email
2ServerFetches public key by email from keys.openpgp.org
3ServerEncrypts secret payload with client’s key
4ServerDelivers encrypted blob to client
5ClientDecrypts with their private key