Complete Signing Guide
🔐 Cryptographic Verification & 4-Mode Setup
This guide covers everything you need to know about cryptographic signing in 1-Click GitHub Security - from understanding why it matters to setting up and verifying signatures across all 4 signing modes.
🎯 Why Cryptographic Verification Matters
The Problem: Trust in Software Development
# Anyone can impersonate any developer
git -c user.name="Maintainer" -c user.email="maintainer@project.com" commit -m "Add backdoor"
Traditional solutions: - GPG signing: Complex key management, key compromise risk, private verification - Trust assumptions: "This commit came from who it claims"
Modern solution: Sigstore - Keyless signing: No long-lived keys to manage or compromise - Identity-based: Tied to your verified GitHub/Google/Microsoft account - Certificate transparency: All signatures publicly auditable - Short-lived certificates: 5-10 minute validity prevents long-term key compromise
🏗️ How Sigstore Verification Works
The Complete Flow
Step-by-step:
1. Developer commits - git commit
triggers gitsign
2. Identity verification - Browser opens for GitHub/Google/Microsoft login
3. Certificate issuance - Fulcio CA issues certificate tied to verified identity
4. Signing - Commit signed with ephemeral certificate (valid 5-10 minutes)
5. Transparency logging - Signature automatically logged to public Rekor ledger
6. Verification - Anyone can verify signature against public transparency log
Security Benefits
✅ Identity-verified signatures - No spoofing possible ✅ Public transparency - All signatures auditable via Rekor ✅ Short certificate lifetime - Compromised certs expire quickly ✅ No key management - Certificates issued automatically ✅ Tamper detection - Any modification breaks signature verification
🤔 GPG vs gitsign: Which Should You Choose?
Quick Decision Matrix
Your Priority | Recommended Mode | Why Choose This |
---|---|---|
Maximum Security | gitsign + YubiKey | Short-lived certificates + hardware authentication + transparency logging |
High Security + Ease | gitsign + software | Keyless signing + automatic rotation + no key management |
GitHub UI Badges | GPG + software | Traditional signing with GitHub "Verified" badges |
Hardware + Badges | GPG + YubiKey | Hardware security + GitHub verification display |
Detailed Security Comparison
Feature | gitsign | GPG |
---|---|---|
Certificate Lifetime | 5-10 minutes | 2+ years |
Key Management | Automatic, keyless | Manual, complex |
Key Compromise Risk | Minimal (short-lived) | High (long-lived) |
Identity Verification | OIDC-verified (GitHub/Google) | Self-asserted |
Transparency Logging | Automatic (Rekor) | Optional, manual |
Revocation | Automatic expiration | Manual CRL/OCSP |
Auditability | Public transparency log | Private keyring |
Setup Complexity | Minimal | Complex |
GitHub "Verified" Badge | ❌ No (limitation) | ✅ Yes |
Cryptographic Security | ✅ Superior | ⚠️ Weaker |
GitHub Verification Badge Limitation
Important Security Note:
- gitsign signatures show as "Unverified" on GitHub due to GitHub's current limitations in supporting X.509/Sigstore signatures
- This is a display-only issue - gitsign provides superior cryptographic security compared to traditional GPG
- GitHub will likely add Sigstore support in the future as the ecosystem matures
- Your commits are still cryptographically signed and verifiable using
gitsign verify
command
Security Trade-offs Explained
Why gitsign is More Secure
- Short-lived Certificates: 5-10 minute validity means stolen certificates become useless quickly
- Keyless Design: No long-lived private keys to steal, lose, or compromise
- Automatic Rotation: New certificates issued for each signing session
- Identity Binding: Tied to verified OAuth identity (GitHub, Google, Microsoft)
- Transparency by Default: All signatures automatically logged in public Rekor ledger
- No Key Management: Eliminates human error in key lifecycle management
Why You Might Choose GPG
- GitHub UI Integration: "Verified" badges appear on commits and tags
- Legacy Tool Support: Works with existing GPG-based workflows
- Offline Signing: Can sign without internet connectivity (after key setup)
- Enterprise Policies: Some organizations require traditional PKI
- Team Familiarity: Developers already know GPG workflows
Recommendation Summary
For Security-First Projects:
- Choose gitsign (default option) for superior cryptographic security
- Accept that GitHub shows "Unverified" (display issue, not security issue)
- Use gitsign verify
command for cryptographic verification
For GitHub-UI-First Projects: - Choose GPG if you specifically need GitHub "Verified" badges - Accept the security trade-offs of long-lived keys - Implement strict key management practices
For Maximum Security: - Choose gitsign + YubiKey for hardware-backed authentication - Combine short-lived certificates with hardware security
🔑 4 Signing Modes Complete Setup
The installer supports 4 signing modes combining two signing methods with two authentication types:
Mode Overview
Mode 1: gitsign + software (default - high security): - Short-lived certificates: 5-10 minute validity - Browser authentication: Standard OAuth flow - Transparency logging: All signatures in Rekor - Zero key management: No long-lived keys
Mode 2: gitsign + YubiKey (maximum security): - Short-lived certificates: 5-10 minute validity - Hardware authentication: YubiKey touch required - Phishing resistance: FIDO2/WebAuthn security - Maximum security: Hardware root of trust
Mode 3: GPG + software (GitHub badges): - Traditional GPG: Long-lived keys (2-year expiration) - GitHub verification: "Verified" badges on commits - Software keys: Standard GPG key management - Manual management: Key rotation required
Mode 4: GPG + YubiKey (hardware + badges): - Traditional GPG: Long-lived keys on hardware - GitHub verification: "Verified" badges on commits - Hardware keys: Private keys on YubiKey - Touch requirement: Physical presence for signing
Installation Commands
# Mode 1: gitsign + software (default - high security)
./install-security-controls.sh
# Mode 2: gitsign + YubiKey (maximum security)
./install-security-controls.sh --yubikey
# Mode 3: GPG + software (GitHub badges)
./install-security-controls.sh --signing=gpg
# Mode 4: GPG + YubiKey (hardware + badges)
./install-security-controls.sh --signing=gpg --yubikey
Mode Switching After Installation
# Check current signing mode
./install-security-controls.sh status
# Switch between modes
./install-security-controls.sh switch-to-gitsign
./install-security-controls.sh switch-to-gpg
# Add/remove YubiKey requirement
./install-security-controls.sh enable-yubikey
./install-security-controls.sh disable-yubikey
# Test current configuration
./install-security-controls.sh test
🔧 Setup for Contributors
Prerequisites
- gitsign installed (included in our installer)
- GitHub account with verified email
- Git configured with matching email
Quick Setup
# Install security controls (includes gitsign)
./install-security-controls.sh
# Verify gitsign is configured
git config --get commit.gpgsign # Should return: true
git config --get gpg.format # Should return: x509
git config --get gpg.x509.program # Should return: gitsign
First Signed Commit
# Make a change
echo "Testing signed commits" >> README.md
git add README.md
# Commit (browser will open for authentication)
git commit -m "test: verify gitsign configuration"
# Browser authentication flow:
# 1. GitHub OIDC login screen appears
# 2. Authorize Sigstore access
# 3. Certificate issued and commit signed
# 4. Signature logged to Rekor transparency ledger
Verification Results
# Check signature
git log --show-signature -1
# Example output:
# tlog index: 567315903
# gitsign: Signature made using certificate ID 0xd1cb...
# gitsign: Good signature from [your-email@domain.com]
# Validated Git signature: true
# Validated Rekor entry: true
🔍 Signature Verification
Verify Any Commit
# Verify specific commit
gitsign verify <commit-hash>
# Verify current HEAD
gitsign verify HEAD
# Verify with specific identity
gitsign verify --certificate-identity="expected@email.com" HEAD
What Verification Checks
✅ Certificate validity - Was certificate valid at signing time? ✅ Identity binding - Does signer identity match expected email? ✅ Transparency logging - Is signature recorded in Rekor ledger? ✅ Signature integrity - Has commit been tampered with since signing? ✅ Trust chain - Is certificate issued by trusted Fulcio CA?
Verification Examples
Successful verification:
$ gitsign verify HEAD
tlog index: 567315903
gitsign: Signature made using certificate ID 0xd1cb214b2a12f6732a84d1777720903036dbd739
gitsign: Good signature from [albert@securityronin.com](https://github.com/login/oauth)
Validated Git signature: true
Validated Rekor entry: true
Failed verification (tampered commit):
$ gitsign verify HEAD
Error: signature verification failed
Details: commit content has been modified after signing
Release Verification
# Verify signed tag
git tag -v v0.6.5
# Check release artifacts
gitsign verify --artifact install-security-controls.sh v0.6.5
# Verify against Rekor ledger
rekor-cli search --email albert@securityronin.com
🛠️ Troubleshooting
Common Issues and Solutions
"failed to sign commit"
# Check gitsign configuration
git config --get commit.gpgsign # Should be: true
git config --get gpg.format # Should be: x509
git config --get gpg.x509.program # Should be: gitsign
# Test gitsign directly
gitsign --help
# Re-run installer if misconfigured
./install-security-controls.sh switch-to-gitsign
"browser authentication timeout"
# Increase timeout
git config --global gitsign.autocloseTimeout 60
# Check browser pop-up blocking
# Ensure oauth2.sigstore.dev is not blocked
# Manual authentication
gitsign verify HEAD # Opens browser for auth
"certificate verification failed"
# Certificate may have expired or identity mismatch
gitsign verify --certificate-identity="expected@email.com" HEAD
# Check Rekor entry status
rekor-cli search --email expected@email.com
"rekor entry not found"
# Signature wasn't logged to transparency ledger
# This shouldn't happen with properly configured gitsign
# Check gitsign configuration
git config --get gpg.x509.program # Should be: gitsign
git config --get gpg.format # Should be: x509
Getting Help
- Check configuration:
gitsign --help
and verify setup - Review logs: Look for gitsign error messages during commit
- Test signing: Try signing a test commit to isolate issues
- Community support: Open issue with reproduction steps
🔗 Additional Resources
- Sigstore Documentation - Complete Sigstore ecosystem guide
- gitsign Documentation - Git signing tool details
- Rekor Documentation - Transparency ledger specifics
- Certificate Transparency RFC - Technical specification
🎯 Key Takeaways
✅ Sigstore = Signing + Transparency - They're one integrated security model ✅ Keyless & automatic - No GPG key management complexity ✅ Identity-verified - Tied to your authenticated GitHub account ✅ Publicly auditable - All signatures logged in Rekor transparency ledger ✅ Short-lived certificates - 5-10 minute validity prevents long-term compromise ✅ Supply chain security - End-to-end verification from development to deployment
The bottom line: Every commit and release in this project is cryptographically signed and publicly verifiable. This provides stronger security than traditional GPG with significantly less complexity.
Choose your signing mode based on your security requirements and GitHub UI preferences, then follow the setup instructions above to get started with cryptographically verified commits.