Using Fortanix Custodial Warm Wallet Solution

  • Updated on Jun 14, 2024
  • Published on Jun 14, 2024
  • 5 minute(s) read

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 () 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.

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

NOTE

  • The name of the plugin used in the Fortanix “Custodial Warm Wallet” solution is “TOTP ETH Signer”.

  • The name of the Node.js SDK used in the Fortanix “Custodial Warm Wallet” solution is “fortanix-web3-eth-accounts”.

  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.  

    Import_plugin.png

    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.

    PluginLibrary.png

    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.  

    PluginID.png

    Figure 3: Plugin UUID

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.  

    QuorumPolicy.png

    Figure 4: Configure Quorum approval policy

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.

AppAPIKey.png
Figure 5: Create an app and copy the API 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)
Bash

Here is a sample master key:

MASTER_KEY = xprv9s21ZrQH143K31xYSDQpPDxsXRTUcvj2iNHm5NUtrGiGG5e2DtALGdso3pGz6ssrdK4PFmM8NSpSBHNqPqm55Qn3LqFtT2emdEXVYsCzC2U

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.

NOTE

The MASTER_KEY file size must be 888 bits.

MASTER_KEY.png
Figure 6: Import master key 
MasterKeyImported.png
Figure 7: Master key imported

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 of type HMAC is created in Fortanix DSM for the wallet name provided. For example: “totp/alice@acme.com”  

    SOCreated.png

    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/.

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.

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.
}
Bash

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.

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.

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

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.

Related articles