Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
120 lines (83 sloc) 4.07 KB

NIP 9 - New Persistent Delegation Request Transaction

    NIP: 9
    Layer: Core
    Title: New Persistent Delegation Request Transaction
    Author: gimre <>
    Status: Active
    Type: Standards Track
    Created: 2020-01-24
    License: MIT


Pentesting team has identified potential issues in persistent delegation request:

  • ad-hoc key derivation scheme
  • key sharing between asymmetric signature and encryption systems

We confirmed both claims, key derivation was indeed an ad-hoc choice. Sharing keys is also bad practice.

This NIP and related server changes fixes both issues.


Short summary of changes

  1. The message marker is changed from FE CC71C764BFE598 to FE 2A8061577301E2
  2. The format of attached message is | marker | ephemeral public key | encrypted harvester data |
  • the format of encrypted harvester key is as earlier | initialization vector | encrypted harvester key | Pkcs7 padding |
  1. The process of deriving a key is changed (generation of ephemeral key)
  2. The key derivation function is changed to HKDF-HMAC-Sha256

Key derivation outline

Let's assume account A wants to send to node N (identified by public key N_pub) delegation request transaction with attached harvester private key HPK. Node


  1. generates ephemeral key pair (E_priv, E_pub)
  2. derives "shared secret" from E_priv, and N_pub
  3. derives shared key SK - by passing "shared secret" into HKDF
  4. generates initialization vector IV
  5. uses SK and IV to encode HPK with AES in CBC mode
  6. creates transfer in format specified earlier | marker | E_pub | encrypted data |

Note, that both steps 1 and 4 should use true random source.

Shared secret derivation

"Shared secret" deriviation is the same as before, the only difference is that on

  • senders side, ephemeral private key is used
  • recipient side, attached ephemeral public key is used for derivation

so for example in case of JS (and skipping details):

	const d = prepareForScalarMult(ephemeralPrivateKey, hashfunc, signSchema);
	c.unpack(q, nodePublicKey);
	c.scalarmult(p, q, d);
	// sharedSecret = pack(p = d (derived from private key) * q (derived from public key))
	const sharedSecret = new Uint8Array(Key_Size);
	c.pack(sharedKey, p);

Shared key derivation

Shared key derivation is simply HKDF-HMAC-SHA256. Test cases are provided in RFC5869 (note, that the rfc in test cases mentions SHA256, but it really means HMAC-Sha256)

so for example in cae of JS

	const sharedKey = new Uint8Array(Key_Size);
	const salt = new Uint8Array(32);
	const info = 'catapult';
	const hash = 'SHA-256';

	const sharedKey = hkdf(sharedSecret, 32, { salt, info, hash });

Design Decisions

The scheme outlined above follows ECIES scheme. The usage of ephemeral key unties usage of A key in asymmetric context from encryption. HKDF is well known function used to derive keys from high-entropy sources.


Server part of the changes is already available inside catapult-server repository.

Proper test vectors will be provided inside test-vectors repository.

Backwards compatibility

Old marker (FE CC71C764BFE598) and data in old format will not be supported since next build after

The changes obviously are not backward compatible.


Alternative KDF construction considered was usage of one-step key derivation function using KMAC, as defined in NIST Special Publication 800-56C rev 1. The idea was abandoned, because of poor adaptation in other programming languages.



Date Version
Jan 24 2020 1.0
You can’t perform that action at this time.