GPG Signing and Repository Security

• Back to ActiveDebianSync main section

ActiveDebianSync provides comprehensive GPG (GNU Privacy Guard) signing capabilities to ensure the integrity and authenticity of your Debian repository. This document explains why GPG signing is critical and how to use it effectively.

Why GPG Signing Matters

When a client runs apt update and apt install, it downloads packages from a repository over the network. 

Without cryptographic verification, several attacks become possible:

• Man-in-the-Middle (MITM) Attacks: An attacker on the network path could intercept and modify packages, inserting malware or backdoors.
• Repository Compromise: If a mirror or repository server is compromised, attackers could replace legitimate packages with malicious versions.
• DNS Hijacking: Attackers could redirect repository URLs to malicious servers serving trojanized packages.
• Replay Attacks: Old, vulnerable versions of packages could be served instead of patched versions.

Enabling GPG Signing

Add the following to your config.json:

{
  "gpg_signing_enabled": true,
  "gpg_private_key_path": "/etc/ActiveDebianSync/gpg/private.key",
  "gpg_public_key_path": "/etc/ActiveDebianSync/gpg/public.key",
  "gpg_key_name": "My Organization Repository",
  "gpg_key_email": "repo@example.com",
  "gpg_key_comment": "Package signing key"
}

Automatic Key Generation

When gpg_signing_enabled is true and ActiveDebianSync starts:

1. Keys Exist: Loads the existing private key and enables signing
2. No Keys: Automatically generates a new 4096-bit RSA key pair

This means you can enable GPG signing with zero manual setup:

{
  "gpg_signing_enabled": true
}

On first startup, you'll see:

INFO: GPG keys not found, generating new key pair...
INFO: Generating GPG key pair for ActiveDebianSync Repository <repo@activedebiansync.local>
INFO: Private key saved to: /etc/ActiveDebianSync/gpg/private.key INFO: Public key saved to: /etc/ActiveDebianSync/gpg/public.key
INFO: GPG Key fingerprint: 1234ABCD5678EF90...
INFO: GPG signing enabled (new key pair generated automatically)

Key Specifications
Auto-generated keys use secure defaults

Manual Key Management

ActiveDebianSync provides CLI commands for GPG management:

• Generate new key pair (interactive): activedebiansync gpg init
• Export public key to file: activedebiansync gpg export-key /path/to/output.asc
• Export public key to stdout: activedebiansync gpg export-key -
• Sign all Release files manually: activedebiansync gpg sign
• Display key information: activedebiansync gpg info

Example: Manual Key Generation

activedebiansync gpg init
Generating GPG key pair...
Name: My Company Repository
Email: packages@mycompany.com
Comment: Official package signing key

Generating 4096-bit RSA key...
Private key saved to: /etc/ActiveDebianSync/gpg/private.key
Public key saved to: /etc/ActiveDebianSync/gpg/public.key
Key fingerprint: A1B2C3D4E5F6789012345678ABCDEF1234567890 GPG key pair generated successfully!

API Endpoints

GPG Status
Get the current GPG signing status :curl http://127.0.0.1:9090/api/gpg/status

Response:

{
  "enabled": true,
  "status": "ready",
  "key_exists": true,
  "key_loaded": true,
  "private_key_path": "/etc/ActiveDebianSync/gpg/private.key",
  "public_key_path": "/etc/ActiveDebianSync/gpg/public.key",
  "key_info": {
      "name": "ActiveDebianSync Repository",
      "email": "repo@activedebiansync.local",
      "comment": "Automatic repository signing key",
      "fingerprint": "A1B2C3D4E5F6789012345678ABCDEF1234567890",
      "keyid": "ABCDEF1234567890",
      "created": "2024-01-15T10:30:00Z",
      "algorithm": "RSA",
      "bits": "4096"
  }
}

GPG Key Information
Get detailed key information: 
curl http://127.0.0.1:9090/api/gpg/info

Generate New Key
Generate a new GPG key pair via API:

• Generate with default values from config: 
  curl -X POST http://127.0.0.1:9090/api/gpg/generate
   
• Generate with custom values: 
  curl -X POST http://127.0.0.1:9090/api/gpg/generate \
  -H "Content-Type: application/json" \
  -d '{"name": "My Repository","email": "admin@example.com","comment": "Package signing key" }'
• Force regenerate (replace existing key)
  curl -X POST http://127.0.0.1:9090/api/gpg/generate \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

Response:

{
  "status": "success",
  "message": "GPG key pair generated successfully",
  "key_info": {
      "name": "My Repository",
      "email": "admin@example.com",
      "fingerprint": "...",
      "created": "2024-01-15T10:30:00Z"
  }
}

Sign Release Files
Trigger signing of all Release files:
curl -X POST http://127.0.0.1:9090/api/gpg/sign

Response:

{
  "status": "success",
  "message": "All Release files signed successfully"
}

Export Public Key
Export the public key for distribution:

• Download as PGP armored text
  curl http://127.0.0.1:9090/api/gpg/export > repo-key.asc
• Get as JSON with key info
  curl "http://127.0.0.1:9090/api/gpg/export?format=json"

Get Client Instructions

Get ready-to-use instructions for APT clients:

• Markdown format
  curl http://127.0.0.1:9090/api/gpg/instructions
• JSON format
  curl "http://127.0.0.1:9090/api/gpg/instructions?format=json"
• With custom server URL
  curl "http://127.0.0.1:9090/api/gpg/instructions?server_url=https://packages.example.com"

Download Public Key (No Auth)

Public endpoint for clients to download the key:

curl http://your-server:9090/api/gpg-key > activedebiansync.asc

Client Configuration

The easiest way to configure clients is to use the generated instructions:

curl http://your-server:9090/api/gpg/instructions

This outputs ready-to-run commands.

• Step 1: Import the GPG Key
  Download and convert to binary format
  curl -fsSL http://your-server:9090/api/gpg-key | \
  sudo gpg --dearmor -o /usr/share/keyrings/activedebiansync.gpg
• Step 2: Add Repository with Signed-By
  echo "deb [signed-by=/usr/share/keyrings/activedebiansync.gpg] http://your-server:8080/debian bookworm main" | \
  sudo tee /etc/apt/sources.list.d/activedebiansync.list
• Step 3: Update Package List
  sudo apt update

Verifying the Setup

After configuration, verify GPG is working:

Check for signature verification
apt update 2>&1 | grep -i gpg

# If successful, you should see:
# Get:1 http://your-server:8080/debian bookworm InRelease [X.X kB]

Legacy Method (Not Recommended)

The older method using apt-key is deprecated but still works:

# NOT RECOMMENDED - use signed-by instead

curl -fsSL http://your-server:9090/api/gpg-key | sudo apt-key add -