Using Fortanix Custodial Warm Wallet Solution

1.0 Introduction

This article describes how the Fortanix “Custodial Warm Wallet” solution provides an additional layer of security to crypto-currency wallets by incorporating a second factor of authentication (2FA) for transaction signing using Time-based One-Time Passwords (TOTP). This solution comprises a plugin that is securely deployed inside Fortanix Data Security Manager (DSM) Software-as-a-Service (SaaS). This solution also comprises a Node.js SDK that makes it easy for wallet backends to interact with Fortanix DSM.

1.1 Fortanix Custodial Warm Wallet Plugin

The Fortanix “Custodial Warm Wallet” solution implements a Warm Wallet as a Fortanix DSM plugin. The warm wallet supports secure second-factor authentication (2FA) using TOTP, secure key management, and secure transaction signing that enables B2C crypto-currency businesses to ensure that customers’ assets are not transferred without their explicit consent.

The plugin is protected by a quorum policy that involves multiple admin users. Once deployed, the plugin code cannot be modified without explicit permissions from multiple administrators.

The plugin performs the following operations:

• Registers users for 2FA using TOTP
• Derives the public key
• Signs data or Ethereum transaction

2.0 Setup

2.1 Create a Fortanix DSM Group

1. To use the Fortanix “TOTP ETH Signer” plugin in Fortanix DSM, you must first create a Fortanix DSM group, and add the Plugin to this group. Figure 1: Import plugin
   Refer to the User’s Guide: Plugin Library for steps to access and install the plugin from the Fortanix DSM Plugin Library.
   Figure 2: Import plugin
2. Copy the UUID of the plugin. When using the “fortanix-web3-eth-accounts” SDK, the environment variable signerId is assigned this UUID. Figure 3: Plugin UUID

2.2 Configure a Quorum Policy for the Group

After creating the Fortanix DSM group and adding the “TOTP ETH Signer” plugin to this group, configure a Quorum Policy for the group to protect the plugin. This will ensure that the plugin code cannot be modified without the approval of the Group Administrator.

1. Go to the detailed view of the group, and click the INFO
2. In the Quorum approval policy section, click ADD POLICY to add a new quorum policy.
3. Configure the Quorum approval policy and click SAVE POLICY. Figure 4: Configure Quorum approval policy

2.3 Create an App In Fortanix DSM

Create an app in Fortanix DSM for the Ethereum Signer and copy the app’s API KEY. When using “fortanix-web3-eth-accounts” SDK, the API Key of this application is used as the value of the environment variable signerAccessToken to interact with Fortanix DSM for signing the crypto transactions. Figure 5: Create an app and copy the API key

2.4 Generate a Master Key

The “TOTP ETH Signer” plugin is paired with a MASTER_KEY. To use the plugin in Fortanix DSM, you must first manually generate this MASTER_KEY and initialize the plugin.

You may use the following JavaScript code snippet to generate a master key:

const bip39 = require('bip39')
const bitcore = require('bitcore-lib')
const bitcoin = require('bitcoinjs-lib')
const bip32utils = require('bip32-utils')

let mnemonic = bip39.generateMnemonic()
let seed = bip39.mnemonicToSeedSync(mnemonic)

var xprv = bitcore.HDPrivateKey.fromSeed(seed);
console.log("MASTER_KEY: " + xprv.xprivkey)

Here is a sample master key:

MASTER_KEY = xprv9s21ZrQH143K31xYSDQpPDxsXRTUcvj2iNHm5NUtrGiGG5e2DtALGdso3pGz6ssrdK4PFmM8NSpSBHNqPqm55Qn3LqFtT2emdEXVYsCzC2U

2.5 Import the Master Key in Fortanix DSM

After manually generating the master key, import this key into Fortanix DSM SaaS as a Secret Raw key in the group created in Section 2.1.

Figure 6: Import master key Figure 7: Master key imported

3.0 Plugin Operations

3.1 User Registration

At user registration time, the TOTP authentication system generates a token.

The plugin must be invoked using walletName (Label) as the input for deriving the shared token during registration. For example: walletName= ‘alice@acme.com’

After the registration is successful:

• A security object of type HMAC is created in Fortanix DSM for the wallet name provided. For example: “totp/alice@acme.com” Figure 8: Security object created
• A TOTP path containing the Secret, Label, and Issuer is returned. For example:
  otpauth://totp/alice%40acme.com?secret=DZKFQ3J4DRUOL7MY2HR7BJ7M&issuer=Fortanix%20DSM
  Where,
  
  • Secret: DZKFQ3J4DRUOL7MY2HR7BJ7M
  • Label: alice@acme.com
  • Issuer: Fortanix DSM
  The Secret, Label, and Issuer information can be used by a QR code generator to generate a QR code. For a quick check, try generating a QR code with the QR code generator such as https://stefansundin.github.io/2fa-qr/.

3.2 Derive the Public Key

Given a walletName and a keyIndex, the plugin can be used to retrieve the corresponding public key. For example, “walletName” : alice@acme.com, “keyIndex”: “0”. The retrieved public key is used by the “fortanix-web3-eth-accounts” SDK to retrieve the account address.

3.3 Sign Data for Ethereum Transaction

The plugin can be used to sign Ethereum transactions or arbitrary data. If a user has been registered for 2FA, a TOTP code must be provided along with the signing request. The transaction is signed using the following input payload:

{
   "operation": "sign",
   "walletName": "string",
   "keyIndex": "number as string",
   "msgHash": "<32-Byte-Message-Hash>"
   "code": "number as string" // code to be provided only if wallet is registered for 2FA.
}

Where, msgHash is a 32-byte message hash that is signed by the “TOTP ETH Signer” plugin. The message hash is generated by the Node.js blockchain SDK.

4.0 Using Node.js Blockchain SDK

4.1 User Registration

During user registration time, the TOTP authentication system generates a token.

The SDK must be invoked using walletName (Label) as the input for deriving the shared token during registration. For example:walletName= 'alice@acme.com'. See the example code here.

After the registration is successful:

• A TOTP path containing the Secret, Label, and Issuer is returned.

4.2 Derive the Account Address

Given a walletName and a keyIndex, the SDK can be used to retrieve the corresponding account address. See the example code here.

4.3 Sign Data or Ethereum Transaction

The SDK can be used to sign Ethereum transactions or arbitrary data. If a user has been registered for 2FA, a TOTP code has to be provided along with the signing request. See the example code here.