Skip to content

Comments

feat: add HMAC-SHA256 cryptographic signing for audit log integrity#60

Merged
allisson merged 3 commits intomainfrom
audit-log-integrity
Feb 21, 2026
Merged

feat: add HMAC-SHA256 cryptographic signing for audit log integrity#60
allisson merged 3 commits intomainfrom
audit-log-integrity

Conversation

@allisson
Copy link
Owner

Implements HMAC-SHA256 cryptographic signing for audit logs to detect tampering and meet PCI DSS Requirement 10.2.2. Uses HKDF-SHA256 key derivation to separate encryption and signing key usage, with automatic signing on log creation when KEK chain is available.

Added:

  • Cryptographic audit log signing with HMAC-SHA256 for tamper detection
  • HKDF-SHA256 key derivation to separate encryption and signing keys
  • verify-audit-logs CLI command for batch integrity verification (text/JSON output)
  • Database migration 000003: signature columns (BYTEA), kek_id (UUID FK), is_signed (BOOLEAN)
  • Foreign key constraints: fk_audit_logs_client_id and fk_audit_logs_kek_id prevent orphaned records
  • AuditSigner service for canonical log serialization and HMAC generation
  • Test infrastructure: CreateTestClient() and CreateTestKek() helpers for FK-compliant testing
  • ADR 0011 documenting HMAC-SHA256 signing decision and alternatives

Changed:

  • Audit logs automatically signed on creation when KEK chain available
  • Audit log API responses include signature metadata (signature, kek_id, is_signed)
  • Updated 46 audit log repository tests to comply with FK constraints

Documentation:

  • Added v0.9.0 upgrade guide with pre/post-migration checks
  • Updated CLI commands documentation with verify-audit-logs usage
  • Updated audit logs API documentation with signature field schema
  • Added AGENTS.md guidelines for audit signer architecture and FK testing patterns
  • Updated README with v0.9.0 highlights and cryptographic signing features

Security:

  • Enhanced audit log tamper detection with cryptographic integrity verification
  • Enforced data integrity with FK constraints preventing orphaned client/KEK references
  • Meets PCI DSS Requirement 10.2.2 for audit trail protection

Performance:

  • Signing overhead: ~10-15µs per audit log (negligible)
  • Batch verification: 10,000 logs verified in ~20-30ms

Implements HMAC-SHA256 cryptographic signing for audit logs to detect tampering and meet PCI DSS Requirement 10.2.2. Uses HKDF-SHA256 key derivation to separate encryption and signing key usage, with automatic signing on log creation when KEK chain is available.

Added:
- Cryptographic audit log signing with HMAC-SHA256 for tamper detection
- HKDF-SHA256 key derivation to separate encryption and signing keys
- verify-audit-logs CLI command for batch integrity verification (text/JSON output)
- Database migration 000003: signature columns (BYTEA), kek_id (UUID FK), is_signed (BOOLEAN)
- Foreign key constraints: fk_audit_logs_client_id and fk_audit_logs_kek_id prevent orphaned records
- AuditSigner service for canonical log serialization and HMAC generation
- Test infrastructure: CreateTestClient() and CreateTestKek() helpers for FK-compliant testing
- ADR 0011 documenting HMAC-SHA256 signing decision and alternatives

Changed:
- Audit logs automatically signed on creation when KEK chain available
- Audit log API responses include signature metadata (signature, kek_id, is_signed)
- Updated 46 audit log repository tests to comply with FK constraints

Documentation:
- Added v0.9.0 upgrade guide with pre/post-migration checks
- Updated CLI commands documentation with verify-audit-logs usage
- Updated audit logs API documentation with signature field schema
- Added AGENTS.md guidelines for audit signer architecture and FK testing patterns
- Updated README with v0.9.0 highlights and cryptographic signing features

Security:
- Enhanced audit log tamper detection with cryptographic integrity verification
- Enforced data integrity with FK constraints preventing orphaned client/KEK references
- Meets PCI DSS Requirement 10.2.2 for audit trail protection

Performance:
- Signing overhead: ~10-15µs per audit log (negligible)
- Batch verification: 10,000 logs verified in ~20-30ms
@allisson allisson merged commit 23d48a1 into main Feb 21, 2026
2 checks passed
@allisson allisson deleted the audit-log-integrity branch February 21, 2026 01:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant