# NimPak Key Revocation and Rollover Policy

## Overview

This document defines the comprehensive key revocation and rollover policy for NimPak's cryptographic infrastructure. Given the critical nature of package integrity and the evolving threat landscape (including quantum computing), this policy ensures rapid response to key compromise while maintaining system availability and security.

## 1. Key Lifecycle Management

### 1.1 Key States

Keys in the NimPak ecosystem have the following states:

- **Active**: Currently valid for signing and verification
- **Deprecated**: Still valid but scheduled for replacement
- **Revoked**: Immediately invalid, blacklisted
- **Expired**: Naturally expired based on validity period
- **Superseded**: Replaced by newer key, grace period may apply

### 1.2 Key Types and Validity Periods

| Key Type | Algorithm | Validity Period | Rollover Schedule |
|----------|-----------|-----------------|-------------------|
| Repository Signing | Ed25519 | 2 years | Every 18 months |
| Package Signing | Ed25519 | 1 year | Every 9 months |
| Emergency Response | Ed25519 | 6 months | As needed |
| Post-Quantum (Future) | Dilithium | 2 years | Every 18 months |

## 2. Revocation Procedures

### 2.1 Emergency Revocation (Immediate Response)

**Trigger Conditions:**
- Key compromise confirmed or suspected
- Private key exposure
- Signing infrastructure breach
- Malicious package signatures detected

**Response Timeline:**
- **T+0 minutes**: Incident detection and confirmation
- **T+15 minutes**: Emergency revocation initiated
- **T+30 minutes**: Revocation broadcast to all repositories
- **T+1 hour**: Client-side revocation list updates
- **T+24 hours**: Full ecosystem propagation verification

**Implementation:**
```bash
# Emergency revocation command
nip key revoke --emergency --key-id=<key-id> --reason="compromise" \
  --broadcast --force-update

# Immediate CRL distribution
nip admin crl-push --emergency --all-repositories
```

### 2.2 Scheduled Revocation (Planned Replacement)

**Process:**
1. **T-30 days**: New key generation and testing
2. **T-14 days**: Deprecation notice and new key distribution
3. **T-7 days**: Final migration warnings
4. **T-0**: Old key revocation, new key activation
5. **T+7 days**: Grace period ends, old signatures rejected

### 2.3 Revocation Reasons and Codes

| Code | Reason | Description | Response Level |
|------|--------|-------------|----------------|
| 0 | Unspecified | Generic revocation | Standard |
| 1 | Key Compromise | Private key exposed | Emergency |
| 2 | CA Compromise | Certificate Authority breach | Critical |
| 3 | Affiliation Changed | Key holder role change | Standard |
| 4 | Superseded | Replaced by newer key | Standard |
| 5 | Cessation of Operation | Service discontinued | Standard |
| 6 | Certificate Hold | Temporary suspension | Standard |
| 9 | Privilege Withdrawn | Access revoked | Emergency |

## 3. Key Rollover Procedures

### 3.1 Automated Rollover Process

**Pre-Rollover Phase (T-30 days):**
```bash
# Generate new key pair
nip key generate --algorithm=ed25519 --purpose=repository-signing \
  --validity=2y --output=/secure/new-key.pem

# Test new key with sample packages
nip sign --key=/secure/new-key.pem --test-mode sample-package.npk

# Validate key strength and compliance
nip key validate --key=/secure/new-key.pem --policy=strict
```

**Overlap Phase (T-14 to T+7 days):**
```bash
# Distribute new public key
nip key distribute --key-id=<new-key-id> --repositories=all \
  --metadata="rollover-from=<old-key-id>"

# Enable dual validation
nip config set validation.allow-multiple-keys=true
nip config set validation.overlap-period=21d
```

**Activation Phase (T-0):**
```bash
# Activate new key
nip key activate --key-id=<new-key-id> --primary

# Deprecate old key
nip key deprecate --key-id=<old-key-id> --grace-period=7d
```

**Cleanup Phase (T+7 days):**
```bash
# Revoke old key
nip key revoke --key-id=<old-key-id> --reason="superseded"

# Update repository metadata
nip admin update-keyring --remove=<old-key-id> --all-repositories
```

### 3.2 Emergency Rollover (Compromise Response)

**Immediate Actions (T+0 to T+1 hour):**
1. Revoke compromised key immediately
2. Generate emergency replacement key
3. Sign critical security updates with emergency key
4. Broadcast emergency key to all clients

**Recovery Actions (T+1 hour to T+24 hours):**
1. Investigate compromise scope and impact
2. Generate permanent replacement keys
3. Re-sign affected packages with new keys
4. Update all repository metadata

**Validation Actions (T+24 hours to T+7 days):**
1. Verify all clients received updates
2. Monitor for malicious signatures using old keys
3. Audit all packages signed during compromise window
4. Generate incident report and lessons learned

## 4. Quantum-Resistant Transition

### 4.1 Hybrid Signature Period

During the transition to post-quantum cryptography, NimPak will support hybrid signatures:

```bash
# Generate hybrid key pair (classical + PQ)
nip key generate --algorithm=hybrid --classical=ed25519 --pq=dilithium \
  --purpose=future-proof

# Sign with both algorithms
nip sign --hybrid --package=example.npk --output=example.npk.sig

# Verify with algorithm preference
nip verify --prefer-pq --fallback-classical example.npk
```

### 4.2 Migration Timeline

| Phase | Duration | Actions |
|-------|----------|---------|
| Preparation | 6 months | PQ algorithm implementation and testing |
| Hybrid Period | 12 months | Dual signatures (classical + PQ) |
| Transition | 6 months | Gradual migration to PQ-only |
| PQ-Only | Ongoing | Classical algorithms deprecated |

### 4.3 Algorithm Deprecation Schedule

```bash
# Set deprecation warnings
nip config set crypto.deprecation.ed25519.warn-after="2030-01-01"
nip config set crypto.deprecation.ed25519.disable-after="2032-01-01"

# Enable quantum-resistant algorithms
nip config set crypto.enable.dilithium=true
nip config set crypto.enable.sphincs=true  # Backup PQ algorithm
```

## 5. Revocation List Management

### 5.1 Certificate/Key Revocation List (CRL/KRL) Format

NimPak uses a custom KDL-based revocation list format:

```kdl
revocation_list {
  version "1.0"
  issuer "nexusos-repository-ca"
  this_update "2025-08-05T14:30:00Z"
  next_update "2025-08-06T14:30:00Z"

  revoked_key {
    key_id "ed25519-abc123def456"
    revocation_date "2025-08-05T10:15:00Z"
    reason_code 1  // Key compromise
    reason_text "Private key exposure detected"
    serial_number "12345"
  }

  revoked_key {
    key_id "ed25519-789abc012def"
    revocation_date "2025-08-04T16:20:00Z"
    reason_code 4  // Superseded
    reason_text "Scheduled key rollover"
    superseded_by "ed25519-new456789abc"
  }

  signature {
    algorithm "ed25519"
    key_id "nexusos-crl-signing-key"
    value "base64-encoded-signature"
  }
}
```

### 5.2 CRL Distribution and Caching

```bash
# Automatic CRL fetching
nip crl update --auto --interval=1h

# Manual CRL verification
nip crl verify --crl-url=https://crl.nexusos.org/repository.crl

# Offline CRL for air-gapped systems
nip crl export --offline --output=offline-crl.kdl
```

### 5.3 CRL Validation During Package Verification

```nim
# Pseudo-code for CRL integration
proc verifyPackageSignature(package: Package, signature: Signature): bool =
  # 1. Verify signature cryptographically
  if not cryptoVerify(package, signature):
    return false

  # 2. Check key revocation status
  let crl = getCurrentCRL()
  if crl.isRevoked(signature.keyId):
    logSecurityEvent("signature_verification_failed", %*{
      "package": package.name,
      "key_id": signature.keyId,
      "reason": "key_revoked",
      "revocation_date": crl.getRevocationDate(signature.keyId)
    })
    return false

  # 3. Check key expiration
  if signature.isExpired():
    return false

  return true
```

## 6. Security Event Logging

### 6.1 Revocation Events

All key lifecycle events are logged in the tamper-evident security log:

```json
{
  "timestamp": "2025-08-05T14:30:00Z",
  "event_type": "key_revocation",
  "severity": "critical",
  "key_id": "ed25519-abc123def456",
  "reason_code": 1,
  "reason_text": "Private key exposure detected",
  "initiated_by": "security-team",
  "affected_packages": ["htop-3.2.2", "vim-9.0.2"],
  "response_actions": [
    "emergency_crl_update",
    "package_re_signing",
    "client_notification"
  ],
  "hash_chain_prev": "blake3-previous-event-hash",
  "hash_chain_current": "blake3-current-event-hash"
}
```

### 6.2 Rollover Events

```json
{
  "timestamp": "2025-08-05T14:30:00Z",
  "event_type": "key_rollover",
  "severity": "info",
  "old_key_id": "ed25519-old123456",
  "new_key_id": "ed25519-new789abc",
  "rollover_type": "scheduled",
  "overlap_period": "7d",
  "affected_repositories": ["stable", "testing"],
  "validation_results": {
    "packages_re_signed": 1247,
    "client_updates": 98.7,
    "errors": []
  }
}
```

## 7. Client-Side Implementation

### 7.1 Automatic Revocation Checking

```bash
# Enable automatic revocation checking
nip config set security.check-revocation=true
nip config set security.crl-update-interval=1h
nip config set security.fail-on-revocation-unavailable=false

# Manual revocation check
nip verify --check-revocation package.npk
```

### 7.2 Grace Period Handling

```bash
# Configure grace periods for different scenarios
nip config set security.grace-period.scheduled-rollover=7d
nip config set security.grace-period.emergency-revocation=0d
nip config set security.grace-period.key-expiration=1d
```

## 8. Monitoring and Alerting

### 8.1 Key Health Monitoring

```bash
# Monitor key health across ecosystem
nip admin key-health --all-repositories --alert-threshold=30d

# Generate key expiration report
nip admin key-report --expiring-within=60d --format=json
```

### 8.2 Revocation Propagation Monitoring

```bash
# Monitor CRL propagation
nip admin crl-status --all-clients --timeout=1h

# Alert on failed revocation propagation
nip admin alert --condition="crl-propagation-failed" \
  --action="escalate-to-security-team"
```

## 9. Incident Response Procedures

### 9.1 Key Compromise Response Checklist

- [ ] **Immediate (0-15 minutes)**
  - [ ] Confirm compromise scope and impact
  - [ ] Initiate emergency revocation
  - [ ] Notify security team and stakeholders
  - [ ] Begin forensic data collection

- [ ] **Short-term (15 minutes - 1 hour)**
  - [ ] Broadcast revocation to all repositories
  - [ ] Generate emergency replacement keys
  - [ ] Update critical security packages
  - [ ] Monitor for malicious activity

- [ ] **Medium-term (1-24 hours)**
  - [ ] Complete forensic investigation
  - [ ] Re-sign affected packages
  - [ ] Verify client-side updates
  - [ ] Generate incident report

- [ ] **Long-term (24+ hours)**
  - [ ] Implement preventive measures
  - [ ] Update security procedures
  - [ ] Conduct lessons learned session
  - [ ] Plan infrastructure improvements

### 9.2 Communication Templates

**Emergency Revocation Notice:**
```
SECURITY ALERT: Emergency Key Revocation

Key ID: ed25519-abc123def456
Revocation Time: 2025-08-05 14:30:00 UTC
Reason: Private key compromise suspected
Impact: Packages signed after 2025-08-04 12:00:00 UTC

IMMEDIATE ACTIONS REQUIRED:
1. Update your NimPak client: nip update --security
2. Refresh revocation lists: nip crl update --force
3. Verify installed packages: nip verify --all --strict

For questions: security@nexusos.org
Incident ID: INC-2025-0805-001
```

## 10. Testing and Validation

### 10.1 Revocation Testing

```bash
# Test emergency revocation procedure
nip test revocation --scenario=emergency --key-id=test-key-123

# Test rollover procedure
nip test rollover --scenario=scheduled --dry-run

# Test CRL propagation
nip test crl-propagation --all-clients --timeout=30m
```

### 10.2 Disaster Recovery Testing

```bash
# Test complete key infrastructure recovery
nip test disaster-recovery --scenario=ca-compromise --restore-from-backup

# Test offline revocation capability
nip test offline-revocation --air-gapped-mode
```

## 11. Compliance and Auditing

### 11.1 Audit Requirements

- All key lifecycle events must be logged immutably
- Revocation decisions must be documented with justification
- Response times must meet defined SLAs
- Regular security assessments of key infrastructure

### 11.2 Compliance Reporting

```bash
# Generate compliance report
nip admin compliance-report --period=quarterly \
  --include=revocations,rollovers,incidents \
  --format=pdf --output=q3-2025-compliance.pdf
```

---

**Document Version:** 1.0
**Last Updated:** 2025-08-05
**Next Review:** 2025-11-05
**Owner:** NexusOS Security Team
**Approved By:** Chief Security Officer