Overview

The Fireblocks API Co-signer script is offered as a managed, versioned component that you can deploy from the Azure Marketplace. Instead of manually creating an SGX-enabled VM, downloading the script, and manually pairing it with an API user, this solution automates the process. It requires an API user pairing token and the Azure API Co-signer script URL from your Fireblocks workspace.

Co-Signer script

The Azure co-signer script is installed in the home folder of the admin user (e.g. /home/yourname/). You can run the co-signer script to add users, list users, print the public key, add a callback handler, and perform various operations just as you would from the command line. Learn how to add more API users after the API co-signer installation is complete.

Successful deployment

On successful deployment of the Azure co-signer, the API user whose pairing token was used will be paired with the newly deployed API co-signer. The workspace Owner will receive a notification in their Fireblocks mobile app to approve the API user.

Prerequisites

You must have a valid Azure Subscription with permissions to create Confidential Compute VM’s, VNets, Resource Groups, and OS Disk at a minimum. Your subscription must also be registered for Microsoft.Compute, Microsoft.Solutions and Microsoft.Network service providers. 

1. Your Azure Subscription must have Quota limits enabled for Standard_DC4s_v3 VM. If you are unsure, check with your Azure Administrator. You may have to submit a support ticket with Microsoft to increase the quota limits. 
2. Your Azure subscription must have the following permissions:
   • Microsoft.Solutions/locations/operationStatuses/read
   • Microsoft.Resources/deployments/write
   • Microsoft.Network/virtualNetworks/write
   • Microsoft.Network/networkInterfaces/write
   • Microsoft.Compute/virtualMachines/write
   • Microsoft.Compute/virtualMachines/extensions/write

How to deploy the Azure Marketplace Fireblocks API Co-signer

Fireblocks offers a packaged, managed service on Azure Marketplace for deploying a fully functional SGX VM with the API Co-signer in your Azure instance. If you are setting up your first API Co-signer, or if you already have API Co-signers in your Azure instance, you can use this option to deploy a new API Co-signer.

Basics

When deploying a new API Co-signer, under the Basics tab, fill out the following fields:

1. Under Subscription, select or enter your existing Azure subscription where you want to deploy this Co-signer. 
2. Under Resource group, select or create a group that properly organizes your resources within your subscription (i.e. geographic, commercial, sales affiliation, etc).
3. Under Region, select the geographic region where you want your virtual machine to be deployed. 
4. Under Virtual Machine, select a name for your machine that is aligned with your best practices. Here you can also change the machine’s size, depending on your estimate of your projected transaction volume. We recommend DC4S as a minimum, but you may decide to change it based on your expected processing volume. 
5. Under Username, enter a username, and we will create one for you with an admin role, which is necessary for the creation of your API Co-signer and for logging into and fully managing your Azure’s virtual machine. 
6. Alternatively, if you are not interested in a username and password, you can upload a Public key. Once we receive it from you, we will use it to create a virtual machine for you, and you can use this key to log into the machine.  
7. If you decide to go with a username, enter and confirm a Password of your choice. The password must meet the specifications listed on the marketplace. 
8. Under Managed application, which is where we package all of your resources (the VM, Virtual network, storage), enter the name of your managed application (just as you entered the name of your Subscription above). 
9. Similarly, under Managed resource group, enter the name of your Managed resource group (just as you entered the name of your Resource group above). 
10. Select Next to move on to the next tab. 

API Co-Signer settings

This tab requires you to access your Fireblocks console. Under the API Co-Signer settings tab, fill out the following fields:

1. If you have not done so already, create an API User in your Fireblocks console. Remember to check the “First user on this machine” option. Once your API User has been created and approved by the workspace owner, your pairing token is generated in the Fireblocks console. Copy it from your workspace and enter it under Pairing token from API user is Fireblocks Console. 
2. Go to the Settings tab in your Fireblocks console and copy the Azure Co-signer URL. Under the Azure Co-signer script URL from the Fireblocks Console, paste the URL you copied from your workspace. Remember to enclose the URL in double quotes. 
3. The next two fields, Callback Handler URL and the Public key for the callback handler are optional. To set them up, you need to enter the URL and Public key you had created in advance for the callback handler. If you opted for configuring a callback handler at this stage, note that you will still have to login to this virtual machine to export the co-signer public key which your callback handler will need to use for validating the payload. 
4. Select the Review + Create tab to finalize the process. 

Review + Create 

Under this section you can review all of the information you provided in the previous sections and confirm they are accurate, or go back to modify whatever needs correction. 

If everything looks good here, select Create and the Azure Marketplace solution will initiate the creation of the Azure SGX API Co-signer. This process will take a few minutes and the workspace owner will receive a notification to approve the API Co-signer, if everything goes well. 

If the deployment fails, you will see an error on the Azure Marketplace portal along with details on its root cause. Refer to the Troubleshooting section below for potential issues that could cause such a failure. 

Troubleshooting 

Since the solution is deployed on your Azure instance, a wide range of issues may occur depending on your configuration. Here are some common issues: 

1. Quota limits on your subscription may prevent the provisioning of Standard_DC4s_v3 VM. You may have to request an increase in quota limits or open a support ticket with Microsoft to increase the quota limits. 
2. Review the Azure deployment logs for any permissions-related errors. Learn more about resolving these errors in the official Microsoft Azure documentation.
   • Make sure your subscription has Microsoft.Compute, Microsoft.Solutions and Microsoft.Network registered.
   • Your subscription should also have permission to create resource groups.
   • Your Azure subscription should have these permissions:
     • Microsoft.Solutions/locations/operationStatuses/read
     • Microsoft.Resources/deployments/write
     • Microsoft.Network/virtualNetworks/write
     • Microsoft.Network/networkInterfaces/write
     • Microsoft.Compute/virtualMachines/write
     • Microsoft.Compute/virtualMachines/extensions/write
3. Check if your pairing token has expired. If it has, renew the token and try again.
4. The API Co-signer script URL must be entered with opening and closing double quotes.
5. If you modified the default VM, make sure you selected an SGX-enabled VM.
6. Log a ticket with Fireblocks Support and attach the *_run.log files from the /var/lib/waagent/custom-script/download/0 folder.
7. You may need to delete the VM and any resources created during the deployment of the solution.