Setup
Installation and Setup
It is not necessary for Blacklist Manager users to become familiar with DARA in order to use Blacklist Manager, but the DARA Signatory’s public key and a client authentication key will be required to complete installation, as described in the next section.
Prerequisites
These tools run in a Linux distribution such as Ubuntu.
In order to install and run these tools, docker and docker-compose must be installed first - see reference 6. The operator will need the necessary permissions to download and run programs. If necessary, each Linux command must be preceded by sudo.
DARA Web Program
This is specified in reference 2. The installation image is available at reference 3.
DARA REST API
This is specified in reference 2. The installation image is available at reference 3.
Blacklist Manager
The installation image is available at reference 4.
Configuration Process Overview
The following sections must be actioned in sequence to enable Blacklist Manager to operate correctly:
Download and install the Installation Image
Edit the Static Configuration
Start-up Blacklist Manager
Perform the steps specified in the Runtime Configuration
Installation Image
Obtain and copy the installation files into the <install> folder on whatever machine has been chosen.
Run this command from a terminal on the <install> folder:
docker load < blacklistmanagerapp.tar
This loads the Blacklist Manager program and the database manager. The multiple bitcoind connection and the DARA REST API configuration is described below.
Static Configuration
When the program is started, the loader will use the “.env” and docker-compose.yml files to specify how the program should be run.
Normally, it is not necessary to change the docker-compose.yml file.
Copy the original “.env” file supplied in the installation image to a new file called “.env”. This contains the configuration parameters that must all be set before the program is started. Where default values are provided, we recommend that you avoid changing them for the first run of the program. Only change them if you need to.
Some parameters have no default values, and all values must be supplied. Blacklist Manager will not operate correctly if any parameter values are missing or invalid. Startup errors may be logged to the docker log file – see the docker documentation.
The “.env” parameters include:
Start-up
Run this command from a terminal on the <install> folder:
Check the running status using:
Example output:
Ensure that the NAMES column includes bmapp (the application) and bmdata (the database manager).
Runtime Configuration
When Blacklist Manager is up and running, the configuration commands in the following sections are available.
Most commands require an API key parameter, the syntax is like this:
The parameter is:
Note: It is also possible to use curl or Postman to issue the commands, by modifying the docker-compose.yml file to expose the ports. This is not shown here. Please be aware that this is a security risk.
Runtime Configuration Overview
The following items must be configured as specified below to enable Blacklist Manager to operate correctly:
A DARA signatory (see section DARA Signatory)
The associated DARA Endpoint (see section DARA Endpoint)
At least one bitcoind node (see section bitcoind Node Connections)
A message signing key (see section Signing Key)
An associated miner coinbase key (see section Miner Coinbase Key)
Activate the miner coinbase key (see section 4.4.5.8.2 Validate and Activate)
Note: It is essential to perform all the steps above to achieve an operational configuration.
Get Blacklist Manager Help
Get help on syntax from Blacklist Manager:
This command may be issued at any time and does not require the apiKey.
Get Blacklist Manager Status
Get the status of Blacklist Manager:
This command may be issued at any time and will show what needs to be configured next in an error report. After Blacklist Manager is configured correctly, only warnings or info will be shown.
Example output:
DARA Signatory
Each DARA signatory has their own private key, which will be used to sign sensitive messages that are returned when Blacklist Manager calls the DARA REST API. To enable Blacklist Manager to validate the returned messages, the DARA signatory’s public key must be obtained (see the section Tool Operators) and stored in its database.
Register (POST)
The command syntax to store the signatory’s public key is:
The parameters are:
Show (GET)
Check the DARA signatory configuration in Blacklist Manager:
docker exec bmapp /app/cli/BlacklistManager.Cli bmapp \
GET Trustlist --apiKey=[apikey]
This will emit information on the configured Trustlist data.
Example output:
Update (PUT)
Update the DARA signatory configuration in Blacklist Manager for {id}:
Delete (DELETE)
Delete the DARA signatory configuration in Blacklist Manager for {id}:
docker exec bmapp /app/cli/BlacklistManager.Cli bmapp \
DELETE Trustlist/{id} --apiKey=[apikey]
DARA Endpoint
Blacklist Manager must have access to at least one DARA endpoint before it can start to download any digital court orders.
Register (POST)
The command syntax to register the DARA endpoint is:
The parameters are:
Note: Before the DARA endpoint is added to the database, Blacklist Manager performs a connection check on the endpoint, and if successful it also verifies whether the returned public key is trusted, and the signature is valid.
Show (GET)
Check the DARA endpoint configuration in Blacklist Manager:
This will emit information on the configured endpoint data.
Example output:
Update (PUT)
Update the DARA endpoint configuration in Blacklist Manager for {id}:
Delete (DELETE)
Delete the DARA endpoint configuration in Blacklist Manager for {id}:
bitcoind Node Connections
Multiple bitcoind nodes can be registered with Blacklist Manager so that they can be made aware that specific transaction outputs are marked as frozen by digital court orders and cannot be spent.
The multiple bitcoind nodes will also be notified when transaction outputs are unfrozen and can be spent again.
Register (POST)
The command syntax to add a bitcoind node is:
The parameters are:
Note: Before a bitcoind node is registered, Blacklist Manager performs a connection check with the endpoint.
Note: After a bitcoind node is registered, Blacklist Manager clears and then repopulates the Nodes’ policy and consensus blacklists.
Show (GET)
Check the bitcoind node configuration in Blacklist Manager:
This will emit information on all configured node data.
Example output:
The possible status values are:
Note: show data for one bitcoind node by specifying the {id} after Node in the command line.
Update (PUT)
Update the bitcoind node configuration in Blacklist Manager for {id}:
Delete (DELETE)
Delete the bitcoind node configuration in Blacklist Manager for {id}:
Signing Key
Blacklist Manager always signs sensitive data before sending it to DARA. To do that, the data signing key must be stored in the database otherwise DARA will not find any blocks for its hash power calculations. This information is used to determine how much hash power has voted in favour of a digital court order.
The administrator can add a new data signing key to Blacklist Manager anytime, but whenever the new signing key is activated, the previous signing key is deactivated.
Add (POST)
The command syntax to add a new signing key is:
The parameters are:
Note: A default private key with delegationRequired=true is generated when the Blacklist Manager is started for the first time. If the administrator decides to use the default private key provided, then this step can be omitted.
Note: If delegationRequired=false, the signing key must be the one that was used for the receiving address of the Coinbase transaction block reward. Since this may expose the miner’s private key, we recommend using the delegationRequired=true feature.
Note: If the miner is concerned that the private key has become compromised, a new one should be activated, and the Notary should be informed immediately which signing public key is no longer valid.
Show (GET)
Check the signing key configuration in Blacklist Manager:
This will emit information on the configured signing key data.
Example output:
The signerId will be referenced by the miner coinbase key, configured in the next section.
Note: The private key is not emitted.
Miner Coinbase Key
The miner coinbase key is used by DARA when it is determining how many blocks have recently been mined with a particular miner’s coinbase key. This information is used to determine how much hash power has voted in favour of a digital court order.
The relevant mined blocks are those that ultimately refer back to:
A coinbase transaction reward sent to a public key in a P2PKH script
A coinbase transaction which contains the MinerId coinbase document (reference 7) where the minerId field contains the public key of the miner (only applicable to BSV)
The relevant miner’s key is the one that was used to sign the coinbase transaction.
Add (POST)
The command syntax to add a miner coinbase key is:
The parameters are:
Note: Multiple miner coinbase keys can be added to each signer key.
Note: Exactly one of publicKey or publicKeyAddress must be provided.
Example output:
The fields are:
The minerId and the dataToSign are required for the next section.
Validate and Activate (PUT)
Each miner coinbase key that was inserted into the Blacklist Manager database must be validated before it can be used. Validation is performed by verifying whether a provided signature matches the publicKey or publicKeyAddress that was sent in a request when adding a new miner coinbase key (see above) and the dataToSign that was sent in the response to that command.
The command syntax is:
The parameters are:
Note: When the administrator is ready to use the miner coinbase key and signing key combination, the activateKey field above should be set to true. The previous key combination will be deactivated, and all future documents sent from Blacklist Manager will use the activated key combination.
Note: The administrator must sign the dataToSign using the miner’s private key which generated the public key specified in section 4.4.5.8.1 Add Miner Coinbase Key
Note: It is essential to perform this step to confirm that an operational configuration has been achieved.
Viewing Logs
The docker logs are available for inspection by container ID.
Check the docker status using:
Example output:
Collect the docker logs using:
View the log with any text editor or search it with any text searching tool.
Last updated