PII Encryption Guide
A Hybrid Approach Using Elliptic Curve Cryptography
This section explains how the end‑to‑end encryption in Notabene works and how to integrate it into your application. It is based on the Elliptic Curve Diffie‑Hellman Ephemeral–Static (ECDH‑ES) standard defined in RFC 7518 and uses AES‑256‑GCM for content encryption.
Overview
Notabene’s encryption design uses widely supported cryptographic primitives so that it can be implemented across operating systems and languages. The core elements include:
- Elliptic Curve P‑256 (secp256r1) – a NIST‑approved elliptic curve offering ~128‑bit security. The curve is widely implemented in TLS libraries and hardware modules; it is defined in FIPS 186‑4, approved for government use and has excellent hardware support.
- ECDH‑ES key agreement – uses an ephemeral key generated for each session and a recipient’s static public key to derive a shared secret. The shared secret is used directly as the content‑encryption key (CEK) in the “Direct Key Agreement” mode.
- ConcatKDF key derivation – defined in NIST SP 800‑56A. It derives an AES key from the ECDH secret and optional PartyU/PartyV information (APU/APV).
- AES‑256‑GCM – encrypts the PII with authenticated encryption. A 96‑bit IV and a 128‑bit authentication tag are used as required by the JWE specification.
- JSON Web Encryption (JWE) – encapsulates the encrypted content, initialization vector and authentication tag. It is transmitted as a compact string.
Notabene supports different encryption models depending on who manages the keys. The following diagram illustrates these options. When Notabene generates and manages the keys, it can decrypt PII stored in its nodes. When the client manages the keys, Notabene only stores opaque ciphertext:
| Encryption model | Key management | Can Notabene decrypt? |
|---|---|---|
| Notabene encrypts PII and manages the keys - Hosted | Notabene generates keys, encrypts clear‑text PII received from the client and stores the ciphertext on its nodes. | Yes |
| One of the parties manages own keys and encrypts, the other party uses Notabene managed keys - Hybrid | The client encrypts the PII using keys provisioned by Notabene (published in the client’s DID Document). | Yes |
| Client encrypts PII – client manages keys - End-to-End | The client encrypts the PII with its own keys and publishes the public portion in its DID Document. Only the counterparty can decrypt the data. | No |
Hosted encryption flow is illustrated below
Both entities are using notabene managed encryption, fully hosted flow. No encryption work required from either of the customers. Originator is using txAppend call to send PII data. Data is stored on each node.
Hybrid encryption flow is illustrated below:
Originator using Notabene managed keys, beneficiary managing own keys. Originator sending data to Notabene, beneficiary retrieving keys and decryption in their system. Data in Node B is only in encrypted form.
Originator managing own keys, beneficiary using Notabene managed keys. Originator using txPresentation, beneficiary getting decrypted data from Notabene’s system
End-to-End Encryption flow is illustrated below:
Both entities managing their own keys and originator using txPresentation
💡 Node is a namespace for each VASP within Transaction Authorization Protocol (TAP). Node is generally hosted on Notabene’s infrastructure stack but could be also self hosted by each VASP.
💡 using txPresentation to transmit PII will result in data not stored on the originator node, only on the benificiary node. txAppend stores PII data in both nodes.
Technology Stack
| Component | Technology |
|---|---|
| Cryptographic Engine | Web Crypto API (native browser/Node.js cryptography) |
| Elliptic Curve | Elliptic CurveP-256 (secp256r1) |
| Key Storage | Veramo Agent (key generation, storage, and retrieval) |
| Content Encryption | AES-256-GCM (performed by Web Crypto API) |
| Key Agreement | ECDH-ES (performed by Web Crypto API) |
| Key Derivation | ConcatKDF per RFC 7518 (custom implementation) |
Best practices
The following practices strengthen your integration:
- Use an HSM or cloud KMS – generate and store private keys in a secure hardware module. Private keys should never be exportable.
- Rotate keys regularly – refresh P‑256 key pairs on a schedule. Update your DID Document to advertise new public keys.
- Use unique ephemerals – always generate a fresh ephemeral key for each encryption session to achieve forward secrecy.
- Publish public keys in DID Documents so counterparties can discover them.
- Validate APU/APV on decryption to prevent unknown‑key‑share attacks.
Code examples
You can find our code examples using encryption and presentation endpoint in Java, Rust and Typescript here
Recipe Demo
You can find three basic recipes to:
- Generate encryption (P-256) keys and update didDOC - link
- Encrypt using ECDH-ES and submit data to txPresentation endpoint - link
- Decrypt using own private key and JWT passed in payload - link
Updated about 3 hours ago