---
slug: keys/rename
version: "0.1"
title: Keys — Rename
summary: A producer changes the identifier a custodian addresses a key by, leaving the key material untouched.
status: draft
targetFrameworkVersion: "0.5.0"
category: key-management
keywords:
  - keys
  - rename
  - identifier
authors:
  - Glenn Gore (https://github.com/stormer78)
parties:
  - role: Producer
    requirement: REQUIRED
    member: issuer
  - role: Key custodian
    requirement: REQUIRED
    member: recipient
proofRequirement:
  requirement: REQUIRED
  rationale: The identifier is what signing requests name, so changing it changes which requests reach this key. That is an authorization-relevant edit and must be attributable.
issuedAtRequirement:
  requirement: REQUIRED
  rationale: Names are how other tasks select a key, so a stale rename repoints a name at a key the operator has already moved it off, and every subsequent signing request follows the name.
sideEffects:
  level: mutating
  rationale: "Changes the stored identifier. The key material and its public half are unchanged."
subjectPath: /keyId
exposure:
  discloses: none
  actsAsSubject: false
errorCodes:
  - code: keys:notFound
    meaning: No key record on this custodian carries the named `keyId`. See [category conventions](../../_shared/0.1/CONVENTIONS.md#1-family-error-codes).
    retryable: false
  - code: keys:alreadyExists
    meaning: A key record already carries the target identifier; the custodian refuses rather than overwrite it. See [category conventions](../../_shared/0.1/CONVENTIONS.md#1-family-error-codes).
    retryable: false
related:
  - keys/show
  - keys/list
  - keys/revoke
---

## Abstract

The **Keys — Rename** Trust Task changes the identifier a *key custodian* addresses a key by. Nothing cryptographic changes: the same private key, the same public half, the same signatures verify afterwards.

What does change is **which requests reach it**. `keyId` is what [`keys/sign`](../../sign/0.1/spec.md) names, so a rename silently redirects every producer still using the old identifier — they will get "no such key", not the key they meant.

## Status of this Document

This is a **draft** *Trust Task specification* per [SPEC.md §5.3](/SPEC.md#53-maturity-levels); the schema **MAY** change without notice. Feedback via the [issue tracker](https://github.com/trustoverip/dtgwg-trust-tasks-tf/issues).

## Conformance

[[RFC2119]](https://www.rfc-editor.org/rfc/rfc2119) and [[RFC8174]](https://www.rfc-editor.org/rfc/rfc8174) key-word conventions apply.

A conforming **producer** **MUST** emit a *Trust Task document* whose `type` is `https://trusttasks.org/spec/keys/rename/0.1`, with itself as `issuer`, the custodian as `recipient`, and both `keyId` and `newKeyId` populated.

A conforming **consumer** (the key custodian) **MUST**:

1. Validate the document per [SPEC.md §7.2](/SPEC.md#72-consumer-requirements).
2. Establish the producer's authority over the key, refusing with `permissionDenied` ([SPEC.md §8.3](/SPEC.md#83-standard-error-codes)) otherwise.
3. Refuse with `keys:notFound` where no record carries `keyId`.
4. Refuse with `keys:alreadyExists` where a record already carries `newKeyId`. A rename **MUST NOT** overwrite another key's record — doing so would silently repoint every signing request naming that identifier at different material.
5. Leave the key material, `publicKey`, `createdAt` and `origin` unchanged, and return the new identifier with the time of the change.

## Authorization

*Stated in anticipation of [SPEC §7.3](/SPEC.md#73-specification-requirements) item 15, which binds specifications targeting framework 0.4; this one targets 0.1, where the declaration is not yet required.*

The authorization evidence this task presupposes is the producer's **authority over the named key**, established by the custodian exactly as for any other operation on that key. Renaming changes no key material and produces no signature, but the label is how every other task addresses the key, so a caller that may not use a key may not relabel it either.

The authorization decision is the *consumer*'s alone. This section describes the evidence the task assumes, not an obligation to authorize any particular party, and per [SPEC §7.2](/SPEC.md#72-consumer-requirements) item 10 verifying the `proof` establishes who asked, never that they may.

## Definitions

* **Producer.** The party renaming; identified by `issuer`.
* **Key custodian.** The party holding the key; identified by `recipient`.

## Request

A *request* document carries `type: https://trusttasks.org/spec/keys/rename/0.1` with a payload that validates against the top-level schema in `payload.schema.json`.

```json
{
  "id": "8293a4b5-c6d7-4e83-f901-122334455667",
  "type": "https://trusttasks.org/spec/keys/rename/0.1",
  "issuer": "did:web:operator.example",
  "recipient": "did:web:custodian.example",
  "issuedAt": "2026-07-31T09:35:00Z",
  "payload": {
    "keyId": "app-signing-key",
    "newKeyId": "app-signing-key-2026"
  }
}
```

## Response

A success *response* document carries `type: https://trusttasks.org/spec/keys/rename/0.1#response`, with a payload that validates against the `$anchor: "response"` sub-schema in `payload.schema.json`.

```json
{
  "id": "93a4b5c6-d7e8-4f94-0112-233445566778",
  "type": "https://trusttasks.org/spec/keys/rename/0.1#response",
  "threadId": "8293a4b5-c6d7-4e83-f901-122334455667",
  "issuer": "did:web:custodian.example",
  "recipient": "did:web:operator.example",
  "issuedAt": "2026-07-31T09:35:01Z",
  "payload": {
    "keyId": "app-signing-key-2026",
    "updatedAt": "2026-07-31T09:35:01Z"
  }
}
```

Failures (`permissionDenied`, `keys:notFound`, `keys:alreadyExists`) use `trust-task-error` ([SPEC.md §8](/SPEC.md#8-error-responses)), not the `#response` variant.

## Security & Privacy

A rename is cryptographically inert and operationally sharp. Every producer configured with the old identifier breaks at its next signing request, and breaks by *failing*, which is the safe direction — but a custodian that resolved the old name to the renamed key "helpfully" would turn a rename into an alias, and an alias into an ambiguity about which key a request meant.

Refusing a colliding `newKeyId` matters for the same reason in reverse: allowing the collision would repoint requests at material the producer never named.
