This document is under active development and has not been finalised.
Skip to content

2.5 Key Management ​

2.5.1 Key Management ​

The secure management of cryptographic keys is essential for the integrity of the signing processes.

2.5.2 Key Types ​

KeyTypeStorage LocationPurpose
Cosign Private KeyEd25519 / ECDSA P-256GitHub SecretsSigning of artifacts
Cosign PasswordPasswordGitHub SecretsProtection of the Private Key
Cosign Public KeyEd25519 / ECDSA P-256Repository (cosign.pub)Verification by users

2.5.3 Key Generation ​

bash
# Generate new key pair
cosign generate-key-pair

# Result:
# cosign.key  → Private Key (password-protected)
# cosign.pub  → Public Key

2.5.4 Key Storage ​

Private Key ​

The Private Key is stored exclusively in GitHub Secrets:

  • Secret Name: COSIGN_PRIVATE_KEY
  • Access: GitHub Actions Workflows only
  • Protection: GitHub Secrets Encryption (Libsodium sealed box)
  • Visibility: Never in logs, never in code

Password ​

  • Secret Name: COSIGN_PASSWORD
  • Access: Only in combination with COSIGN_PRIVATE_KEY

Public Key ​

  • Storage Location: Repository root (cosign.pub)
  • Availability: Public
  • Purpose: Verification by users and systems

2.5.5 Key Rotation ​

TriggerActionDeadline
AnnuallyRoutine rotationEvery 12 months
Suspected compromiseImmediate rotationWithout delay
Personnel changeReview and rotation if necessaryWithin 7 days
Security incidentRotation as part of Incident ResponsePer Playbook

Rotation Process ​

1. Generate new key pair
   └── cosign generate-key-pair

2. Update GitHub Secrets
   ├── COSIGN_PRIVATE_KEY → New Private Key
   └── COSIGN_PASSWORD → New Password

3. Update Public Key in the repository
   └── cosign.pub → New Public Key

4. Archive old Public Key
   └── keys/cosign-<date>.pub.archived

5. Update documentation
   ├── Rotation date
   ├── Key Fingerprint
   └── Reason for rotation

6. Verification
   └── Perform test signing and verification

2.5.6 Emergency Procedure in Case of Key Compromise ​

  1. Immediately: Rotate GitHub Secrets (new key pair)
  2. Within 1h: Identify all releases signed since the compromise
  3. Within 4h: Re-sign affected releases with the new key
  4. Within 24h: Notify users of the key change
  5. Documentation: Document the incident in the Incident Report

2.5.7 Access Permissions ​

RolePrivate KeyPublic KeyKey Rotation
Security LeadManagement (GitHub Secrets)ReadExecution
DevOps LeadNo direct access (only via Workflow)ReadSupport
Development TeamNo accessReadNo access
GitHub ActionsRead (Runtime)ReadNo access

Documentation licensed under CC BY-NC 4.0 · Code licensed under MIT