Tatum Key Management System (KMS)

Tatum Key Management System (KMS) is a comprehensive solution for building custodial applications. In custodial applications, you control your application’s end-users’ private keys and wallet mnemonics. Blockchain transactions are signed locally, and sensitive data is not sent over the Internet.

With KMS, you can easily build and scale custodial apps, provide the highest level of security for your users, and allow them to use blockchain technology without having to deal with private keys and mnemonics. End-users can simply log in to your app with their credentials, and KMS takes care of the rest.

Tatum KMS on Github

What does KMS do?

KMS runs locally on your server (more on that later) and provides security for generating wallets, addresses, private keys, and signing transactions securely. Your sensitive data is encrypted and stored on your server, so you never have to worry about what would happen if it were somehow intercepted.

When you generate a wallet with KMS, it creates a signature ID that is used in place of the wallet’s mnemonic.
When you generate a private key to an address, it creates a signature ID to be used in place of the private key.

Then, when you send API requests to Tatum you only have to remember to replace two fields:

mnemonic -> signatureId (of the wallet’s mnemonic phrase)
fromPrivateKey -> signatureId (of the private key)

Example: ****In the following mint NFT endpoint example (Solana), there is a fromPrivateKey field on line 9:

curl -i -X POST \
  https://api.tatum.io/v3/nft/mint \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "chain": "SOL",
    "to": "FykfMwA9WNShzPJbbb9DNXsfgDgS3XZzWiFgrVXfWoPJ",
    "from": "FykfMwA9WNShzPJbbb9DNXsfgDgS3XZzWiFgrVXfWoPJ",
    "fromPrivateKey": "3abc79a31093e4cfa4a724e94a44906cbbc3a32e2f75f985a28616676a5dbaf1de8d82a7e1d0561bb0e1b729c7a9b9b1708cf2803ad0ca928a332587ace391ad",
    "metadata": {
      "name": "My NFT.",
      "symbol": "NFT_SYMBOL",
      "sellerFeeBasisPoints": 0,
      "uri": "https://my_token_data.com",
      "creators": [
        {
          "address": "FykfMwA9WNShzPJbbb9DNXsfgDgS3XZzWiFgrVXfWoPJ",
          "verified": 1,
          "share": 10
        }
      ]
    }
  }'

To use the KMS instead, simply replace the fromPrivateKey field with a signatureId field, and enter the signature ID of the private key that was generated by KMS:

curl -i -X POST \
  https://api.tatum.io/v3/nft/mint \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "chain": "SOL",
    "to": "FykfMwA9WNShzPJbbb9DNXsfgDgS3XZzWiFgrVXfWoPJ",
    "from": "FykfMwA9WNShzPJbbb9DNXsfgDgS3XZzWiFgrVXfWoPJ",
    "signatureId": "26d3883e-4e17-48b3-a0ee-09a3e484ac83",
    "metadata": {
      "name": "My NFT.",
      "symbol": "NFT_SYMBOL",
      "sellerFeeBasisPoints": 0,
      "uri": "https://my_token_data.com",
      "creators": [
        {
          "address": "FykfMwA9WNShzPJbbb9DNXsfgDgS3XZzWiFgrVXfWoPJ",
          "verified": 1,
          "share": 10
        }
      ]
    }
  }'

KMS then periodically picks up pending transactions to be signed, signs them, and broadcasts them to the blockchain. Your sensitive data is encrypted and stored within your security perimeter, so you never have to worry about what would happen if it were somehow intercepted.

Four-eye principle

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

The four-eye principle is mandatory on the mainnet to make the production environment more secure. You will find information about how to enable the four-eye principle further in this article.

When the four-eye principle is enabled, you allow only the transactions from your application server to be signed: every time a transaction from Tatum is fetched to be signed, it is validated against the external server using a simple HTTP GET operation:

your_external_url/transaction_id

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

Supported operating systems

You can run KMS on the following operating systems:

macOS: Natively or via Docker
Unix: Natively or via Docker
MS Windows: Only via Docker

We recommend that you run KMS from the Docker image regardless of the operating system used.

Install KMS

To meet the highest security standards, KMS should be installed in a deny-from-all environment.

KMS is shipped as a Node.JS binary, and Node.JS 14+ should be installed on your server.

Steps:

Go to the Tatum GitHub’s KMS page.
Download and install KMS. On your local server
```
npm i -g @tatumio/tatum-kms
```
As a Docker image
```
docker pull tatumio/tatum-kms
```
Turn on the four-eye principle on the mainnet. Add the external-url parameter and set it to your application server. This server should hold the list of valid transactions to sign.
```
tatum-kms daemon --external-url=http://192.168.57.63
```

For more details about installation, see the Readme file in the GitHub repo.

To learn more about how to use KMS, see:

How does KMS work?

Tatum KMS stores all your mnemonics and private keys in a wallet storage file. This storage file is an AEC encrypted file, for which only you know the encryption key.

Every wallet that is stored inside your KMS has a unique identifier, called signatureId. This signatureId is used in communication with the Tatum API and represents the wallet used by the specific operation.

Be aware that there are two types of signature IDs that are generated by KMS:

mnemonic signature IDs
private key signature IDs

The following applies:

Any time a private key is required for a request, you must replace the privateKey field with a signatureId field that contains the signature ID of the private key from the wallet storage.
Whenever there is a mnemonic is required to sign a transaction, you must replace the mnemonic field with a signatureId field containing the signature ID of the mnemonic from the wallet storage.

Tatum KMS also supports integrations to Azure Key Vault, VGS, and AWS Secrets Manager so that you can store your keys and mnemonics there. For more information, see Tatum KMS GitHub pages, where all of the source code is available.

When you generate and store all the wallets you want to work with, you then enable the daemon mode in the KMS. This daemon mode periodically checks for the pending transactions to sign.

Every pending transaction has a signatureId present. When the pending transaction is matched with the wallet storage's specific wallet, it is signed locally and sent to the blockchain. Your wallet data are stored only in memory.

KMS is a command-line tool and provides two modes of operation:

CLI mode is used to generate wallets or private keys, typically for the initial setup and one-time operations
daemon mode periodically pulls pending transactions from the Tatum API, signs transactions locally, and broadcasts the transactions to the blockchain

KMS use cases

KMS can be used to securely sign any transaction with a signatureId instead of a privateKey or mnemonic.

deploy NFT smart contracts
mint NFTs
transfer ERC-20, ERC-721, and ERC-1155 tokens
get a list of pending transactions to sign
complete pending transactions to sign
delete transactions waiting to be signed
any other transaction that requires a private key or mnemonic to be signed

For a full list of API calls available for Tatum KMS, refer to our API documentation.

Tatum KMS in video

PreviousPrivate Keys and Mnemonic Phrases NextUse KMS to Store Private Keys and Sign Transactions on Bitcoin

Last updated 1 year ago