GuidesPostman CollectionRecipesAPI Reference

Encryption

Suggest Edits

Getting your JsonDIDKey

For End-2-End and Hybrid encryption, your VASP needs a dedicated DIDKey which is a public-private keypair. You can create a new keypair using the @notabene/cli and then publish it to the Notabene directory under the pii_didkey field. This allows other VASPs retrieve your public key and encrypt PII data to you:

  1. Installing the CLI:
npm i -g @notabene/cli
  1. Generate JsonDIDkey
notabene keys:create

This will generate a JSON object containing an Ed25519 key and metadata which can be passed to the Notabene SDK when creating transactions to encrypt the PII.

{
"did":"did:key:z6MkjwpTikNZkpfop2ebcbPfsxi786ftTr9nGBD3XKKHZ2S",
"controllerKeyId":"519b59a6b7ebf128f6c6af4081f5e512750e768908263dbc656b7b3541c33",
"keys":[{"type":"Ed25519","kid":"519b59a6b7eb7689c6af4081f5e512750e1b4e47f08263dbc656b7b3541c33",
"publicKeyHex":"519b59a6b7ebf128f6c7689f5e512750e1b4e47f08263dbc656b7b3541c33",
"meta":{"algorithms":["Ed25519","EdDSA"]},
"kms":"local",
"privateKeyHex":"0d07d8acda928f98765e4a0b80013e2be369c29564419ac3ba08107599aeb3fc519b59a6b7ebf128f6c6af4081f5e512750e1b4e47f08263dbc656b7b3541c33"}],
"services":[],
"provider":"did:key"
}

Adding the public key to the Notabene network VASP profile

curl --location '{{baseURL}}/tf/vasps/update' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data '{ "did": "{{your_vasp_did}}",
    "fields": [
        {
            "fieldName": "pii_didkey",
            "values": [
                {
                    "value": "{{your_vasp_did_key}}"
                }
            ]
        }
    ]}'

// get your encryption key
const ikey = ... // or create a new key using the CLI, or: await client.toolset.createKey();

// extract the did:key (public key)
const pii_didkey = JSON.parse(ikey).did;

// upload did:key to your VASP on the Notabene directory
const fields = [
  {
    fieldName: 'pii_didkey',
    values: [
      {
        value: pii_didkey,
      },
    ],
  },
];
await client.trustFramework.update(vaspDID, fields);

Typically you will do this only once, and re-use the same keypair for a long time. If you believe your private key was compromised, you can rotate your keypair (ie. create a new one + publish it again). Data encrypted using a specific public key can only be decrypted with its private key, so don't throw away your old key(s) if you still have data of interest encrypted with those key(s).

const { Notabene } = require("@notabene/nodejs");

const client = new Notabene({
    authURL: 'https://auth.notabene.id',
    baseURL: "https://api.notabene.dev",
    audience: "https://api.notabene.dev",
    clientId: "xxxxxxx",
    clientSecret:"xxxx-xxxxxx",
    baseURLPII: "https://pii.notabene.dev",
    audiencePII: "https://pii.notabene.dev",
});

const pii_didkey = "did:key:z6MkjwpTikNZkpfop2ebcbPfsxi786ftTr9nGBD3XKKHZ2S"

const vaspDID = "did:ethr:0xd4bd902ec78578f33a20ff601504d2ab324cfab9"

// upload did:key to your VASP on the Notabene directory
const fields = [
  {
    fieldName: 'pii_didkey',
    values: [
      {
        value: pii_didkey,
      },
    ],
  },
];

const myfunc = async function () {
    const uploadKeys = await client.trustFramework.update(vaspDID, fields);
    console.log(uploadKeys);
  };
  myfunc().catch((err) => console.error(err));

Message encryption

We follow the JWE spec:

DIDComm Messages are encrypted with the keys of a single DID. A message being sent to multiple DIDs MUST be encrypted for each DID independently. If a single DID has multiple key types, the keys of each type must be used in a separate encryption of the message.

DIDComm supports two types of message encryption: Authenticated Sender Encryption (“authcrypt”) and Anonymous Sender Encryption (“anoncrypt”). Both forms are encrypted to the recipient DID. Only authcrypt provides direct assurances of who the sender is. Each encrypted message MUST use either authcrypt or anoncrypt.

The encrypted form of a JWM is a JWE in General JSON Format. The JOSE family defines JSON Web Algorithms (JWAs) which standardize certain cryptographic operations that are related to preparing JOSE structures. For the purposes of interoperability, DIDComm messaging does not support all JWAs; rather, it takes a subset of the supported algorithms that are applicable for the following cases around secure messaging. These supported algorithms are listed in tables later in the spec.

ECDH-1PU for key wrapping
XC20PKW for data encryption
X25519 for in-memory key encryption

Data encryption

Data is encrypted using AWS KMS and SSE-S3.
Encryption / Decryption operations are managed, logged, and monitored within AWS.
Data at rest in AWS is encrypted using ECDH-1PU+XC20PKW.
Data in transit is encrypted using TLS 1.2 or greater.

SafePII

Notabene adds a new PII service to our Travel Rule nodes. This industry-first feature allows VASPs to manage the secure exchange of encrypted PII to counterparties while simultaneously managing their own encryption keys.

As a separate first-class service run on behalf of our clients, SafePII is next to but complementary to our existing Travel Rule Service API. Separating this critical part of our API will allow VASPs to take a risk-based approach to better implement the Travel Rule from a data protection point of view. The escrow aspect of our service will enable us to perform address ownership and proprietary Notabene rule-based checks before encrypted PII is exchanged with the beneficiary VASP.

Encryption keys are, by default, managed by VASPs themselves. Still, VASPs can elect to utilize our key management infrastructure for some or all aspects of their service, similarly to how VASPs use a combination of local hot wallets and custodial wallet API services today. Unlike wallet API services, we explicitly designed our SafePII service around data encryption.

Regardless of how VASPs choose to use our SafePII service in the future, it is a considerable step up in data security over building your own service to integrate with an existing Travel Rule protocol. It also signals to counterparty exchanges that you take the data protection duties of implementing the Travel Rule very seriously.

Based on their needs, VASPs can choose between three different options:

  • End-to-end
  • Hosted
  • Hybrid

If you want to use SafePII, you must utilize our SDK.

End-to-end encryption

End-to-End SafePII brings the most security, as the Originating VASP encrypts PII data so that only they and the Beneficiary VASP can decrypt it.

In this flow, PII data traveling across the ether will be encrypted, meaning Notabene will never have access to the contents. Even in a hacking case or a leak, the attackers will not be able to decrypt the PII data because it’s simply cryptographically “impossible” – unless they can figure out the decryption key, which is only known by either of the VASPs.

Hosted encryption

During the Hosted SafePII flow, Notabene encrypts all raw Travel Rule transaction data created through our easy-to-use restful API without worrying about local key management. Each VASP has a dedicated encryption key managed by Notabene’s PII service and can be rotated on-demand.

Our current API customers will automatically be migrated to the Hosted Escrow PII flow without any manual changes. The Hosted flow is beneficial for VASPs using hosted/white-label exchange software and/or VASPs that don’t feel comfortable managing encryption keys by themselves.

Hybrid encryption

The Hybrid SafePII mode extends the End-to-End flow, where the Originator VASP further encrypts the PII data selectively using their dedicated Notabene-managed encryption key, allowing Notabene to decrypt the PII (or parts of the PII data) for in-flow pre-transaction name sanction screening.

More information

At its core, our new SafePII service is built entirely using open standards and libraries. We believe it is important not to reinvent the wheel, particularly regarding encryption. Our goal is to push some of the learnings we have made here into Travel Rule protocol groups and provide our core encryption libraries as open source.

The Notabene Travel Rule Network is built on top of the W3C standard of Decentralized Identifiers (DIDs), co-authored by two of our Notabene co-founders. Our new SafePII service utilizes the DID-Comm standard for securely exchanging encrypted and authenticated messages between entities such as VASPs.

Click here to learn how Decentralized Identifiers (DIDs) are shaping the Crypto Travel Rule infrastructure.

This set-up, in turn, is based on long-time industry standards for encryption JSON Web Encryption. We use the EdDSA encryption algorithm by default, which is currently recognized as the most secure public key encryption algorithm. We can easily upgrade to newer, better protocols in the future.

When encrypting a data item, an entirely new key is generated and encrypted to VASP’s public keys, encrypts the data, and is discarded. This ensures that even if bad actors could decrypt a single data item using massive national government-grade computing power, they will only be able to crack that specific data item–nothing more.

All data is additionally hashed and only identifiable by a content addressable identifier (CID) which stems from the InterPlanetary File System (IPFS) ecosystem. Knowing a CID is not enough to access the data; the client must be authorized and authenticated by the owner(s) to gain access. Typically the owners are the Originator & Beneficiary VASPs, but it could also be an intermediary such as Notabene.

CIDs are useful as VASPs can use them as consistent internal identifiers of PII without exposing the risk of actual PII within their own services.

Additional Security considerations:

  • In the End-to-End and Hybrid SafePII flows, VASPs encrypt PII data to each other using their self-managed keys.
  • VASPs publish their respective public keys on the Notabene VASP Network for key discovery.
  • VASPs can rotate their self-managed keys by generating a new cryptographic key pair and publishing the public key on the Notabene VASP Network.
  • PII service-managed keys (during hosted & hybrid flows) can constantly be rotated on-demand.
  • Used encryption keys must comply with the new W3C “did:key” spec.
    ‍

Updated 5 months ago