Deployment

This page will walk you through the steps needed to deploy your own Virtual Signer. Be sure to visit the sub-pages where we will also cover the topics of logging, monitoring and testing of your new Virtual Signer.

API Keys

You must create an API key for your user account in io.vault to enable the Virtual Signer to register itself in your vaults. To do that, follow these steps.

1. Log in to app.iofinnet.com with your credentials.
2. Click the key icon in the top right corner of the page to open the API keys panel.
3. Click the "Create API Key" button.
4. Enter a name for your API key – this can be anything that helps you remember what it's for.
5. Click "Submit".

The details of your API key will be displayed. This is what we use to fill the EDG_VS_AuthClientId, EDG_VS_AuthClientSecret and EDG_VS_OrgId parameters going forward.

If your Org ID is not displayed on this page, and you are unsure of what it is, please contact your io.finnet representative to ask them for your Org ID for use in the next steps.

Setup Options

The Virtual Signer may run on an Azure Confidential Compute Virtual Machine or on an on-premise server. With both options, the Virtual Signer runs as a Docker container.

Setup Option 1: Microsoft Azure Confidential Computing VM

You may use Azure's Dedicated Hosts offering which supports Intel SGX technology to run containerized confidential virtual machines (VMs). These will ensure that your data is fully protected by a hardware-level secure enclave during rest and execution, protecting you from threats. For more information about Intel SGX VMs for use in Azure confidential computing see this link.

When you launch launch a VM on a Dedicated Host that is equipped with Intel SGX hardware, the CPU will always be the same across reboots. This is important to ensure that the Virtual Signer's encrypted data does not become corrupted.

To setup this way, please follow the guide on the Azure website which will take you through the steps necessary to deploy a host and a compatible VM. Then you will return this guide, once you have SSH access to your VM, to complete the Docker installation outlined below.

📘

Important: Intel SGX Needed

To be able to run the Virtual Signer software properly, you must be using an SGX-supported host like the DCsv2-Type1 with "Intel Xeon E-2288G Processor with SGX Technology" which, at the time of writing, costs $616.85 per month with discounts available if a host is reserved for 1 or 3 years.

You may run a number of VMs on your dedicated host, making this a potentially cost-effective option for running several Virtual Signers isolated from each other, and there is no need to manage any hardware yourself.

More information on Azure pricing is available here and we have written up our own Infrastructure Pricing guide in this documentation.

📘

Important: Data Encryption

The Virtual Signer uses Intel SGX encryption that is bound to the physical hardware CPU that the software is running on. This means that you must use the same physical CPU throughout the entire lifetime of the Virtual Signer once it's started.

With a physical on-premise server, this is already taken care of for you, as the physical hardware will always be the same.

However, with a cloud provider like Azure, you must use a feature like Dedicated Hosts to make sure that you are always running on the same hardware.

Setup Option 2: On-Premise Server

To retrieve a list of processors that support Intel SGX or to inquiry a specific processor, see Intel's Website. Running your own dedicated server will ensure that you control the hardware, and that the hardware always stays the same. It's therefore the most preferred (albeit the most expensive) way to run a Virtual Signer.

Once you have SSH access to your server, return to this guide to complete the Docker installation outlined below.

Docker setup guide

We use Docker Hub Container Registry to distribute the signed Docker images for the Virtual Signer.

You should then be able to pull the latest Docker image with:

$ DOCKER_CONTENT_TRUST=1 docker pull iofinnet/io-vault-virtual-signer:latest

Or a specific version (v0.0.1 in this example) with:

$ DOCKER_CONTENT_TRUST=1 docker pull iofinnet/io-vault-virtual-signer:v0.0.1

The Virtual Signer is distributed as a signed Docker image, and that means that it can be invoked from a Docker Compose file. A sample docker-compose.yml file to do this is shown below.

version: "3.9"
volumes:
  secret-private-keys-volume-1:
services:
  virtual-signer-1:
    container_name: virtual-signer-1
    restart: unless-stopped
    image: iofinnet/io-vault-virtual-signer:latest
    logging:
      options:
        max-file: "5"
        max-size: "10m"
    ports:
      - 8081:8081
    devices:
      - /dev/sgx/enclave:/dev/sgx/enclave
      - /dev/sgx/provision:/dev/sgx/provision
    env_file:
     - docker.env
    volumes:
      - secret-private-keys-volume-1:./vsignerdata

Note how the "image" property refers to the Virtual Signer image pushed to a Docker registry. To use a specific version of the image, like we saw before, replace latest with the version you want to use (like v0.0.1).

Please also be sure to configure your settings in the docker.env file in the file above. Replace the /path/to/your/docker.env with the path to your own docker.env file on your local machine.
This file may be located anywhere on your host machine.

Here's a sample docker.env to use. If you need to add more fields later, the VS will prompt you to do so.

EDG_VS_ENV=dev
EDG_VS_Port=8181
EDG_VS_ApprovalMode=AlwaysApprove

Replace the values in docker.env above with your own, and be sure to update the local path to it in the docker-compose.yml.

To start the Virtual Signer instance run:

$ docker-compose pull && docker-compose up

Or to restart a running instance run:

$ docker-compose pull && docker-compose down && docker-compose up

When it starts, the Virtual Signer checks if InitialDevice has a value in configuration. If so, it checks
if the device already exists. If not, it creates the device. A running instance of the Virtual Signer can have
more than one devices. To create a new device, run:

$curl -v -X POST http://localhost:8181/api/v1/register-vs-device  --header 'Content-Type: application/json' --data-raw '{"DeviceName":"Virtual-Signer-2", "OrgId": "cl123456789"}'

replacing the values for port, device name and organization id. The response will include the device id:

{
    "deviceId": "clgmimg9r114135l02otm0w0zc",
    "deviceName": "Virtual-Signer-2 (0zc)",
    "orgId": "cl123456789"
}

Data Storage and Backup

See the page for Data Storage and Backup.

Logging and Log Rotation

See the page for Logging and Log Rotation.

Prometheus Metrics

See the page for Prometheus Metrics.

Testing the Deployment

See the page for Testing the Deployment.