# Issuer and key security

**Design guidance.** These are proposed arrangements and security expectations for participants. They are not a description of a Realworld custody service or a statement that a deployment already meets them. Product availability and assessed controls need separate [assurance and release information](assurance-and-release.md).

An issuer authorises a statement and causes it to be signed. Key custody, permission to sign and recognition of the issuer are separate responsibilities. A trust framework may bind an organisation, a public key and an authority scope. That does not mean it supplies or holds the issuer's private key. Any custody arrangement needs its own named operator and agreement.

## Possible issuing arrangements

- **Managed professional portal**: Key custody: A named custody provider under an explicit arrangement. Approval responsibility: An authorised person or approved issuance policy for the issuer.
- **Vendor integration**: Key custody: The issuer's or vendor's designated key store. Approval responsibility: A documented link between the vendor workflow, issuer and approved content.
- **Institutional deployment**: Key custody: The institution's controlled environment. Approval responsibility: The institution's authorised people and policies.
- **Agent-assisted preparation**: Key custody: Inherits one of the arrangements above. Approval responsibility: Approval remains outside the language model.

These options do not establish an integration with any vendor. Synthetic demonstrations need a separate test context and must not acquire production authority merely because their signatures can be checked.

## Approve the content that will be signed

The proposed workflow separates preparation, approval and signing:

```mermaid
flowchart TB
  P["Portal or vendor workflow"] --> D["Prepared record"]
  M["Optional drafting assistant"] --> D
  D --> V["Validate and display exact content"]
  V --> A["Issuer approval or approved policy"]
  A --> S["Authorised signing operation"]
  S --> C["Credential and issuance record"]

  click P href "#possible-issuing-arrangements"
  click M href "integration-profiles.html#agent-and-mcp-boundaries"
  click S href "#key-lifecycle"
  click C href "verifier-behaviour.html#a-result-with-separate-checks"

  class P,D,V,A,S,C rwOutline
  class M rwMuted
  class P,M,D,V,A,S,C rwEven
```

This is a reference workflow, not a deployed-system diagram. Approval should bind the issuer, asset, engagement, claims, document references, profile version and intended operation. The signing service should independently enforce that approval, refuse changes made afterwards and apply a defined retry policy. Automated batches need an approved scope, limits and a responsible owner.

A language model may help prepare a record. Its output or chat confirmation is not signing authority. The proposed agent-assisted model gives the assistant no general operation for signing arbitrary content and no access to private keys. Approval and signing permissions remain enforced outside the model.

## Public verification material and secrets

- **Public verification key, public-only JWK set or certificate**: May be published with its purpose, version and authenticated issuer binding. Publication alone does not establish trust.
- **Key identifier (`kid`)**: Identifies a key; it is neither signing permission nor proof of issuer authority.
- **Private key, seed, recovery share or symmetric secret**: Keep within the approved custody arrangement. Never place it in documentation, repositories, prompts, tool arguments, support tickets or logs.
- **Access token, refresh token, client secret or session credential**: Treat as access credentials, not public verification material.
- **Document digest or status information**: Assess privacy and disclosure needs before publishing; a digest is not automatically anonymous.

A published JWK set must contain only the public parameters allowed for its key type. Verification of a credential does not require the issuer's private signing key. Algorithms and wire formats belong to the versioned [SD-JWT VC binding](../shared/sd-jwt-vc-binding.md), not an arbitrary choice by a caller.

For example, public EC keys use `crv`, `x` and `y`; public RSA keys use `n` and `e`; public OKP keys use `crv` and `x`, alongside their key type and permitted metadata. Private members such as `d`, `p`, `q`, `dp`, `dq`, `qi` and symmetric `k` must not appear in a public verification-key set. Listing a key type here does not add it to an accepted credential profile.

Explicitly labelled synthetic test keys may be reproducible so an example can be checked. Treat them as publicly known, keep them separate from operational keys, and never register them as trusted production issuers. Their publication does not make the same handling appropriate for a real signing secret.

## Key lifecycle

Each arrangement should state how keys are generated, authorised for use, activated, backed up, rotated, retired and handled after compromise. Recovery and staff changes must not bypass issuer identification or signing approval. Credential signing, trust-list signing, status publication, service access and software releases have distinct purposes and should use separate keys and permissions.

Stopping a key, withdrawing an issuer's authority, revoking one credential and losing access to a status source are different events. Rotation alone does not invalidate every earlier signature. An issuer's own timestamp does not independently prove that a signature predates a compromise; any historical acceptance policy needs an appropriate evidence basis.

Protected key storage addresses key extraction, but approval controls and the integrity of issuer-to-key bindings still matter. The [responsibility model](trust-and-responsibilities.md) explains what remains with each participant. See [Reporting security issues](reporting-security-issues.md) for reporting guidance.

Candidate production arrangements should evaluate non-exportable keys in an HSM, KMS or an equivalent protected signer. That design choice still needs operator, recovery and access-control evidence. A protected device can sign an improperly authorised instruction; it does not replace exact-content approval or independent administration of trust records.
