Overview

The AWS-compatible API Co-Signer automates transaction signing, wallet approvals, and other approvals initiated via the API. AWS EC2 instances with Nitro allow the same functionality with higher security and are now the recommended AWS service for deploying Fireblocks API Co-signers.

The AWS-compatible API Co-Signer utilizes the Customer Managed Key (CMK) within the AWS KMS service to encrypt the secrets.key file. The secrets.key file is used to encrypt the API Co-Signer’s secrets database which stores the following data:

• The set of keys required for approving transactions according to Transaction Authorization Policy (TAP) rules and various administrative configurations
• Your MPC key share used to sign transactions.

Each API Co-Signer can be optionally configured to work with a unique API Co-Signer Callback Handler, an HTTPS server that can approve or reject transaction signing and configuration change requests based on custom logic implemented by the customer.

API Co-Signer transaction flow

The process for generating and signing a Fireblocks transaction using the Fireblocks REST API service and the API Co-Signer is as follows:

1. An API transaction request is made to the Fireblocks REST API service. A new transaction is submitted via this API endpoint; the transaction is generated on the Fireblocks backend.
2. The transaction passes through your transaction authorization policy and, if approved, continues to the next step.
3. The transaction is sent to all Co-Signers for signing.
4. The AWS Co-Signer receives a request to sign the transaction.
5. If there is no callback handler setup, the transaction continues to step 7.
6. If the callback handler is set up, the API Co-Signer sends a secure approval request to the callback handler.
7. The callback handler responds, either approving or rejecting the transaction.
8. Upon approval, the AWS Co-Signer engages with the Co-Signers on Fireblocks to start a mutual signing process for the transaction.

API Co-Signer requirements

To set up an API Co-Signer, you must first hold an API key with signing permissions. Please follow these instructions to set up your API key.

The API Co-Signer can be provisioned together with the Callback Handler. The Callback Handler processes POST requests and responds with an approval or rejection response.

For more details on response requests and structure, learn more about API Signer Callback in the developer documentation.

AWS and API Co-Signer setup

Follow the steps below to configure your AWS Key and set up your API co-signing software.

Step 1: Create CMK using AWS Key Management Service (KMS)

AWS KMS helps you centrally manage and securely store your keys.

1. Open the KMS console and select Create a key.
2. Under Configure key, select the following options:
   • Key type: Symmetric
   • Key Usage: Encrypt and decrypt
   • Key Material Origin: KMS
   • Regionality: Single-Region key or Multi-Region key (use Multi-Region if the EC2 instance is located in a different region)
3. Select Next.
   
4. Alias: Set a display name for the key
5. Description & Tags: Optional
6. Select Next.
   
7. Key administrators: Choose the role that you would like, or leave this section empty.
8. Select Next.
   
9. Key usage permissions: This can remain empty.
10. Select Next.
11. Review and Confirm.
12. Select the Key ID and then copy the Key ARN for later usage:
    

Step 2: Create an IAM policy 

You manage access in AWS by creating policies and attaching them to IAM identities (users, groups of users, or roles) or AWS resources. A policy is an object in AWS that defines an identity or resource's permissions. AWS evaluates these policies when an IAM principal (user or role) makes a request. Permissions in the policies determine whether the request is allowed or denied.

1. Open the Identity and Access Management (IAM) console.
2. On the left side menu, select Access Management > Policies.
3. Select Create Policy.
   
4. Switch to "JSON" view and paste the following JSON file into the editor. Make sure to replace the Resource value of the Statement array with your CMK ARN from Step 1: Create CMK using AWS Key Management Server.
   

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "VisualEditor0",
               "Effect": "Allow",
               "Action": "kms:Decrypt",
               "Action": "kms:Encrypt",
               "Resource":"<YOUR_CMK_ARN_HERE>"
           }
       ]
   }

   
   
5. Select Next: Tags.
6. Tags: Optional
7. Select Next: Review.
8. Review Policy: Enter a Name and select Create Policy.

Step 3: Create an IAM role

You can use IAM roles to delegate access to your AWS resources. With IAM roles, you can establish trust relationships between your trusting account and other AWS trusted accounts.

• The trusting account owns the resource that requires access.
• The trusted account contains the users who need access to the resource.

Please note that for the instance metadata version, use V1 and V2.

1. Open the Identity and Access Management (IAM) console.
2. On the left side menu, select Access Management.
3. Select Roles.
4. Select Create Role.
   
5. Type of trusted entity: AWS Service
6. Use Case: EC2
7. Select Next: Permissions.
   
8. Attach Permissions Policy: Search for the policy created in Step 2: Create an IAM policy and enable the checkbox.
   
9. Select Next: Tags.
10. Tags: Optional
11. Select Next: Review.
12. Review: Enter a Name and select Create Role.

Step 4: Create an EC2 instance

1. Open the EC2 Dashboard.
2. Select Launch Instance.
3. Choose an Amazon Machine Image (AMI): Search for "Ubuntu Server 20.04" and select Select.
   
4. Choose an Instance Type: c5.large (2 vCPUs and 4GiB of Memory)
   
5. Select Next: Configure Instance Details.
6. IAM role: Select the IAM Role created in Step 3: Create an IAM role.
7. Select Review and Launch.
8. Review Instance Launch: Review and select Launch.
9. Make sure the machine meets the following requirements:
   • No inbound connections
   • Outbound - only port 443
   • The installation phase requires Docker registry, auth port 443 and 5000 for transport.
   • Controlling network access to your instances is highly recommended. For example, configure your VPC and security groups appropriately. For more information, see the AWS documentation for controlling network traffic.
   • Securely manage the credentials used to connect to your instances.

Step 5: API Co-Signer software installation

On the API Co-Signer machine:

1. Enter root mode:
   

   sudo - i

2. Use the steps below to copy a link to the API Co-Signer script file from your Fireblocks Console. If you have any issues with these steps, please contact Fireblocks Support.
   1. 1. Go to Settings > General.
      2. Under Download co-signer script select the Copy icon to copy the AWS KMS script file's URL to your clipboard.
         
3. Enter the command:

   curl -o cosigner "<<Download Link>>"

4. Change the script's permissions to be executable:
   

   chmod +x cosigner

5. If you plan to set up an API Co-Signer Callback Handler place either the TLS certificate of the callback handler in a file named certificate.pem or a copy of the public key under the same folder as the CLI script. Learn more about configuring an API Co-Signer with a callback handler.
   1. Optionally enter the Callback URL. This is the HTTPS server base URL of the API Co-Signer Callback Handler.
      

      Please enter callback URL (if using callback URL, else empty)

   2. The script will ask to select an authentication method:
      

      Please select one of the callback authentication options: (1)-PUBLIC KEY (2)-certificate

      • (Recommended method) If you choose PUBLIC KEY (more information), paste your public key and press return:

        Please paste your callback public key

        Note

        This authentication method is supported for API Co-Signer version 1.1.1 and greater.

      • If you choose a certificate (more information), the script can either fetch the certificate from the Callback Handler URL, or you can paste the certificate.

        Would you like to try to fetch the certificate for <URL> from the web server(y/n)?

        • If you enter "n" to choose no, you will be requested to paste your certificate:
          

          Need certificate for domain <URL domain>, please paste your certificate

6. Run the API Co-Signer setup:
   

   ./cosigner setup

7. The CLI script will request you to enter the following inputs:
   • KMS ARN: The CMK ARN created in Step 1: Create CMK using AWS Key Management Server.
   • Pairing Token: This token can be retrieved from the Fireblocks Console admin page accordingly:
     1. As an Admin, log in to your Fireblocks Console and navigate to Settings > Users.
     2. Select the Pending Activation user status.
     3. Select Copy Pairing Token from the context menu. This token is only available for API users assigned a Signer or Admin role that are not paired with a signing device. The pairing token is valid for 1 hour.
   • [Optional] Callback Handler URL: The HTTPS server base URL where the API Co-Signer Callback Handler is or will be available. (See Callback Handler setup for more details.) If you don't have the callback handler URL available at this stage, you can provide it at a later stage as a configuration update.
8. Start the API Co-Signer:
   

   ./cosigner start

9. If you are running the API Co-Signer for the first time, the workspace owner must approve a new MPC key share request from the Fireblocks mobile app, similar to approving any other user with signing privileges.

If you do not plan on using a callback handler, your API Co-Signer should now be available for use.

To configure a callback handler with your API Co-Signer, follow the steps in the API Co-Signer setup article for non-AWS servers, keeping in mind you will be prompted to provide a KMS ARN, the CMK ARN described in step 1 of this article.

Additional Features

See below a list of various use cases and commands for the API Co-Signer. 

Adding additional API users

The API Co-Signer supports signing for multiple API users, either from the same workspace or from different workspaces.

To add another user, please run the following command that will request you to enter the following inputs:

./cosigner add-user

• Pairing Token: As described above.
• Callback Handler URL: As described above.

Configuration Updates

Users can update the callback handler URL (callback_handler_url), by running:

./cosigner callback-update [user id]

The [user id] is optional and only needed if there are several API users paired to the same API Co-Signer. When running the command in this instance, please specify which user’s callback handler URL you would like to update. A complete list of all users can be retrieved by running the following command:

./cosigner list-users

Software Upgrades

Fireblocks notifies all customers when a software update is available.

To update, please run the following command:

./cosigner upgrade

Monitoring

The API Co-Signer is docker-based and uses the docker JSON file driver for logging. The default output of the driver is standard but can be configured to support other logging mechanisms.

To retrieve the API Co-Signer logs, run the following command:

./cosigner logs

The log file is written to the /databases/cosigner/log directory.