​

Sparkle Key Management Guide

​

Overview

• A private key (kept secret) for signing updates
• A public key (distributed with the app) for verifying signatures

​

Key Locations

​

Public Key

• Location: VibeTunnel/sparkle-public-ed-key.txt
• Status: Committed to repository
• Usage: Embedded in app via SUPublicEDKey in Info.plist
• Current Value: AGCY8w5vHirVfGGDGc8Szc5iuOqupZSh9pMj/Qs67XI=

​

Private Key

• Location: private/sparkle_private_key
• Status: NOT in version control (in .gitignore)
• Usage: Required for signing updates during release
• Format: Base64-encoded key data (no comments or headers)

​

Initial Setup

​

For New Team Members

1. Request Access
   Copy

   # Contact team lead for secure key transfer
   # Keys are stored in: Dropbox/Backup/Sparkle-VibeTunnel/
   

2. Install Private Key
   Copy

   # Create private directory
   mkdir -p private
   
   # Add key file (get content from secure backup)
   echo "BASE64_PRIVATE_KEY_HERE" > private/sparkle_private_key
   
   # Verify it's ignored by git
   git status  # Should not show private/
   

3. Verify Setup
   Copy

   # Test signing with your key
   ./build/SourcePackages/artifacts/sparkle/Sparkle/bin/sign_update \
     any_file.dmg \
     -f private/sparkle_private_key
   

​

For New Projects

1. Generate New Keys
   Copy

   # Build Sparkle tools first
   ./scripts/build.sh
   
   # Generate new key pair
   ./build/SourcePackages/artifacts/sparkle/Sparkle/bin/generate_keys
   

2. Save Keys
   Copy

   # Copy displayed keys:
   # Private key: [base64 string]
   # Public key: [base64 string]
   
   # Save private key
   mkdir -p private
   echo "PRIVATE_KEY_BASE64" > private/sparkle_private_key
   
   # Save public key
   echo "PUBLIC_KEY_BASE64" > VibeTunnel/sparkle-public-ed-key.txt
   

3. Update App Configuration
   • Add public key to Info.plist under SUPublicEDKey
   • Commit public key file to repository

​

Key Security

​

Best Practices

1. Never Commit Private Keys
   • Private directory is in .gitignore
   • Double-check before committing
2. Secure Backup
   • Store in encrypted location
   • Use password manager or secure cloud storage
   • Keep multiple secure backups
3. Limited Access
   • Only release managers need private key
   • Use secure channels for key transfer
   • Rotate keys if compromised
4. Key Format
   • Private key file must contain ONLY the base64 key
   • No comments, headers, or extra whitespace
   • Single line of base64 data

​

Example Private Key Format

SMYPxE98bJ5iLdHTLHTqGKZNFcZLgrT5Hyjh79h3TaU=

​

Troubleshooting

​

”EdDSA signature does not match” Error

1. Verify private key matches public key
2. Check key file has no extra characters
3. Regenerate appcast with correct key

​

”Failed to decode base64 encoded key data”

# Extract just the key
grep -v '^#' your_key_backup.txt | grep -v '^$' > private/sparkle_private_key

​

Testing Key Pair Match

# Sign a test file
echo "test" > test.txt
./build/SourcePackages/artifacts/sparkle/Sparkle/bin/sign_update \
  test.txt \
  -f private/sparkle_private_key

# The signature should generate successfully
# Compare with production signatures to verify

​

Key Rotation

1. Generate New Keys
   Copy

   ./build/SourcePackages/artifacts/sparkle/Sparkle/bin/generate_keys
   

2. Update App
   • Change SUPublicEDKey in Info.plist
   • Update sparkle-public-ed-key.txt
   • Release new version with new public key
3. Transition Period
   • Keep old private key for emergency updates
   • Sign new updates with new key
   • After all users update, retire old key

​

Integration with Release Process

1. generate-appcast.sh
   • Expects key at private/sparkle_private_key
   • Fails if key missing or invalid
   • Signs all DMG files in releases
2. release.sh
   • Calls generate-appcast.sh after creating DMG
   • Ensures signatures are created before pushing

​

Recovery Procedures

​

Lost Private Key

1. Generate new key pair
2. Update app with new public key
3. Release update signed with old key (if possible)
4. All future updates use new key

​

Compromised Private Key

1. Generate new key pair immediately
2. Release security update with new public key
3. Notify users of security update
4. Revoke compromised key (document publicly)

​

Verification Commands

​

Verify Current Setup

# Check public key in app
/usr/libexec/PlistBuddy -c "Print :SUPublicEDKey" \
  build/Build/Products/Release/VibeTunnel.app/Contents/Info.plist

# Check private key exists
ls -la private/sparkle_private_key

# Test signing
./scripts/generate-appcast.sh --dry-run

​

Verify Release Signatures

# Check signature in appcast
grep "sparkle:edSignature" appcast-prerelease.xml

# Manually verify a DMG
./build/SourcePackages/artifacts/sparkle/Sparkle/bin/sign_update \
  build/VibeTunnel-1.0.0.dmg \
  -f private/sparkle_private_key

​

Additional Resources

• Sparkle Documentation
• EdDSA on Wikipedia
• Ed25519 Key Security