nips/xx.md

NIP-X

Key Revocation and Migration

draft optional

This NIP defines a protocol for clients and relays to gracefully recovery from a compromised private key.

At a minimum this includes the revocation of a private key. Clients give warning that the key is compromised. Relays and clients reject future events from a revoked key and may delete existing events.

Also defined is a protocol for a user to be able to remember an associated public key for another user. In the event that a private key of the other user is compromised, the user is able to identity who it was and how to go about recovering from the compromise. This includes an ability to remember the original name, NIP-05 identification, website, migration keys and other associated metadata. Client implementations can provide various strategies to help that recovery, starting as simple as displaying that the key has been compromised.

There are two new events introduced:

• Key Revocation
• User Metadata Attestation

There is one new optional field (migration_pubkeys) for a user's metadata (kind 0):

• Migration Keys

Key Revocation Event

This is a regular event with kind 50. It will revoke a public key (it has been compromised) and stop future events from the key (as determined as after the event was received). It will also provide a means to inform followers of the compromise and suggest a successor public key to follow.

{
  "kind": 50,
  "pubkey": "<user-pubkey>",
  "tags": [
	["successor-key", "<successor-pubkey>"],
	["key-revocation"]
  ],
  "content": "<optional-comment>"
}

• The key-revocation tag MUST be included, once and without a value.
• There MUST NOT be multiple successor-key tags or multiple values.

Event Handling for Clients

For a client, this event is a revocation with a suggestion for a migration to a successor public key. The revocation SHOULD be automatic. The migration, if it is provided, SHOULD NOT be automatic and MAY be presented and verified by the user to accept or reject the migration key change.

Key Revocation

• Upon a valid key revocation:
  • All events SHOULD display a warning that the event is from a revoked public key.
  • A user's profile SHOULD display a warning that the key has been compromised.
  • All events of a revoked public key MAY be deleted, this MAY be after a duration of time depending on the client or preferences.

Key Migration

• If a user has made a prior User Metadata Attestation:
  • The user interface MAY display the original name, NIP-05, migration keys and other user metadata that has been attested.
  • The user interface MAY provide a means to accept or reject a suggested key migration. This can include using NIP-05, migration keys (with matching signatures) and/or a social graph of those the user follows that are now following the suggested successor public key.
• Upon the user accepting a suggested successor key:
  • The predecessor public key SHOULD be unfollowed and the successor public key SHOULD be followed.
  • The predecessor public key SHOULD be added to a mute list.

Event Handling for Relays

For a relay, this event is a key revocation.

Key Revocation

• Upon a valid key revocation:
  • All future events (as determined when it was received) of a revoked public key MUST be rejected, except for another Key Revocation Event. This is to ensure that if a key is compromised and a fraudulent event is made, an honest event can also be made and broadcast.
  • All events of a revoked public key MAY be deleted. The time-frame that events are deleted MAY be defined by an agreed upon terms between client and relay.
• For denial-of-service mitigation, a relay MAY require proof-of-work, a small fee or another solution to continue to write Key Revocation Events. This MAY be determined by the terms agreed upon by the client and relay.

User Metadata Attestation Event

This is a parameterized replaceable event with kind 30050. This is an attestation for another user's metadata (kind 0). This will help a user remember what public key is associated with what display_name, nip05, website and other metadata (should that kind 0 event be compromised in the future). It can also attest to a newly defined migration_pubkeys field that could be useful to be able to identify a user. The attestation can be public or private.

Public:

{
  "kind": 30050,
  "pubkey": "<user-pubkey>",
  "tags": [
	["d", "<pubkey-of-friend>"],
	["p", "<pubkey-of-friend>"],
	["p", "<optional-predecessor-pubkey-of-friend>"],
	["attestations", JSONStringify({
	  "<metadata-key>": "<metadata-value>",
	  "<metadata-key>": "<metadata-value>"
	})]
  ],
  "content": ""
}

Private:

  "kind": 30050,
  "pubkey": "<user-pubkey>",
  "tags": [
	["d", "<encrypted-and-hashed-pubkey"]
  ],
  "content": Nip44Encrypt(JSONStringify([
	["p", "<pubkey-of-friend>"],
	["attestations", JSONStringify({
	  "<metadata-key>": "<metadata-value>",
	  "<metadata-key>": "<metadata-value>"
	})]
  ]))

• For a public attestation:
  • The d tag and a p tag MUST include a public key for the attested to metadata.
  • Another p tag SHOULD be included if there was a predecessor public key. This helps to inform other users of a link between the predecessor public and a successor public key.
  • The attestations tag MUST include JSON stringified copy of the attested to metadata keys and values.
• For a private attestation:
  • The d tag MUST be an encrypted and hashed version of the public key (hex encoding of a sha256 hash of an encrypted, with NIP-44, of the public key).
  • The p, metadata and attestations tags, as the same as the public attestation, MUST be JSON stringified and NIP-44 encrypted in the content field.

Migration Keys

This is a new field on a users metadata (kind 0) event with a key of migration_keys. Its purpose is to define a set of migration keys that can be used to help migrate to a successor key in the future. The event can assign anywhere from 1 to n migration keys. A threshold number of keys (m of n) can be assigned to verify this event.

The value should be as follows:

[<threshold>, <migration-pubkey-1>, <migration-pubkey-2>]

• Clients MAY present a user interface to make an attestation, if this field is available on the metadata.
• Clients MAY use hardware devices and NIP-06 seed phrases to store the migration keys.

Revocation Event Signing

A Key Revocation Event MAY be signed with m of n of these migration keys. This can help assist the migration process for those that have previously attested to the migration_keys.

The following migration-sigs tag MAY be included:

{
	"kind": 50,
	"tags": [
		// other tags
		["migration-sigs", "<index-0-sig", "<index-1-sig>", "<index-2-sig>"]
	]
	// other fields
}