GuidesPostman CollectionRecipesAPI Reference

PII SDK

Encryption & Decryption Library for Personal Identifiable Information (PII)

Suggest Edits

⚠️

The PII SDK should only be used if you are integrating with the Notabene or Fireblocks API.

⚠️

If you are using the Notabene Node SDK the PII SDK functionality is already included.

You can find the PII SDK here.



Installation

yarn

yarn add @notabene/pii-sdk

npm

npm install @notabene/pii-sdk


Usage

Prerequisites

You must create a private/public key pair and publish the public key to the Notabene network. Instructions on how to do that are here.

did:             did:key:z6MkmCX1yN9DFVFKrvJ2ULptaDMZsWeTwa4BLifBAVSFg3gL
controllerKeyId: 643b067d274844756bc6d7c32be7303dd6badcfc31b9dc56e73ec164e23e8249
keys:
  -
    type:          Ed25519
    kid:           643b067d274844756bc6d7c32be7303dd6badcfc31b9dc56e73ec164e23e8249
    publicKeyHex:  643b067d274844756bc6d7c32be7303dd6badcfc31b9dc56e73ec164e23e8249
    meta:
      algorithms:
        - Ed25519
        - EdDSA
    kms:           local
    privateKeyHex: 09e19983ba6efe881a4395ba653742c6ebfdd3bf3ea0ab4359f3474146a7a677643b067d274844756bc6d7c32be7303dd6badcfc31b9dc56e73ec164e23e8249
services:
  (empty array)
provider:        did:key

Initializing the SDK

const PIIsdk = require("@notabene/pii-sdk").default;

const toolset = new PIIsdk({
	clientId: "<YOUR API CLIENT ID>",
	clientSecret: "<YOUR API CLIENT SECRET>",
	audience: "https://pii.notabene.id", // test env url is "https://pii.notabene.dev"
	authURL: "https://auth.notabene.id", // test env url is "https://auth.notabene.id"
	piiURL: "https://pii.notabene.id" // test env url is "https://pii.notabene.dev"
});


Encryption

A full code sample on encrypting a transaction's PII can be found here:


🔒
Using the PII SDK to encrypt and send a tr message
Open Recipe
const PIIsdk = require("@notabene/pii-sdk").default;

const toolset = new PIIsdk({<PII SDK Parameters>});

const originatorVASPdid = "<YOUR VASP DID>"
const beneficiaryVASPdid = "<BENEFICIARY VASP DID>"

const counterpartyDIDKey = "<COUNTER-PARTY PUBLIC KEY>"

const keypair = {
	"did": "<YOUR PUBLIC KEY>",
	"keys": [{
		"privateKeyHex": "<YOUR PRIVATE KEY>"
	}]
}

const pii = {<PII data you want to encrypt>};

// Encrypt PII
const encrypted_pii = await toolset.generatePIIField({
	pii: pii,
	originatorVASPdid: originatorVASPdid,
	beneficiaryVASPdid: beneficiaryVASPdid,
	counterpartyDIDKey: counterpartyDIDKey,
	keypair: keypair,
	senderDIDKey: keypair.did,
	encryptionMethod: 2 // 0=hosted, 1=end-to-end, 2=hybrid
});

transacion = {
	transactionAsset: "ETH",
	transactionAmount: "1000000000000000000",
	originatorVASPdid: originatorVASPdid,
	beneficiaryVASPdid: beneficiaryVASPdid,
	transactionBlockchainInfo: {
		txHash: "",
		origin: "<Blockchain addresss>",
		destination: "<Blockchain address>"
	},
	pii: encrypted_pii,
	pii_url: "https://pii.notabene.id" // test env url is "https://pii.notabene.dev"
}


Decryption

A full code sample on fetching a transaction and decrypting it's PII can be found here:

🔐
Decrypting PII with the PII-SDK
Open Recipe
const PIIsdk = require("@notabene/pii-sdk").default;

const toolset = new PIIsdk({<PII SDK Parameters>});

const keypair = {
	"did": "<YOUR PUBLIC KEY>",
	"keys": [{
		"privateKeyHex": "<YOUR PRIVATE KEY>"
	}]
}

const transaction = {"encrypted transaction"}

// decrypt PII
transaction.ivms101 = await toolset.getPIIObject(transaction.pii, transaction.pii_url, keypair);


Complete flow

Sending end-to-end encrypted PII in a travel rule message

Here is a copy-paste example that will end-to-end encrypt a payload and send it to a beneficiary VASP using txCreate:

(async () => {
    try {
	const PIIsdk = require("@notabene/pii-sdk").default;
	const fetch = require('isomorphic-fetch');

	//Initialize the Notabene encryption toolset
	const toolset = new PIIsdk({
		clientId: "xxxxxxxxxxxxxxxxxxxxxxxxxx", // replace with your own client ID
		clientSecret: "xxxxxxxxxxxxxxx", // replace with your own client secret
		audience: "https://pii.notabene.dev", // prod env: "https://pii.notabene.id"
		authURL: "https://auth.notabene.id", // prod&test env: "https://auth.notabene.id"
		piiURL: "https://pii.notabene.dev" // prod env: "https://pii.notabene.id"
	});

	const originatorVASPdid = "did:ethr:0x54768b1da0c6f1bd0fda15dc6c55cbba40f85744" // replace with your own DID
	const beneficiaryVASPdid = "did:ethr:0xd4bd902ec78578f33a20ff601504d2ab324cfab9" // the DID of the vasp where you are sending

	const counterpartyDIDKey = "did:key:z6MkecCsDyGh4LdUSyhNdVX8E719o92HospPGETauaKpMmfr" // the public key of the beneficiary VASP

	const keypair = { // replace with your own keypair information
		"did": "did:key:z6MkmCX1yN9DFVFKrvJ2ULptaDMZsWeTwa4BLifBAVSFg3gL",
		"keys": [{
			"privateKeyHex": "09e19983ba6efe881a4395ba653742c6ebfdd3bf3ea0ab4359f3224146a7a677643b067d274844756bc6d7c32be7303dd6badcfc31b9dc56e73ec164e23e8249"
		}]
	}

	const pii = {
		originator: {
			originatorPersons: [{
				naturalPerson: {
					name: [{
						nameIdentifier: [{
							primaryIdentifier: 'Smith',
							secondaryIdentifier: 'John',
						}, ],
					}, ],
					geographicAddress: [{
						streetName: 'Chicago Ave',
						townName: 'Chicago',
						country: 'US',
						buildingNumber: '10',
						postCode: '123456',
					}, ],
					nationalIdentification: {
						countryOfIssue: 'US',
						nationalIdentifier: '987654321',
						nationalIdentifierType: 'DRLC',
					},
				},
			}, ],
			accountNumber: [
				'0x2581f70e8c65e357c01cFb591397c39004B3fa4Agggg',
			],
		},
		beneficiary: {
			beneficiaryPersons: [{
				naturalPerson: {
					name: [{
						nameIdentifier: [{
							primaryIdentifier: 'Hall',
							secondaryIdentifier: 'Leah',
						}, ],
					}, ],
				},
			}, ],
			accountNumber: [
				'0x15615618561561561a651561561e614561b1cc65161561',
			],
		}
	};

	// Encrypt PII
	const piiIvms = await toolset.generatePIIField({
		pii: pii,
		originatorVASPdid: originatorVASPdid,
		beneficiaryVASPdid: beneficiaryVASPdid,
		counterpartyDIDKey: counterpartyDIDKey,
		keypair: keypair,
		senderDIDKey: keypair.did,
		encryptionMethod: 1 // 0=hosted, 1=end-to-end, 2=hybrid
	});

	// create a transaction on Notabene using the encrypted data
	const bearer_token = "Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
	const options = {
		method: 'POST',
		headers: {
			accept: 'application/json',
			'content-type': 'application/json',
			authorization: bearer_token
		},
		body: JSON.stringify({
			transactionAsset: "ETH",
			transactionAmount: "1000000000000000000",
			originatorVASPdid: originatorVASPdid,
			beneficiaryVASPdid: beneficiaryVASPdid,
			transactionBlockchainInfo: {
				origin: "0x2581f70e8c65e357c01cFb591397c39004B3fa4Agggg",
				destination: "0x15615618561561561a651561561e614561b1cc65161561"
			},
			pii: piiIvms,
			pii_url: "https://pii.notabene.dev" // prod env :"https://pii.notabene.id"
		})
	};

	const response = await fetch('https://api.notabene.dev/tx/create', options);
        const responseData = await response.json();
        console.log(responseData);
    } catch (error) {
        console.error('An error occurred:', error);
    }
})();


Decrypting end-to-end encrypted PII

A copy-paste example of decrypting end-to-end encrypted PII:

(async () => {
        const PIIsdk = require("@notabene/pii-sdk").default;
        const fetch = require('isomorphic-fetch');


    	//Initialize the Notabene encryption toolset
	const toolset = new PIIsdk({
		clientId: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // replace with your own client ID
		clientSecret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // replace with your own client secret
		audience: "https://pii.notabene.dev", // prod env: "https://pii.notabene.id"
		authURL: "https://auth.notabene.id", // prod/test env: "https://auth.notabene.id"
		piiURL: "https://pii.notabene.dev" // prod env: "https://pii.notabene.id"
	});

	const vaspDid = "did:ethr:0xd4bd902ec78578f33a20ff601504d2ab324cfab9" // replace with your own VASP DID

	const keypair = { // replace with your own keypair information
		"did": "did:key:z6MkecCsDyGh4LdUSyhNdVX8E719o92HospPGETauaKpMmfrL",
		"keys": [{
			"privateKeyHex": "09e19983ba6efe881a4395ba653742c6ebfdd3bf3ea0ab4359f3474146a7a677643b067d274844756bc6d7c32be7303dd6badcfc31b9dc56e73ec164e23e8249"
		}]
	}

  const bearer_token = "Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" // your accessToken
	const options = {
		method: 'GET',
		headers: {
			accept: 'application/json',
			'content-type': 'application/json',
			authorization: bearer_token
		}
	};

	const transactionId = "5098f416-b4d3-421c-9f5a-d82b11dd1b2c" // the transfer ID of the message you want to decrypt

	const resp = await fetch('https://api.notabene.dev/tx/info?' + new URLSearchParams({
			id: transactionId,
		}), options)
		.catch(err => console.error(err));

	const transaction = await resp.json()
  console.log(transaction)
  console.log(JSON.stringify(transaction.ivms101))
  
	// decrypt PII
	transaction.ivms101 = await toolset.getPIIObject(transaction.pii, transaction.pii_url, keypair);
  console.log(JSON.stringify(transaction.ivms101))
})();


The encrypted and decrypted ivms101 data:

{"originator":{"accountNumber":["QmbaENHc5S5MFJb7dDuGncthF6HzHmUzxGikkBikUK3HAG"],"originatorPersons":[{"naturalPerson":{"name":[{"nameIdentifier":[{"primaryIdentifier":"QmRZ6icXvuAM6n6dgjDh4YZc3U7cTCvceuguR21sbWEHQu","secondaryIdentifier":"QmUc4fRrBAYJQBDc2oB7qunwZ8Qcp9dQrfVW6s8XCeHtCL"}]}],"geographicAddress":[{"country":"QmYfqqGKTQTcXY62HGKYFcMuPcXtGsRQpK3QuUew23t8U3","postCode":"QmRq9EdpK9MFnQcoaKQcnyf8Ynqpzen5bL3RfYFuMnLuQ9","townName":"QmVzDHTLq4QPAmAUAMENYoatZj5tHJv3BLfziKtoFZsFtD","streetName":"QmT1mWjw7LtWL5UysBcGc8k9cDsj1eZYPkmdrzNbx3uXcw","buildingNumber":"QmeNdBnYVo5qAYhjtrLHKyCQnxPu1tQfdHTX32nsnjhEWu"}],"nationalIdentification":{"countryOfIssue":"QmZw3nXuTEixbL1DjCvHuYz4sKfLay3zFpHSgBuZcTa1Xn","nationalIdentifier":"QmbDEoa9wPFmWQ5Xo3T9xzSTjALu3dhQgPWdodRVju9G9A","nationalIdentifierType":"QmVUSZgBfXCiMtpSEpaZzDEjx4AYzRKyoAcFDn9sa4uiy3"}}}]},"beneficiary":{"accountNumber":["QmSNJ9F1aHzkhMNv15F6btRubiv4iHs545jM46GCjJLkHo"],"beneficiaryPersons":[{"naturalPerson":{"name":[{"nameIdentifier":[{"primaryIdentifier":"QmQ4HNxywDqebaTnDZDLK5UxobR5ZsjY26KJSZWM9hMxBw","secondaryIdentifier":"QmeAVCbLrvwGRVqW7qUf2Cg7chPpfDK3noGjSzc4iHvmr8"}]}]}}]}}
{"originator":{"accountNumber":["0x2581f70e8c65e357c01cFb591397c39004B3fa4Agggg"],"originatorPersons":[{"naturalPerson":{"name":[{"nameIdentifier":[{"primaryIdentifier":"Smith","secondaryIdentifier":"John"}]}],"geographicAddress":[{"country":"US","postCode":"123456","townName":"Chicago","streetName":"Chicago Ave","buildingNumber":"10"}],"nationalIdentification":{"countryOfIssue":"US","nationalIdentifier":"987654321","nationalIdentifierType":"DRLC"}}}]},"beneficiary":{"accountNumber":["0x15615618561561561a651561561e614561b1cc65161561"],"beneficiaryPersons":[{"naturalPerson":{"name":[{"nameIdentifier":[{"primaryIdentifier":"Hall","secondaryIdentifier":"Leah"}]}]}}]}}

Updated about 2 months ago