Encryption scenarios
The PII of a Travel Rule transfer is encrypted in one of the three ways the PII Encryption Guide describes: Hosted, Hybrid or End-to-End. Which one a transfer uses depends on the originator’s Notabene managed encryption setting, which decides who encrypts the PII, and on the beneficiary’s DID document, which decides whose key it is encrypted to. The beneficiary’s own setting only applies to the transfers it sends.
Scenarios
Who manages the keys on each side decides the scenario. The originator manages its own keys when it turns Notabene managed encryption off and encrypts the PII itself, and the beneficiary manages its own keys when it publishes a #pii key in its DID document.
| Scenario | Originator’s keys | Beneficiary’s keys |
|---|---|---|
| Hosted | Notabene | Notabene |
| Hybrid | The originator | Notabene |
| Hybrid | Notabene | The beneficiary |
| End-to-End | The originator | The beneficiary |
Hosted
decrypt=true- 1The originator sends the PII in clear text to
/append. - 2Notabene encrypts it to the beneficiary’s
#notabene-piiand keeps the originator’s copy. - 3Notabene decrypts it on the beneficiary’s behalf.
Notabene manages the keys of both the originator and the beneficiary, which is where every institution starts. The originator sends the PII in clear text with Append PII data to a transfer, Notabene encrypts it to the beneficiary’s #notabene-pii key, and neither institution handles keys or encryption.
Because Notabene holds both keys, it decrypts the originator’s copy when the originator reads its transfer and the beneficiary’s copy when the beneficiary reads the transfer with Get a specific transfer and decrypt=true, each time on that institution’s behalf.
Hybrid: the originator manages its own keys
decrypt=true- 1The originator encrypts the PII to the beneficiary’s
#notabene-piiand sends it to/presentation. - 2Notabene passes it on and keeps no copy for the originator.
- 3Notabene decrypts it on the beneficiary’s behalf.
The originator manages its own keys and Notabene manages the beneficiary’s keys. The originator has turned Notabene managed encryption off, so it encrypts the PII itself to the key in the webhook, which is the beneficiary’s #notabene-pii, and sends it with Present PII data to counterparties, which leaves no copy on the originator’s side.
Nothing changes for the beneficiary, which reads the transfer with decrypt=true while Notabene decrypts the PII on its behalf.
Hybrid: the beneficiary manages its own keys
- 1The originator sends the PII in clear text to
/append. - 2Notabene encrypts it to the beneficiary’s own
#piiand keeps the originator’s copy. - 3The beneficiary decrypts it with its own private key.
Notabene manages the originator’s keys and the beneficiary manages its own keys. The originator sends the PII in clear text with Append PII data to a transfer, as in Hosted, but the beneficiary has published its own #pii key, so Notabene encrypts the PII to that key instead of #notabene-pii.
The beneficiary reads the transfer with decrypt=false and decrypts the PII with its own private key, and Notabene cannot decrypt the beneficiary’s copy. Notabene still keeps the originator’s copy and decrypts it on the originator’s behalf.
End-to-End
- 1The originator encrypts the PII to the beneficiary’s own
#piiand sends it to/presentation. - 2Notabene passes it on without being able to decrypt it.
- 3The beneficiary decrypts it with its own private key.
Both institutions manage their own keys. The originator encrypts the PII to the key in the webhook, which is the beneficiary’s own #pii key, and sends it with Present PII data to counterparties, so Notabene keeps no copy for the originator and cannot decrypt the one it passes on.
The beneficiary reads the transfer with decrypt=false and decrypts the PII with its own private key, so only the two institutions ever see it in clear text. What each side sets up is in End-to-End setup.
How the PII travels
/appenddecrypt=true- 1The beneficiary asks for the PII, and Notabene picks its
#notabene-piikey, as it has no#piikey. - 2Notabene sends the originator
tap.requirePresentationRequested, with acallbackUrlto/append. - 3The originator sends the PII in clear text with Append PII data to a transfer, and Notabene encrypts it to that key.
- 4The beneficiary reads the transfer with Get a specific transfer and
decrypt=true, and Notabene decrypts the PII on its behalf.
/presentationencryptionKeydecrypt=true- 1The beneficiary asks for the PII, and Notabene picks its
#notabene-piikey, as it has no#piikey. - 2Notabene sends the originator
tap.requirePresentationRequested, with acallbackUrlto/presentationand that key asencryptionKey. - 3The originator encrypts the PII to that key and sends it with Present PII data to counterparties.
- 4The beneficiary reads the transfer with Get a specific transfer and
decrypt=true, and Notabene decrypts the PII on its behalf.
/append- 1The beneficiary asks for the PII, and Notabene picks its own
#piikey, which always comes before#notabene-pii. - 2Notabene sends the originator
tap.requirePresentationRequested, with acallbackUrlto/append. - 3The originator sends the PII in clear text with Append PII data to a transfer, and Notabene encrypts it to that key.
- 4The beneficiary reads the transfer with Get a specific transfer and
decrypt=false, then decrypts the PII with its own private key.
/presentationencryptionKey- 1The beneficiary asks for the PII, and Notabene picks its own
#piikey, which always comes before#notabene-pii. - 2Notabene sends the originator
tap.requirePresentationRequested, with acallbackUrlto/presentationand that key asencryptionKey. - 3The originator encrypts the PII to that key and sends it with Present PII data to counterparties.
- 4The beneficiary reads the transfer with Get a specific transfer and
decrypt=false, then decrypts the PII with its own private key.
Key selection
Notabene chooses the beneficiary’s PII key automatically, from its DID document, and nobody picks it per transfer. A key whose id ends in #pii always comes first, so as soon as an institution publishes one, Notabene encrypts to it and gives it to originators that encrypt themselves, in the webhook’s encryptionKey and through Get entity public encryption keys.
| Order | Key id ends in | Used | Decrypted by |
|---|---|---|---|
| 1 | #pii | Whenever the DID document has one | The institution, with its own private key |
| 2 | #notabene-pii | Only when there is no #pii key | Notabene, on the institution’s behalf |
Adding a
#piikey to your DID document is all it takes for the PII you receive to be encrypted to your own key, which Notabene cannot decrypt. Notabene switches to it within 5 minutes, whatever your own Notabene managed encryption setting is.
End-to-End setup
To receive PII that only you can decrypt, generate a P-256 key pair and keep the private key in your KMS or HSM. Add the public key to your DID document with an id ending in #pii and reference it in keyAgreement, as shown in Key Management in DIDdocs. When PII arrives, read it as described in Receive Travel Rule (PII) data transfers and decrypt it with your private key.
To send PII that Notabene cannot decrypt, turn off Notabene managed encryption in the dashboard Settings and subscribe to tap.requirePresentationRequested. When it arrives, encrypt the IVMS101 to the encryptionKey it carries and send it to its callbackUrl with Present PII data to counterparties. The key agreement, key derivation and JWE format are in Encryption workflow.
Updated 2 days ago