> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/sonic-1.0.0-rc-production-architecture/trust-and-key-rotation.md).

# Trust & Key Rotation

SONIC r30 trust registry and safe cryptographic key rotation for quotes, Sale Release activation, and receipts.

Revision 30 makes cryptographic key identity a first-class runtime contract so production keys can rotate without invalidating active commercial state or exposing secrets to clients.

## Signing surfaces

| Surface                 | Signing model           | Persisted identity                  | Verification               |
| ----------------------- | ----------------------- | ----------------------------------- | -------------------------- |
| Sale quote              | HMAC-SHA256             | `quoteKeyId`                        | server-only secret keyring |
| Sale Release activation | Ed25519 external signer | `activationKeyId`                   | public Ed25519 keyring     |
| Receipt integrity       | Ed25519 external signer | `receiptKeyId` + `receiptAlgorithm` | public Ed25519 keyring     |

## Public trust registry

`GET /api/v1/trust/keys` returns only public verification material:

* key purpose (`SALE_RELEASE` or `RECEIPT`);
* stable key ID;
* algorithm (`Ed25519`);
* SHA-256 SPKI fingerprint;
* public JWK.

It never returns HMAC keys, signer tokens, private keys, legacy HMAC secrets, or environment values.

## Rotation procedure

{% stepper %}
{% step %}

### Stage the new key

Add the new verification key or HMAC key to the deployed keyring before it is used for signing.
{% endstep %}

{% step %}

### Switch the current signer/key ID

Activate the new quote key ID or external Ed25519 signer key.
{% endstep %}

{% step %}

### Verify production health

Check readiness, trust-key fingerprints, newly issued quotes, release signatures, receipt signatures, and worker processing.
{% endstep %}

{% step %}

### Retire safely

Remove an old quote HMAC key only after every quote signed by it has expired. Retain public Ed25519 keys for as long as historical release/receipt verification is required.
{% endstep %}
{% endstepper %}

## Migration contract

`202609110004_r30_key_rotation` adds `SaleQuote.quoteKeyId` and `Receipt.receiptAlgorithm`. Production readiness pins the exact migration chain required by r30.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/sonic-1.0.0-rc-production-architecture/trust-and-key-rotation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.