The Notabene agent
The Notabene agent is a Docker container that enables a VASP to easily set up E2E and hybrid encryption.
You can get the Notabene agent from here
Usage
To use the Notabene Agent, follow these steps:
Clone the repository:
git clone [email protected]:notabene/open-source/notabene-agent.git
https://gitlab.com/notabene/open-source/notabene-agent.git
Move into the right directory
cd notabene-agent
Build the Docker image:
docker build -t notabene-agent .
Run the container, and make sure to customize the URLs api.notabene.id and pii.notabene.id if you are looking to use it in the production environment, and api.notabene.dev and pii.notabene.dev for the test environment
docker run \
-p 3000:8080 \
-e PORT=8080 \
-e CLIENT_ID=YourClientId \
-e CLIENT_SECRET=YourClientSecret \
-e AUTH_URL=https://auth.notabene.id \
-e AUDIENCE=https://api.notabene.id \
-e BASE_URL=https://api.notabene.id \
-e AUDIENCE_PII=https://pii.notabene.id \
-e BASEURL_PII=https://pii.notabene.id \
-e KEYS='[{"vaspDID":"did:ethr:0x1111111","privateKeyHex":"987654321___123456789"}]' \
notabene-agent
// By default the Notabene Agent listens on port 3000. The -p option maps a host port to the container port.
// The KEYS argument is optional, but required for Hybrid and E2E encryption flows.
docker run \
-p 3000:8080 \
-e PORT=8080 \
-e CLIENT_ID=YourClientId \
-e CLIENT_SECRET=YourClientSecret \
-e AUTH_URL=https://auth.notabene.id \
-e AUDIENCE=https://api.notabene.dev \
-e BASE_URL=https://api.notabene.dev \
-e AUDIENCE_PII=https://pii.notabene.dev \
-e BASEURL_PII=https://pii.notabene.dev \
-e KEYS='[{"vaspDID":"did:ethr:0x1111111","privateKeyHex":"987654321___123456789"}]' \
notabene-agent
// By default the Notabene Agent listens on port 3000. The -p option maps a host port to the container port.
// The KEYS argument is optional, but required for Hybrid and E2E encryption flows.
Use the container proxy server:
POST http://localhost:3000/tx/create
API reference
Almost all endpoints are identical to our API documetation (https://doc.notabene.id/). Except you do not need to provide an authorization header, the agent takes care of that using the Auth0 ClientId and ClientSecret credentials.
E2E Encryption
Requirement: For this flow your VASP needs to have an encryption keypair. To generate a new keypair call the following endpoint: GET http://localhost:3000/didkey/new
. The output will contain several fields that need to be processed:
- Update your VASP in the Notabene network to set its
pii_didkey
field to thisdid:key:...
value. - Use the
privateKeyHex
value to initialize the Notabene Agent with theKEYS
argument, associating your vaspDID with this private key.
- POST
localhost:3000/tx/create
-- creates a transaction and encrypts the PII data if theoriginatorVASPdid
appears in theKEYS
. If thebeneficiaryVASPdid
has nopii_didkey
it will only encrypt for the originator. - GET
localhost:3000/tx/info?id=txid&vaspDID=did:ethr:0x123
-- gets the transaction & decrypts the PII data if thevaspDID
appears in theKEYS
. When managing multiple VASPs you may not know theoriginatorVASPdid
given a transaction ID, in that case you can call this endpoint twice. - POST
localhost:3000/tx/update
-- updates a transaction and decrypt the PII data if theoriginatorVASPdid
appears in theKEYS
. If thebeneficiaryVASPdid
has nopii_didkey
it will only encrypt for the originator.
Hybrid Encryption
Requirement: For this flow your VASP needs to have an encryption keypair. (see E2E Encryption)
- POST
localhost:3000/tx/create?hybrid=1
-- creates a transaction and encrypts the PII data if theoriginatorVASPdid
appears in theKEYS
. If thebeneficiaryVASPdid
has nopii_didkey
it will only encrypt for the originator. - GET
localhost:3000/tx/info?id=txid
-- because of hybrid encryption only the transaction ID is required. - POST
localhost:3000/tx/update?hybrid=1
-- updates a transaction and decrypt the PII data if theoriginatorVASPdid
appears in theKEYS
. If thebeneficiaryVASPdid
has nopii_didkey
it will only encrypt for the originator.
Updated 5 months ago