Installing CASP

This chapter walks you through the Unbound CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. service installation and activation process. If you are upgrading from a previous version of CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions., follow the procedure in Upgrading CASP.

CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. installation includes the following steps:

Prerequisites

Installation instructions for the prerequisites are provided in the following sections.

Install Java

  1. Determine which version of java you have by running the following command:

    java -version

  2. If you are not running one of the versions of Java described in System Requirements, download and install it.

Set up NodeJS

NodeJS is required for the built-in wallets. If you are using BYOWClosedBring Your Own Wallet - support any coin or crypto asset type using the CASP APIs to control the vault and key operations., then you can skip this step. To install NodeJS, follow the instructions found on the NodeJS website:

https://nodejs.org

For example, for CentOS or Ubuntu, following the instructions described in NodeJS Package Managers.

To verify that NodeJS is installed, run the following command:

node -v

Tip
You may want to use a NodeJS package manager, such as n or nvm, to help manage the NodeJS version.

Set up Apache HTTP Server

Install Apache HTTP daemon.

  • For CentOS:
  • sudo yum -y install httpd
    sudo yum -y install mod_ssl

  • For Ubuntu:
  • sudo apt-get install -y apache2
    sudo a2enmod ssl
    sudo a2enmod proxy
    sudo a2enmod proxy_http

Setup UKC

Setting up UKCClosedUnbound Key Control - The name of Unbound's key management product., involves installing UKCClosedUnbound Key Control - The name of Unbound's key management product., configuring it for CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions., and configuring the backup key.

  1. Install UKCClosedUnbound Key Control - The name of Unbound's key management product..
    1. Install the UKCClosedUnbound Key Control - The name of Unbound's key management product. entry point (EP) and partner servers.

      Note
      Only use the FIPSClosedFederal Information Processing Standards - standards developed by the United States federal government for use in computer systems by non-military government agencies and government contractors installation instructions if you specifically need it.

    2. For BIP implementations, install an auxiliary server.

    3. Refer to the UKC User Guide for more information about this process.
  2. Configure UKCClosedUnbound Key Control - The name of Unbound's key management product. for CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions..
    1. Create a new partition named casp.

      Notes
      1. To access this partition, the username is user.
      2. If you have multiple CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. systems, each one needs a dedicated partition.

    2. Reset the default user password in the new CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. partition.
    3. Allow no certificate.
  3. Create the cold backup key (which can be a 2048, 3072 or 4096 bit key). This key is used to encrypt the key material. The backup private key must be strongly segregated from the CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. system. The following are possible methods for creating this key.
    1. Use another UKCClosedUnbound Key Control - The name of Unbound's key management product. system, segregated from your CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. environment (that is, not the UKCClosedUnbound Key Control - The name of Unbound's key management product. that you are using for this CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. implementation).
    2. Use an offline device that is not connected to the network. You can run the following command on your offline device to create an RSA 2048 key pair.

      openssl genrsa 2048 > key.pem

    3. Use an HSMClosedHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing.

    Note
    It is recommended to put the private key in cold, disconnected storage. The key can also be duplicated for resiliency.

  4. Install the cold backup key.

    A file with the public part of this key must be installed on the Entry Point (EP) and Partner of one server pair. It serves as the UKCClosedUnbound Key Control - The name of Unbound's key management product. backup encryption key for databases located on the EP and Partner servers.

    1. Create a file with the public key. For example, if your key is in a file called key.pem:

      openssl rsa -in key.pem -pubout > casp_backup.pem

    2. Run the UKC offline backup key script, once on the EP server and once on the Partner server.

    Note
    If you have multiple UKCClosedUnbound Key Control - The name of Unbound's key management product. pairs, you only need to run the script on one pair.

  5. You can verify the UKCClosedUnbound Key Control - The name of Unbound's key management product. installation by running a curl command. See Checking UKC Service for more information.

Note
To restore, follow the procedure described in CASP Restore Utility.

Tip
For troubleshooting information, see Troubleshooting in the UKCClosedUnbound Key Control - The name of Unbound's key management product. User Guide.

OpenSSL Configuration

Check that your version of OpenSSL supports the required curves. List the curves using this command:

openssl ecparam -list_curves

The output should contain these curves:

secp256k1 : SECG curve over a 256 bit prime field
secp384r1 : NIST/SECG curve over a 384 bit prime field
secp521r1 : NIST/SECG curve over a 521 bit prime field
prime256v1: X9.62/SECG curve over a 256 bit prime field

If those curves are not found in the output, you need to update your version of OpenSSL.

For example, on CentOS run:

sudo yum update openssl

CASP Package Installation

Download and install the CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. Service.

  1. Access the CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. repository from the link provided to you by Unbound.

  2. Select your platform and version and then download the corresponding package, casp-{version}.rpm or casp-{version}.deb.
  3. (Optional) Verify the package as described in Unbound Public Key.
  4. Install the package file.
    • For CentOS:

      sudo yum -y install casp-{version}.rpm

    • For Ubuntu:

      sudo dpkg -i casp-{version}.deb

CASP Configuration

The following steps describe configuration that is needed after installing the CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. package. The section CASP Setup Utility is not required but can be helpful with configuration. Follow the rest of the sections as needed.

Warning
CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. requires that you set up the UKCClosedUnbound Key Control - The name of Unbound's key management product. backup, as described in Backup.

Configure the CASP Database

  1. On the CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. Orchestrator, create the CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. database and a database user. See Server Requirements for a list of supported databases. The database user and password are needed for the casp.conf file as described in the next section.
    • For MySQL:

      mysql -u username -p -e "CREATE DATABASE casp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

    • For PostgreSQL:

      psql -U username -c 'CREATE DATABASE casp;'

      Or:

      createdb casp

      See PostgreSQL for more information on installing PostgreSQL.

  2. Load the schema file from directory /opt/casp/sql. Use the file that corresponds to your database.
    • For MySQL:

      mysql -u username -p database < /opt/casp/sql/casp-mysql.sql

      For example, for a database named casp, with a user sa, and password abc123:

      mysql -pabc123 casp -u sa

    • For PostgreSQL:

      psql -U username casp < /opt/casp/sql/casp-postgresql.sql

CASP Setup Utility

CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. contains scripts that can help with the installation. They are found in the bin directory and provide these functions:

Each of these scripts and their associated options are explained in the following sections.

UKC Password Setup

This script encrypts the UKCClosedUnbound Key Control - The name of Unbound's key management product. password that is used in the CASP Configuration File. The script uses the casp.conf file if it exists. If it does not exist, the script creates the file.

Syntax:

sudo casp_setup_ukc \
--ukc-url=<ukc_url> \
--ukc-user=<ukc_user> \
--ukc-password='<ukc_password>' \
--force-get-ukc-ca

Note
This command must be called with sudo.

The parameters are described in the following table.

Parameter Required Description
ukc-url required URL of the UKCClosedUnbound Key Control - The name of Unbound's key management product..
ukc-user required UKCClosedUnbound Key Control - The name of Unbound's key management product. user name. The format is the user name, an @ sign, and then the partition name. For example, "user@casp".
ukc-password optional UKCClosedUnbound Key Control - The name of Unbound's key management product. password. If it is not specified on the command line, the utility prompts for it. This password was set up in Setup UKC, step 2b. Use single quotes if the password contains special characters.
force-get-ukc-ca optional The first time that the utility runs it downloads the certificate (in PKCSClosedPublic-Key Cryptography Standards - Industry-standard cryptography specifications. #7 format) for the UKCClosedUnbound Key Control - The name of Unbound's key management product. server. Subsequent runs use the same certificate, unless this flag is specified.

Example:

sudo casp_setup_ukc --ukc-url <IP ADDRESS OF UKC EP> --ukc-user user@casp --ukc-password '<UKC PASSWORD>'

Warning
You must restart the CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. services for the changes to take effect, using the command:
sudo service casp.tomcat restart

UKC Health Check

This script checks the health of the UKCClosedUnbound Key Control - The name of Unbound's key management product..

Syntax:

casp_check_ukc

There are no parameters for this script.


The response for a correctly working UKCClosedUnbound Key Control - The name of Unbound's key management product. is:

UKC health check was successful

Database Password Setup

This script encrypts the database password that is used in Configure the CASP Database.

Syntax:

sudo casp_setup_db \
--db-url=<DB_url> \
--db-user=<DB_user> \
--db-password=<DB_password> \
--db-driver=<org.postgresql.Driver> \
--db-driver-path=<postgresql-9.6.jar>

Note
This command must be called with sudo.

The parameters are described in the following table.

Parameter Required Description
db-url required URL of the database.
db-user required Database user name.
db-driver required The database driver, such as org.postgresql.Driver or com.mysql.jdbc.Driver.
db-driver-path required Path to the database driver, such as postgresql-9.6.jar or /opt/casp/jdbc/mysql-connector-java-8.0.12.jar.
db-password optional Database password. If it is not specified on the command line, the utility prompts for it.

Example:

sudo casp_setup_db --db-url jdbc:postgresql://casp.abc123.us-east-1.rds.amazonaws.com:5432/casp --db-user myDBuser --db-driver org.postgresql.Driver --db-password abc123456 --db-driver-path /opt/casp/jdbc/postgresql-42.2.5.jar

Warning
You must restart the CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. services for the changes to take effect, using the command:
sudo service casp.tomcat restart

Database Health Check

This script checks the health of the database.

Syntax:

casp_check_db

There are no parameters for this script.


The response for a correctly working database is:

Database health check was successful

Tip
You can check the database health with the Database Health Check script, the Status API, or in the Web Interface.

Firebase Token Setup

This script configures the Firebase token that is used for push notifications on MacOS.

Syntax:

casp_setup_fb_token \
-token <arg>

The parameters are described in the following table.

Parameter Required Description
token required Firebase token.

CASP Configuration File

You must verify all the settings in the /etc/unbound/casp.conf file. The default configuration file is created when CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. is installed. Replace all values in angle brackets ("< >") with the desired values. You must uncomment the lines related to the database that you are using (either MySql or PostgreSQL). All other lines that are commented are optional.

Notes
1. If you ran the UKC Password Setup or Database Password Setup script, you see encrypted passwords in this file.
2. Passwords containing the following characters should not be used in the casp.conf file: %, !

# Database Settings (PostgreSQL) - Uncomment if using PostgreSQL
#database.url=jdbc:postgresql://localhost:5432/casp
#database.user=postgres
#database.password=123456
#database.driver=org.postgresql.Driver
#database.driverfile=/opt/casp/jdbc/postgresql-<VERSION>.jar

# Database Settings (MySQL) - Uncomment if using MySQL
#database.url=jdbc:mysql://localhost:3306/casp?useUnicode=true&characterEncoding=UTF-8
#database.user=root
#database.password=12345678
#database.driver=com.mysql.cj.jdbc.Driver
#database.driverfile=/opt/casp/jdbc/mysql-connector-java-<VERSION>.jar

# UKC Settings
ukc.url=https://<UKC URL>
ukc.user=<UKC user>@<UKC partition>
ukc.password=<UKC user password>

Tip
You can check the UKCClosedUnbound Key Control - The name of Unbound's key management product. health with the UKC Health Check, Status API, or in the Web Interface.

Wallet Configuration

After installing CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions., you need to configure it to handle the crypto assets that you are using. CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. provides the infrastructure to handle various types of crypto assets, as shown in the following figure.

The heart of CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. is the CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. Core that handles all key management functionality. The CASP Transaction Handler is an interface that provides a way to customize the format of the transactions. Crypto assets are handled in one of these ways:

  1. Built-in wallets - implemented using one of these methods for the chain connector:
    1. Built-in support is provided for crypto assetClosedDigital information that needs to be securely stored. ledgers for Bitcoin and Ethereum. The implementation is described below.
    2. Plugins can be created to customize your chain connector for different types of crypto assetClosedDigital information that needs to be securely stored. ledgers. Refer to the Chain Connector section of the CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. Developers Guide for information on how to create your own plugin.
  2. BYOWClosedBring Your Own Wallet - support any coin or crypto asset type using the CASP APIs to control the vault and key operations. - Bring Your Own Wallet - fully customized design using the Unbound APIs. See here for the full set of APIs provided to implement your wallet.

Configuration of the built-in chain connectors is described as follows.

Note
This configuration is needed only if you are using one of CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions.'s built-in crypto assets.

It is recommended to build your system using Bitcoin Testnet. Once the system is validated, switch to one that uses real currency.

Note
The log files for all wallets are in /var/log/unbound/.

Tip
You can check the chain connector health with the Status API or in the Web Interface.

A script is provided that configures the CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. chain connectors. It can be used for

The script modifies the /etc/unbound/wallets/development.yaml file.

Note
All default values are taken from /opt/casp/provider/wallets/config/default.yaml. You must not edit this file since it is overwritten during an upgrade. However, you can use it for a reference for what options are available. To override a value, set it in /etc/unbound/wallets/development.yaml. For example, you can set minTransactionValue and/or maxTransactionValue. (The min/maxTransactionValue parameters are specified in the smallest unit for the asset, such as satoshi for Bitcoin and wei for Ethereum.)

Syntax:

sudo casp_setup_wallets \
--blockset-token <arg> \
--infura-project-id <arg> \
--log-level <arg>

The parameters are described in the following table.

Parameter Required Description
blockset-token optional Blockset API token.
infura-project-id optional Infura project ID for Ethereum.
log-level <arg> optional Change the default og level



For example, to configure BTCTEST:

sudo casp_setup_wallets \
--blockset-token abcd1234abcd1234abcd1234abcd1234 \
--infura-project-id dcba4321dcba4321dcba4321dcba4321

Response:

Wallets configuration was updated, wallets service must be restarted.

After running the script, restart the service with this command:

sudo service casp.wallets restart

You can then open the log file and make sure you see messages like these:

info: Using Blockset : BTC.main
info: Using Blockset : BTC.test3

Troubleshooting
For both Bitcoin and Bitcoin Testnet, when retrieving the balance on a BIP44 vault with sub-accounts, you may encounter a situation where the Blockset BTC/BTCTEST token limit is reached. It returns an error code such as:
API calls limits have been reached.

The following parameters can be specified in the configuration file, production.yaml, to control the behavior of Blockset requests.
Blockset:
maxConcurrentRequests: 10 // # of requests allowed to be sent at once to Blockset
minRequestTimeMs: 100 // The minimum time between one request and another
maxRetries: 10 // # of times to retry once a request to Blockset fails with 429 - too many requests

Ethereum and Ethereum Testnet

  • Installation of these wallets requires NodeJS.
  • Warning
    You must set an Infura token for both ETH and ETHTEST.

  • Optionally, update the fee settings. The file /opt/casp/providers/wallets/config/default.yaml contains the default fees. The file /opt/casp/providers/wallets/config/production.yaml lets you define your own fees.
  • If needed, modify the type of test network, Set network = "ropsten". It can have one of the following values: ropsten, kovan, or rinkeby
  • Restart the service after any of these changes.

    sudo service casp.wallets restart

ERC-20

ERC-20 is supported by the ETH/ETHTest wallet. To check an ERC-20 balance or create a transaction, add contractAddress to the request (refer to the CASP API reference).

A plain text name can be assigned to a contract address in the /opt/casp/providers/wallets/config/production.yaml file. The Web Interface uses these names when displaying transaction information. The configuration uses these fields:

  • address - Token contract address.
  • name - Name displayed to the user.
  • symbol - Token currency symbol.
  • decimals - Number of decimal digit precision supported by the token.

The following is an example showing the wallet setup for an Ethereum test network along with the ERC-20 token plain text names. It defines the name My BOKKEY for a contract address.

Wallets:
ETHTEST-ROPSTEN:
  walletType: ethereum
  name: Ethereum Ropsten
  signCompleteCallbackUrl: 'http://localhost:3000/ethtest-ropsten/api/v1.0/callback/withdrawals/complete'
  infura:
    network: ropsten
    token: 'abcd1234abcd1234abcd1234abcd1234'
  erc20Tokens:
    - address: "0xabcd1234abcd1234abcd1234abcd1234abcd1234"
    name: "My BOKKEY"
    symbol: "BOKKEY"
    decimals: 18

Ripple

Support for Ripple (XRP) can be enabled with the following:

  1. Edit the file /opt/casp/providers/wallets/config/production.yaml.
  2. To enable the Ripple test network, uncomment (or add) these lines:
  3.     RIPPLE-ALTNET:
            disabled: false

  4. To enable the Ripple main network, uncomment (or add) these lines:
  5.     RIPPLE-MAINNET:
            disabled: false

    Note
    The indentation for these lines is critical for parsing the yaml file correctly.

Start the CASP Services

This procedure configures the CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. services.

  1. Start the service.

    sudo systemctl start casp.tomcat

  2. To check the status of a service on the system, use the status command:

    sudo service casp.tomcat status

  3. If you are using the built-in CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. wallet (BTC or ETH), start the service.

    sudo systemctl start casp.wallets

Configure Apache

Note
You can access CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. over HTTPS using Apache. By default, there is an Apache self-signed certificate that can be used for testing. This certificate must be replaced for production. To replace the certificate, update the CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. configuration for Apache in /etc/httpd/conf.d/casp-apache.conf. See the Apache documentation for more information.

  1. Configure Apache to start on boot.
    • For CentOS:

      sudo systemctl start httpd
      sudo systemctl enable httpd

    • For Ubuntu:

      sudo systemctl start apache2
      sudo systemctl enable apache2

  2. To verify that Apache is running, navigate to http://<server-ip>. Replace <server-ip> with the IP address of the server. You should see an Apache landing page if it is running.
  3. To configure Apache to only use HTTPS:
    1. Edit /etc/httpd/conf.d/casp-apache.conf.
    2. Comment out all the lines for the HTTP virtual host. This is the section of the configuration file that starts with <VirtualHost *:80> and ends with </VirtualHost>.
    3. Edit /etc/httpd/conf.d/httpd.conf.

      Note
      The location and name of the httpd.conf file depends on the OS and version. For example, on Ubuntu, the file is /etc/apache2/apache2.conf.

    4. Comment out the Listen 80 line in httpd.conf.
  4. Restart Apache:

    sudo systemctl restart httpd

Configure Logs

Use the following procedure to enable trace logging. Unbound support may ask you to create this log if you encounter an issue with UKCClosedUnbound Key Control - The name of Unbound's key management product..

  1. Edit /etc/unbound/log4j/casp.xml.
  2. Find the following line:
  3. <Logger name="TRACE" additivity="false" level="off">

  4. Change it to:
  5. <Logger name="TRACE" additivity="false" level="debug">

Push Notifications (optional)

The Unbound CASPClosedUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. Signer app (see Mobile App) uses Google firebase for push notifications on iOS and Android.

Note
Enabling push notifications is optional. The mobile app is fully functional without push notifications, but the user has to open the app to manually check if there are new approval requests.

A script is provided to setup the firebase token. This script checks the UKCClosedUnbound Key Control - The name of Unbound's key management product. health and then stores the firebase push token in UKCClosedUnbound Key Control - The name of Unbound's key management product.. The token is used to send push notifications to the Mobile App.

Syntax:

sudo casp_setup_fb_token \
--token=<TOKEN>

The parameters are described in the following table.

Parameter Required Description
token required The push notification token.

The response is:

UKC health check was successful.
Firebase token set up successfully.

After running the script, restart the Tomcat service.

sudo service casp.tomcat restart