Skip to content

Signing Key Lifecycle (v1)

Purpose

Define how DiffVer manages tenant-scoped artifact signing metadata across generation, storage, rotation, and verification.

Current implementation scope: - Signature modes: deterministic, kms-hmac, and aws-kms over artifact checksum. - Tenant signing configuration is API-managed and persisted. - Artifact integrity can be verified via API (checksum + signature validation).

Data Model

Signing config fields (per tenant): - tenant_id - active_key_id - key_version (integer, >= 1) - algorithm (sha256) - created_at - updated_at

Artifact signature fields: - algorithm - key_id - key_version - signed_at - value

Lifecycle Stages

1) Key Registration

Register or update active signing metadata for a tenant.

Endpoint: - PUT /v1/keys/signing-config

Example request:

{
  "tenant_id": "t_1",
  "active_key_id": "kms://prod/diffver/t_1/signing",
  "key_version": 1,
  "algorithm": "sha256"
}

Read current active config: - GET /v1/keys/signing-config?tenant_id=t_1

Audit trail: - signing_config.upserted is recorded in GET /v1/audit-events.

2) Artifact Signing During Scan Finalization

When scan processing completes (or errors), DiffVer builds an artifact and adds: - checksum: sha256 hash of canonical artifact payload. - signature: mode-specific value derived from tenant signing config metadata and checksum.

Behavior notes: - Signature metadata is bound to the config active at sign time. - Artifact includes retention metadata (full vs artifact_only).

3) Key Rotation

Rotation is performed by updating signing config: - keep active_key_id and increment key_version, or - switch active_key_id and set new key_version.

Example rotation request:

{
  "tenant_id": "t_1",
  "active_key_id": "kms://prod/diffver/t_1/signing",
  "key_version": 2,
  "algorithm": "sha256"
}

Expected outcome: - New artifacts are signed with new key_id/key_version. - Existing artifacts remain verifiable against embedded signature metadata. - Rotation event is auditable via signing_config.upserted.

4) Artifact Verification

Endpoint: - POST /v1/artifacts/verify

Request body:

{
  "artifact": { "...": "artifact document" }
}

Response fields: - valid - checksum_valid - signature_valid - reason

Verification checks: - Recompute canonical checksum and compare with artifact checksum. - Recompute expected signature from artifact metadata (tenant_id, key_id, key_version, algorithm, mode) and checksum. - Return combined validity plus failure reason on mismatch.

Operational Guidance

  • Use tenant-scoped key IDs that map to your KMS naming convention.
  • Rotate key version on a fixed cadence (for example, quarterly) or after security events.
  • Alert on repeated signature_valid=false responses and investigate tampering or config drift.
  • Monitor signing_config.upserted audit events for unauthorized changes.

Known v1 Limitations

  • sha256 is the only supported algorithm.
  • aws-kms mode currently targets KMS HMAC GenerateMac workflows.
  • Key state lifecycle (disabled, revoked, retired) is not modeled separately from active config.

v2 Roadmap

  • Add asymmetric KMS signing and verification support.
  • Add key status model (active, retiring, retired) and overlap windows.
  • Add verification policy controls (for example, fail if key version below minimum allowed).
  • Add signed artifact attestations compatible with external provenance systems.