Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tatumio/tatum-kms

Unbreakable secure KMS (key management system) integrated to Tatum blockchain infrastructure
https://github.com/tatumio/tatum-kms

blockchain cryptocurrency daemon-mode keymanagment mnemonic wallet-store

Last synced: 3 days ago
JSON representation

Unbreakable secure KMS (key management system) integrated to Tatum blockchain infrastructure

Awesome Lists containing this project

README 

        
# Tatum Key Management System (KMS)

**Tatum Key Management System (KMS)** is a comprehensive solution for Tatum-powered applications.



> **Warning**

>

> Important notice about using KMS with ETH and CELO: Please upgrade to version 6.2.3 or newer (all previous versions depend on https://ethgasstation.info which will stop working from 12.12.2022)



KMS securely stores private keys and mnemonics of blockchain wallets. KMS periodically pulls pending

transactions to sign from Tatum, signs them locally using the stored private keys and mnemonics, and broadcasts them to the blockchain.






KMS supports the following blockchains:

* Algorand (ALGO)

* Bitcoin (BTC)

* Bitcoin Cash (BCH)

* BNB Beacon Chain (BSC)

* BNB Smart Chain (BNB)

* Celo (CELO)

* Dogecoin (DOGE)

* Elrond (EGLD)

* Ethereum (ETH) including ERC-20 tokens

* Flow (FLOW)

* Harmony (ONE)

* Klaytn (KLAY)

* KuCoin Community Chain (KCS)

* Litecoin (LTC)

* Polygon (MATIC)

* Solana (SOL)

* Stellar (XLM)

* TRON (TRON)

* VeChain (VET)

* XinFin (XDC)

* XRP (XRP)



For more information about KMS, see our [user documentation](https://docs.tatum.io/docs/tatum-key-management-system-kms).



## Secure storage

KMS generates and stores the private keys and mnemonic in an encrypted file, `wallet.dat`, in the local file system. This wallet storage file is encrypted using the AES-GCM-256 cipher.



The password that is used to encrypt the wallet storage file is the most sensitive asset in this architecture. The password is never passed as a parameter.



You can enter the password into KMS using either of the following methods:

* Enter the password manually at KMS start. The password is stored in the memory only during the daemon runtime.

* Store the password in [VGS Vault](https://www.verygoodsecurity.com/), [Microsoft Azure Key Vault](https://azure.microsoft.com/en-us/services/key-vault/), or [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/). The password is obtained during KMS start and is stored in the memory only during the daemon runtime.



In this setup, the private keys and mnemonics never leave your perimeter. If someone gains unauthorized access to the file system, they cannot get the private keys and mnemonics because they are encrypted.



## Signature IDs vs. Private keys and mnemonics



Every wallet that is stored inside KMS has a unique identifier called **signature ID**. The signature ID is used in communication with the Tatum API and represents the wallet used by the specific operation.



>**NOTE:** You can have up to 25,000 signature IDs per one blockchain and one Tatum API key. If you exceed this limit,

you get an error message, and KMS stops signing your transactions until you adjust your data to respect the limit.



The Tatum API accepts the following representations of the signature ID in requests:



* A signature ID that represents the **private key** type of a wallet



    In API calls like [/v3/bitcoin/transaction](https://docs.tatum.io/reference/btcgeneratewallet#operation/BtcTransferBlockchain), `signatureId` in the request represents the private key type of the wallet.

    ```

    bash:$ tatum-kms storemanagedprivatekey BTC

    {

      "signatureId": "e3015fc0-2112-4c8a-b8bf-353b86f63ba5"

    }

  ```

* A signature ID that represents the **mnemonic** type of a wallet

    

    In API calls like [/v3/offchain/bitcoin/transfer](https://docs.tatum.io/reference/btctransfer#operation/BtcTransfer), `signatureId` in the request represents the mnemonic type of the wallet.



   ```

    bash:$ tatum-kms generatemanagedwallet BTC

    {

      "signatureId": "e3015fc0-2112-4c8a-b8bf-353b86f63ba5",

      "xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid"

    }

  ```

* A signature ID that represents the **mnemonic**/**index** type of a wallet



    In API calls like [/v3/offchain/ethereum/transfer](https://docs.tatum.io/reference/btctransfer#operation/EthTransfer), the index of the specified private key generated from the mnemonic must be used together with `signatureId`.

   ```

    bash:$ tatum-kms generatemanagedwallet BTC

    {

      "signatureId": "e3015fc0-2112-4c8a-b8bf-353b86f63ba5",

      "xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid"

    }

  ```



## Set up and use KMS on your site

To get KMS up and running on your site on the mainnet, complete the following steps:



1. [Install KMS](#install-kms) on your local environment.

    

    KMS is installed as a set of CLI tools and commands to generate and store wallets and private keys securely.

    You can install KMS from npm or via Docker.

1. Store the existing mnemonics and private keys in KMS, or generate new mnemonics and private keys using KMS.

    

    For more information, see the [KMS commands](#kms-commands).

1. Implement the [four-eye principle](#implement-the-four-eye-principle) by setting up a service to store the IDs of the transactions that need to be signed.



    This is another security level in KMS that verifies that the transactions to sign are yours.

1. [Run KMS in daemon mode](#run-kms-in-daemon-mode) so it can periodically check for transactions to sign.

1. When performing operations that must be signed with the private key or mnemonic (such as transferring funds, minting NFT, and so on), use the KMS schemas to build the body of the API requests as specified in the [API Reference](https://docs.tatum.io/reference/welcome-to-the-tatum-api-reference).

    

    This way, you will be using the signature ID instead of the private key or a combination of the signature ID and the index instead of the mnemonic.



## Install KMS



### Supported operating systems

You can run KMS on the following operating systems:

- **macOS:** Natively or via [Docker](https://hub.docker.com/repository/docker/tatumio/tatum-kms)

- **Unix:** Natively or via [Docker](https://hub.docker.com/repository/docker/tatumio/tatum-kms)

- **MS Windows:** Only via [Docker](https://hub.docker.com/repository/docker/tatumio/tatum-kms)



We recommend that you run KMS from the [Docker image](https://hub.docker.com/repository/docker/tatumio/tatum-kms) regardless of the operating system used.



### Environment variables

Create file `.env` file with the  following parameters and replace the placeholders with your values:  

```

# required

TATUM_API_KEY=XXXXX-YOUR-API-KEY

# one of the following setups is required: password, VGS, Azure, or AWS

# password setup

TATUM_KMS_PASSWORD=XXXXPASSWORD

# VGS setup

TATUM_KMS_VGS_USERNAME=XXXXUSERNAME

TATUM_KMS_VGS_PASSWORD=XXXXPASSWORDVGS

TATUM_KMS_VGS_ALIAS=XXXVSGALIAS

# Azure setup

TATUM_KMS_AZURE_SECRETVERSION=XXVERSION

TATUM_KMS_AZURE_SECRETNAME=XXSECRETNAME

TATUM_KMS_AZURE_VAULTURL=XXXXVAULTURL

# AWS setup

TATUM_KMS_AWS_REGION=us-east-1

TATUM_KMS_AWS_SECRET_NAME=YOUR_KMS_SECRET_NAME

TATUM_KMS_AWS_ACCESS_KEY_ID=AKIAYWGKDBVRGMCASWIE

TATUM_KMS_AWS_SECRET_ACCESS_KEY=ZxDq62BZGyGe2CzwnVjL/IH8NnJG5Fu0isN7wev9

TATUM_KMS_AWS_SECRET_KEY=pwd

# Debug mode. if true/1, it will expose data from signEthKMSTransaction() method to the console

TATUM_KMS_DEBUG_MODE=true/false/1/0

```



### Install KMS from npm

1. Install KMS globally:

   ```

   npm i -g @tatumio/tatum-kms

   ```

   or

   ```

   yarn global add @tatumio/tatum-kms

   ```

1. Use ```.env``` file to configure Tatum KMS   

   1. via ```--env-file=/path/to/.env``` 

      ```

       tatum-kms --env-file=/path/to/.env getaddress 11111111-1111-1111-1111-111111111111 0

      ```  

   1. via environment variables directly

      ```

      TATUM_API_KEY=XXXXX-YOUR-API-KEY tatum-kms --help

      ```

   1. via predefined environment vars on global level

      ```

      export TATUM_API_KEY=XXXXX-YOUR-API-KEY  

      tatum-kms --help

      ```



>**IMPORTANT!** NodeJS >=14 and npm@6 are required. KMS does **not** work on npm@7.



### Install KMS via Docker

1. Pull the `tatum-kms` image:

    ```

    docker pull tatumio/tatum-kms

    ```

1. Navigate to the home directory:

    ```

    cd $HOME

    ```

1. Use pre-created ```.env``` file to configure Tatum KMS via ```--env-file .env```:

1. Map the Docker volume to the local storage (your home folder).

  

    For more details, refer to the [Docker user documentation](https://docs.docker.com/storage/volumes/).



    Once you have mapped the Docker volume, KMS is ready to be run as a Docker container.



To interactively communicate with KMS and run various [KMS commands](#kms-commands), use the `docker run` command:

```

docker run -it --env-file .env -v $HOME:/root/.tatumrc tatumio/tatum-kms --help

docker run -it --env-file .env -v $HOME:/root/.tatumrc tatumio/tatum-kms generatemanagedwallet BTC

docker run -it --env-file .env -v $HOME:/root/.tatumrc tatumio/tatum-kms storemanagedprivatekey BTC

```



>**NOTE:** You can shorten the command syntax and use it as follows:

```

docker run ${COMMON_PARAMS} tatumio/tatum-kms generatemanagedwallet BTC

```

>where `COMMON_PARAMS` can be exported as all the flags necessary for running the container.



## Implement the four-eye principle

To verify whether a transaction to sign with KMS is indeed yours, implement the **four-eye-principle** (also referred to as "4-eye principle"). This principle ensures that pending transactions are controlled in Tatum and in your system.



Every time a transaction from Tatum is fetched to be signed, it is validated against an external trusted server

using a simple HTTP GET operation:



`your_external_url/transaction_id`



If the response is `2xx`, KMS signs the transaction. Otherwise, the transaction is skipped and is not signed, and you should take the appropriate steps on your end to fix the situation.



>**NOTE:** Implementing the four-eye-principle is mandatory on the mainnet to make the production environment more secure.






To enable the four-eye-principle:

1. Set up an application server that will hold the list of valid transactions to sign.

1. Add the `external-url` parameter to KMS and set it to your application server:



    ```

    tatum-kms daemon --external-url=http://192.168.57.63

    ```



## Run KMS in daemon mode

```

tatum-kms daemon

```

or

```

docker run -d --env-file .env -v $HOME:/root/.tatumrc tatumio/tatum-kms daemon

```

When KMS runs as a daemon, it periodically checks for any new pending transactions to sign.



After successful startup, the daemon requires the password to the wallet storage file. The file and the data in the file are encrypted, and the password is stored in the memory only during the daemon runtime.

```

bash:$ tatum-kms daemon

Enter password to decrypt wallet store:

```



Alternatively, you can provide the password via an environment variable:

```

TATUM_KMS_PASSWORD=password

```



### Change the frequency of checking for the pending transactions

Checking for the pending transactions consumes credits from the monthly credit allowance associated with your API key: 1 credit for every 500 signature IDs per API call. For more information about the credits, see [Plans and Limits](https://docs.tatum.io/docs/plans-limits).



By default, KMS checks for the pending transactions to sign every 5 seconds.



To change the frequency of the check, use the `--period` parameter and set it the required number of seconds:

```

tatum-kms daemon --period=15

```



### Change the path to the wallet storage file

By default, the [wallet storage file](#secure-storage) is saved under the `.tatumrc` folder in your home directory  (for example, `/home/admin/.tatumrc/wallet.dat`).



To change the path to the wallet storage file, use the `--path` parameter and set it to the new path:

```

tatum-kms daemon --path=/path/to/wallet/storage/file/wallet.dat

```

### Check for the pending transactions only on some blockchains 

By default, KMS checks for the pending transaction on [all supported blockchains](#tatum-key-management-system-kms).



To check for the transactions only on some blockchains, use the `--chain` parameter and set it to the list of the blockchains to check separated with a comma (`,`):

```

tatum-kms daemon --chain=BTC,LTC,ETH

```



## KMS commands

To see all available KMS commands, refer to the KMS help:

```

tatum-kms --help

```



When KMS runs in [daemon mode](#run-kms-in-daemon-mode), use the following commands to communicate with the daemon and modify it:



* `generatewallet chain` generates a wallet on the specified blockchain (`chain`) and echos it to the output.

    

    This command does **not** add the generated wallet to the wallets managed by KMS.

    ```

    bash:$ tatum-kms generatewallet BTC

    {

      "mnemonic": "urge pulp usage sister evidence arrest palm math please chief egg abuse",

      "xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid"

    }

  ```



* `generatemanagedwallet chain` generates a wallet on the specified blockchain (`chain`) and adds it to the managed wallets.

    

    This command echos the signature ID of the wallet to be used in requests to the Tatum API and the extended public key of the wallet to pair with [virtual accounts](https://docs.tatum.io/docs/virtual-accounts).



    ```

    bash:$ tatum-kms generatemanagedwallet BTC

    {

      "signatureId": "e3015fc0-2112-4c8a-b8bf-353b86f63ba5",

      "xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid"

    }

  ```



* `storemanagedwallet chain` stores a mnemonic-based wallet on the specified blockchain (`chain`) and adds it to the managed wallets.

    

    This command echos the signature ID of the wallet to be used in requests to the Tatum API and the extended public key of the wallet to pair with with [virtual accounts](https://docs.tatum.io/docs/virtual-accounts).

    

    ```

    bash:$ tatum-kms storemanagedwallet BTC

    {

      "signatureId": "e3015fc0-2112-4c8a-b8bf-353b86f63ba5",

      "xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid"

    }

  ```



* `storemanagedprivatekey chain` stores the private key of the wallet on the specified blockchain (`chain`) and adds it to the managed wallets.

    

    This command echos the signature ID of the wallet to be used in requests to the Tatum API.



    ```

    bash:$ tatum-kms storemanagedprivatekey BTC

    {

      "signatureId": "e3015fc0-2112-4c8a-b8bf-353b86f63ba5"

    }

  ```



* `generatemanagedprivatekeybatch chain count` generates and stores the specified number of private keys (`count`) on the specified blockchain (`chain`).

    

    This command is useful when you want to pre-generate a large amount of managed private keys for later use.



    ```

    bash:$ tatum-kms generatemanagedprivatekeybatch BTC 100

    ```



* `getmanagedwallet signatureId` obtains the mnemonic or the private key from the wallet storage file for the wallet associated with the specified signature ID (`signatureId`).



    ```

    bash:$ tatum-kms getmanagedwallet e3015fc0-2112-4c8a-b8bf-353b86f63ba5

    {

      "mnemonic": "urge pulp usage sister evidence arrest palm math please chief egg abuse",

      "xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid",

      "testnet": false,

      "chain": "BTC"

    }

    ```



* `removewallet signatureId` removes the managed wallet associated with the specified signature ID (`signatureId`) from the wallet storage file.



    ```

    bash:$ tatum-kms removewallet e3015fc0-2112-4c8a-b8bf-353b86f63ba5

    ```



* `getprivatekey signatureId i` obtains the managed wallet associated with the specified signature ID (`signatureId`) from the wallet storage file and generates a private key for the specified derivation index (`i`).



    ```

    bash:$ tatum-kms getprivatekey e3015fc0-2112-4c8a-b8bf-353b86f63ba5 3

    {

      "privateKey": "L4TUX4PP4X5R9JqotwmHbEYXz3WLrw4FR7FfVmZJoSdMovCV2mEe"

    }

    ```



* `getaddress signatureId i` obtains the managed wallet associated with the specified signature ID (`signatureId`) from the wallet storage file and generates an address for the specified derivation index (`i`).



    ```

    bash:$ tatum-kms getaddress e3015fc0-2112-4c8a-b8bf-353b86f63ba5 3

    {

      "address": "13KvuMxDNT7jDffgSp7QtuLJq6fjpq1Ah7"

    }

    ```



* `export` exports all managed wallets.



    ```

    bash:$ tatum-kms export

    {

      "e3015fc0-2112-4c8a-b8bf-353b86f63ba5": {

        "mnemonic": "urge pulp usage sister evidence arrest palm math please chief egg abuse",

        "xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid",

        "testnet": false,

        "chain": "BTC"

      }

    }   

    ```  

* `checkconfig` shows environment variables for Tatum KMS (for debugging).



    ```

    bash:$ tatum-kms checkconfig

    Version                          : 6.4.0

    Wallet file path                 : ~/.tatumrc/wallet.dat

    Wallet exists                    : true

    Wallet store type                : LOCAL

    Env file                         : .env

    TATUM_API_KEY                    : d2eb5c******************************

    ...

    ```    



## Common issues

**Error message:**

 ```

 error:: TypeError: Cannot read property 'mnemonic' of undefined

 ```



**Possible reasons:**



* You used a mnemonic-based signature ID but the operation requires a signature ID based on the private key.

* You correctly used the mnemonic-based signature ID but you did not specify the index of the private key.



    KMS generates the private key from the mnemonic that the signature ID holds. To generate the correct private key from the mnemonic, KMS needs to know the [index of the private key](#signature-ids-vs-private-keys-and-mnemonics) to generate (0-2^31-1).