Define who can create a trusted receipt
HMAC uses one shared secret for authentication and verification. A verifier with that secret can also create a valid receipt, so distribute it only to systems that should have that capability. A public download verifier should not receive the organization’s HMAC key; use an appropriate public-verification mechanism for that different requirement.
For a small team, a protected CI release job can create receipts while an authorized deployment job verifies them. Review who can edit those jobs, read their secret store or access retained logs. Restricting a filename is not enough if every project job receives the same secret automatically.
Generate and store the key deliberately
CloneGuard keygen creates a 32-byte key file and refuses to overwrite an existing output. Use a private location outside source control and delivered artifacts. In CI, materialize the secret only for the job that needs it, set appropriate local permissions and remove the temporary file during teardown.
Never paste a key into an issue, benchmark record, command transcript or public configuration. Public receipts may contain file paths and inventories that also deserve review before publication. Keeping the key private does not automatically make every field of an authenticated receipt suitable for a public audience.
Rotate with an explicit historical mapping
The current receipt format does not provide an automatic organization-wide rotation service. Maintain an external mapping from release series to the key identifier held in your secret-management system. When rotating, generate a new key, update the authorized release path and run an intact/failure verification test before using it for production.
Retain access to old verification keys according to your retention policy, or deliberately retire those verification capabilities with documentation. Re-signing an old inventory with a new key creates a new authentication event; it should not be described as an unchanged historical receipt. Preserve the original record when reproducibility matters.
Exercise the exposure response
If a key is exposed, stop using it for new trusted receipts and review what artifacts or receipts could have been replaced. Generate a replacement key and distribute it through the controlled secret store. A new key does not retroactively make previously authenticated records trustworthy if their provenance is uncertain.
Document the incident window, affected releases and known-good backups. Verify selected retained artifacts against trusted historical records and native signatures where applicable. For independent origin or time claims, bring in the organization’s signing and provenance process rather than stretching HMAC beyond shared-key authentication.
Practical checklist
- Assign key creation and verification owners.
- Keep secrets out of releases and logs.
- Map releases to managed key identifiers.
- Test rotation before accepting new production receipts.
Sources and further reading
Primary references support the technical details. Procedures here are guidance; only explicitly recorded project results describe tests we ran.
Prepared with AI assistance. How this library is produced. Suggest a correction; keep private code and credentials out of public issues.