NIP-102

Hierarchical Deterministic Key Management

draft optional

This NIP defines a way to separate identity from authentication using hierarchical deterministic (HD) keys. This allows people to use one key pair to issue independent key pairs for different apps. If a key is compromised, the root key pair can publish an event revoking that key as of a specific time.

HD keys (BIP-32, BIP-39, BIP-44) provide a means of creating new key pairs from a parent in such a way that the new pubkey can be verified to be a child of the parent's pubkey. A message signed by this new key can be rapidly and locally verified as an authentic subkey of the claimed parent.

NIP-06 declares the default nostr derivation path to be m/44'/1237'/<account>'/0/0.

recovery phrase -> seed -> xpriv
   -> m/44'/1237'/0'     -> Account0
   -> m/44'/1237'/0'/0/0 -> Account0 Subkey0
   -> m/44'/1237'/0'/1/0 -> Account0 Subkey1
   -> m/44'/1237'/0'/2/0 -> Account0 Subkey2

Management Event

The parent key can publish a Kind 10102 event for subkey management. This event lists subkeys that have been revoked, as well as those that are currently active, and a preference for how valid subkeys that are not listed should be treated. This is only a preference, as it may not always be immediately available to clients and relays.

Content:

{
  "keys": {
    "<hex-subkey0-pubkey>": { "active_at": "<epoch-timestamp>" },
    "<hex-subkey1-pubkey>": { "active_at": "<epoch-timestamp>", "revoked_at": "<epoch-timestamp>" },
    "<hex-subkey2-pubkey>": { "active_at": "<epoch-timestamp>" }
  },
  "default_policy": "allow"
}

Signing

When signing events using a subkey, the account pubkey and subkey derivation path will be included as a well known attribute. Relays and clients should validate the subkey->parent relationship, and immediately discard messages with invalid claims.

{
  "pubkey": "<hex-subkey1-pubkey>",
  "kind": 1,
  "tags": [
    ["account", "<hex-account0-pubkey>", "<subkey1-derivation-path>"],
  ],
}

For clients that don't implement NIP-102, we can have the account key publish a Kind 10102 key management event using the subkey at the time of creation:

Content:

{
  "account": "<hex-account0-pubkey>",
  "derivation_path": "<subkey1-derivation-path>"
}

Behavior

All searches for the account pubkey should return those signed by any account subkey. If an event is replaceable, it is up to the client or relay as to whether both messages are maintained, or if only the latest across all subkeys is maintained. In any situation where data will be lost, a reasonable effort should be made to locate the most recent revocation list before proceeding.

Migration

Most current keys do not use BIP-39 derivation and will need to perform a manual key rotation to a new pubkey using a method not defined here.

Reference Code

from bip_utils import Bip39SeedGenerator, Bip32Slip10Secp256k1

account0_derivation_path = "m/44'/1237'/0'"
subkey0_derivation_path = "0/0"

mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
master_xpriv = "xprv9s21ZrQH143K3GJpoapnV8SFfukcVBSfeCficPSGfubmSFDxo1kuHnLisriDvSnRRuL2Qrg5ggqHKNVpxR86QEC8w35uxmGoggxtQTPvfUu"
account0_xpub = "xpub6D6V5EX8HTe95getx2tTH2QApmrA1nPJFEnneAK813RjcDdSc3WaAF7BRNpTF7o7zXjVm3DD3VMX66jhQ7wLaZ9sS6NzyfiwfzqDZbxvpDN"
subkey0_xpub = "xpub6Gf5o5yEF14TykSmvZBzS9wFSgnqvPsxit1v4CaaNf6S6S5mm169FRN3QkCsVsDm8NNaN8eGbQg9vR43BD9UqQTrfWFmRKoWep2gxQpFh3Q"

seed = Bip32Slip10Secp256k1.FromSeed(Bip39SeedGenerator(mnemonic).Generate())
account0 = seed.DerivePath(account0_derivation_path)
subkey0 = account0.DerivePath(subkey0_derivation_path)

def is_subkey(pubkey, subkey, derivation_path):
    parent = Bip32Slip10Secp256k1.FromExtendedKey(pubkey)
    if parent.DerivePath(derivation_path).PublicKey().ToExtended() == subkey:
        return True
    else:
        return False

print(f'subkey0_xpub is child of account0_xpub: {is_subkey(account0_xpub, subkey0_xpub, subkey0_derivation_path)}')

4.0 KiB Raw Blame History