> For the complete documentation index, see [llms.txt](https://docs.openg2p.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openg2p.org/products/open-agri-stack/administration/keys.md).

# Keys

Replacing and rotating signing keys.

Three kinds of signing key, each changed where it lives:

| Key                                  | Signs                                                               | Who trusts it, and how they get it                                                                                                                                                                                             |
| ------------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Composite signing key                | The Composite's calls to the registries and its answers to partners | Each department's Partner Management reads it from the Composite's JWKS URL when needed; partners read it there too ([how](https://docs.openg2p.org/products/open-agri-stack/architecture/exchange.md#composite-as-a-partner)) |
| Exchange Consent Manager signing key | The consent tokens the Exchange CM issues for the registries        | Each department's Consent Manager reads it from the Exchange CM's JWKS URL                                                                                                                                                     |
| Partner signing key                  | The partner's requests and the consents it signs                    | The Exchange's Partner Management holds it, from the partner's onboarding                                                                                                                                                      |

Nobody enters the Composite signing key or the Exchange CM signing key anywhere: changing it where it lives is enough.

## Composite signing key

The install generates it (Secret `agri-composite-signing`, kept on upgrades and uninstall) unless a Secret with your own key existed first.

### Rotate the generated key

1. Delete the Secret: `kubectl -n <Exchange namespace> delete secret agri-composite-signing`.
2. Upgrade the Composite release in Rancher with the same values: the chart generates a new key and `kid`.
3. Restart the Composite: `kubectl -n <Exchange namespace> rollout restart deploy/agri-composite-api`.
4. **Check:** `curl -s https://agri-composite.<Exchange domain>/.well-known/jwks.json` shows the new `kid`.

The Partner Managements pick the new key up within their cache time (5 minutes); until then a registry may refuse the Composite's calls. Rotate at a quiet time.

### Use your own key

For a key generated where your organisation keeps its keys (an EC P-256, RSA or Ed25519 key in a password-protected `.p12`):

```bash
kubectl -n <Exchange namespace> delete secret agri-composite-signing --ignore-not-found
kubectl -n <Exchange namespace> create secret generic agri-composite-signing \
  --from-file=composite.p12=./composite.p12 --from-literal=password='<p12 password>' \
  --from-literal=kid=<kid> --from-literal=algorithm=auto
kubectl -n <Exchange namespace> rollout restart deploy/agri-composite-api
```

The chart leaves a Secret it did not create alone, and a `.p12` is used before a generated key. To rotate it, repeat with the new `.p12` and a new `kid`. Before a first install, create the Secret first and the chart never generates one. Settings: [Composite chart settings: signing key](https://docs.openg2p.org/products/open-agri-stack/deployment/exchange/composite-chart-settings.md#signing-key).

### An older install

An install from before the generated key holds the Composite signing key's public key in each Partner Management itself (onboarded by the former setup script). There, rotating also needs, in **every** Partner Management, a key-update request on `PARTNER_AGRI_COMPOSITE` adding the new public key and `kid` (from the JWKS URL above), approved; then revoke the old `kid` after 5 minutes.

## Exchange Consent Manager signing key

1. Create a Secret with the new `.p12` ([Production: the CM signing key](https://docs.openg2p.org/products/open-agri-stack/deployment/production.md#exchange-consent-manager-signing-key)).
2. In Commons Services of the Exchange: **Signing Key Secret** the new Secret, a new **Signing Key ID**; upgrade.

The departments read the new key from the Exchange CM's JWKS URL. Consent tokens signed with the old key lapse within their lifetime (5 minutes).

## Partner signing key

The partner sends its new public key and `kid`. In the Exchange's Partner Management, on the partner: **Rotate / add keys** with the new key (a key-update request), approve. Old and new keys both work until the old `kid` is revoked: revoke it (**Rotate / add keys**, tick the old key) once the partner has switched. Partner's side: [Partner Guide: Fetching Farmer Data](https://docs.openg2p.org/products/open-agri-stack/partner-integration-guide.md#step-2-get-onboarded-in-partner-management).

## A compromised key

| Key                     | At once                                                                                                                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Composite signing key   | Rotate it as above. An older install: also revoke the old `kid` in every Partner Management                                                                                                                                            |
| Exchange CM signing key | Rotate it as above; tokens signed with it lapse within 5 minutes                                                                                                                                                                       |
| Partner signing key     | Revoke its `kid` in the Exchange's Partner Management (or **Disable** the partner: [Managing Partners](https://docs.openg2p.org/products/open-agri-stack/administration/managing-partners.md#disable-a-partner)), then add its new key |


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openg2p.org/products/open-agri-stack/administration/keys.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
