Unbound NextGen vHSM® Interactive Demo

The Unbound NextGen vHSM® Interactive Demo provides a quick and easy way to evaluate the Unbound CORE solution. CORE is composed of several components that need to be setup to work properly. Therefore, this quick start solution is provided to enable you to launch CORE without any configuration using Docker.

Installation

Use these instructions to get CORE running using Docker.

If you are not registered for Docker, follow the registration process (It is recommended to open this link in a new tab).
Contact Unbound and provide us with your Docker username to get access to the Docker images.
Install Docker.
- For Windows:
  - Install Docker Desktop CE (community edition). It must include Docker Engine version 19.03 or newer. You can get the latest version from Docker.
  - Use the default Docker settings during installation.
- For Linux:
  - Follow the instructions to install Docker Compose.
- For Mac:
  - Install Docker Desktop (community edition) v2.1.0.5 or newer. Follow the instructions to install Docker Desktop.
Download or clone this repository from the main page or click here.
If you downloaded a compressed (.zip) file, uncompress it.
The download contains a folder called ukc-docker. Open a terminal (such as cmd or PowerShell on Windows) and navigate to the ukc-docker folder.

Note: All subsequent commands are run from a terminal from this directory.
Start Docker.
- On Windows and Mac, start the Docker program.
- On Linux, run docker from the command line in a shell with administrator privileges.
Check that Docker is running.

You can check if Docker is running with the command docker info.
- If it returns an error, then it is not running. This error may happen if Docker was run without administrator privileges.
- On success, it returns status information about the Docker installation.
Open a terminal and navigate to the ukc-docker folder.
Run this command to log into Docker:
```
docker login
```
Enter the credentials that you created for the Docker Hub website.

After successful login you see:
```
Login Succeeded
```
The Docker installation uses a settings file, called settings.env. This file is located in the root of the ukc-docker folder that was downloaded in step 6.

Installation works with the default values set in this file, so you do not have to change anything in it. However, you may want take a look at it to see what settings can be configured before running the installation process. The settings are described in the file.
Run Docker to create the UKC container:

Note: If you are restarting or trying to update the demo, refer to Restarting/Updating Docker.
```
docker-compose pull
docker-compose up -V
```
The setup takes several minutes to complete. During this time, Docker creates multiple containers for CASP, CASP database, CASP client, and UKC servers. It also creates the CASP user, client, keys, and more.
Wait until you see a large READY message. This message means that everything is installed and working. You may see some errors during the install process, but as long as you get the READY message, UKC was installed correctly.

Note: Do not close the terminal window. Closing it terminates the Docker containers.

Congratulations! UKC is now running.

Next Step - Explore the vHSM Demo

Open your browser and navigate to http://localhost:8081 (for Windows and Mac) or http://<docker-ip-address>:8081 (for Linux, where docker-ip-address is the server where you installed Docker).

The Web UI provides the following sections:

Tokenization - UKC can be used for tokenization with a format-preserving encryption (FPE) key. This site demonstrates tokenization/de-tokenization of various tokens by UKC using a pre-defined FPE key stored in UKC. The demo use cases include free text, credit card number, USA SSN, and USA phone number.
UKC Admin - access the UKC administration interface, which can be used to view the FPE key details and more. Use these credentials to log in:
- Username: so
- Password: Unbound1!
- Partition: root (or test) For more information on how to use the web interface, see UKC User Interface Guide.
CLI - get access to the UKC client command line interface.
Logs - view the logs for the UKC servers. This can be helpful to view after running tokenization/de-tokenization operations.
Resources - links to more information about UKC, the SDE API, and

Testing Development

Development can be done in one of the following ways:

Unbound UKC Client - contact Unbound for instructions.
UKC clientless provider - see the UKC User Guide for instructions on using the clientless provider. Also, see Using Maven in the UKC User Guide.
REST API - See the UKC User Guide REST API section.

Notes:

Development is supported from the Docker host, but not from other machines.
When using these options, UKC can be accessed at https://localhost:9443/.

Restarting/Updating Docker

To update and restart Docker:

Ensure that the previous session is finished:
```
docker-compose down
```
Get the latest files:
```
docker-compose pull
```
Retart Docker:
```
docker-compose up -V
```

Troubleshooting

docker-compose hangs on startup

If you run docker-compose up -V and after a few minutes you still do not see the READY message, it probably means that there was an error starting up the Docker environment. You may have noticed that there were some error messages in the docker-compose output.

If this happens, follow these steps:

Stop the docker-compose process by pressing Ctrl+c.

Remove any running UKC containers:

docker rm -f ukc-client ukc-ep ukc-partner ukc-aux

Remove existing images:

docker rmi -f unboundukc/ukc-vhsm  unboundukc/vhsm-client

Run docker system prune.
Restart the Docker service by clicking on the Docker icon in the system menu bar (Mac) or system tray (Windows) and choosing Restart, or by running docker restart (Linux).
Run docker-compose pull (in the directory where your UKC docker-compose.yaml file is located).
Run docker-compose up -V

Cannot open the web console

If you cannot open the UKC web console in your browser, you might have port 443 in use by another service.

You can change UKC web console port by editing docker-compose.yml, and replacing the UKC export port with a different port. Ports are specified in this file with a format HOST:CONTAINER. Note that you should only change the HOST port and leave the CONTAINER port as-is. See the Docker documentation for more information.

For example, to change the port from 443 to 9443:

Locate the ukc-client section in the docker-compose.yml file.
Change "443:443" to "9443:443".

Restart the Docker with:

docker-compose down
docker-compose up -V

Use https://localhost:9443/login to open UKC web console.

Virtualization

If you need to turn on virtualization on your Windows device, use these instructions:

Enable Hyper-V using the instructions from Microsoft.
You must enable virtualization in the BIOS on your device.

UKC logs

You can see the UKC log files by logging into the Docker container for the EP and then finding the UKC logs. See here for more information about the UKC logs.

Tips

Installing Docker on CentOS 7

The default Docker installed by yum is an older version of Docker. You can use the technique below to update to a newer Docker version.

sudo yum install -y yum-utils   device-mapper-persistent-data   lvm2
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum -y install docker-ce
sudo systemctl start docker
sudo curl -L \
     "https://github.com/docker/compose/releases/download/1.23.1/docker-compose-$(uname -s)-$(uname -m)" \
     -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Docker License

See here for information about Docker licensing.

Philamericus / Unbound-NextGen-vHSM-Interactive-Demo