Key Management System for Tatum-powered applications.
Tatum KMS is used to store private keys and mnemonics of the blockchain wallets securely. KMS periodically pulls pending transactions to sign from Tatum Cloud, signs them locally using stored private keys, and broadcasts them to the blockchain.
Tatum KMS generates and stores the private keys and mnemonic in the local file system's encrypted file. The wallet file is encrypted using the AES-GCM-256 cipher.
The most sensitive information in this architecture is the password, which is used to encrypt the file. The password is never passed as a parameter or obtained from the environment variables. There are three ways of entering a password to the KMS:
In this architecture, private keys and mnemonics never leave your perimeter, but they are encrypted if anybody gains access to the file system.
Tatum KMS is shipped via npm. It installs a set of CLI tools and commands to generate and store wallets / private keys securely. NodeJS >=14 and npm@6 is required. Not working on npm@7!!!
npm i -g @tatumio/tatum-kms
To see list of all available commands, please see help.
tatum-kms --help
By default, Tatum KMS runs as a daemon and periodically checks (defaults to once every 15 seconds) any new pending transactions to sign.
tatum-kms daemon
After a successful startup, daemon will require the password to the wallet store. In wallet store, data are encrypted and password is stored only in memory of the daemon.
bash:$ tatum-kms daemon
Enter password to decrypt wallet store:
Wallet store is saved in the home folder of the user in .tatumrc folder, e.g. /home/admin/.tatumrc/wallet.dat
.
To change path to the wallet file, parameter --path
is used.
tatum-kms daemon --path=/path/to/wallet/store/directory/wallet.dat
Another way how to provide the password is via env variable:
TATUM_KMS_PASSWORD=password
To change periodicity, use --period
parameter (in seconds).
tatum-kms daemon --period=5
By default, Tatum KMS checks for pending transaction in every blockchain - BTC, BCH, BNB, LTC, ETH, ETH ERC20s, XLM,
XRP, VET, DOGE, TRON, BSC, CELO, FLOW, XDC, EGLD. To specify concrete blockchains, parameter --chain
is used with
blockchains separated by ,
.
tatum-kms daemon --chain=BTC,LTC,ETH
If you want to verify, if transaction, which is being signed using KMS is yours, you can enable 4-eye-principle.
Add externalUrl
parameter, which will point to your application server. This server will hold list of valid
transactions to sign. Every time the tx is fetched from Tatum to be signed, it is validated against the external server
using simple HTTP GET operation your_external_url/transaction_id
. If response is 2xx, transaction is being signed.
Otherwise transaction is skipped and not signed and you should do the appropriate operations on your end. This parameter
is mandatory for mainnet, to increase security on production environment.
tatum-kms daemon --external-url=http://192.168.57.63
Docker pull: To run as docker container run the following command to pull tatum-kms image
docker pull tatumio/tatum-kms
Navigate to home directory
cd $HOME
Create a .env file in the $HOME directory with the following parameters:
TATUM_API_KEY=XXXXX-YOUR-API-KEY
TATUM_KMS_VGS_USERNAME=XXXXUSERNAME
TATUM_KMS_VGS_PASSWORD=XXXXPASSWORDVGS
TATUM_KMS_VGS_ALIAS=XXXVSGALIAS
TATUM_KMS_PASSWORD=XXXXPASSWORD
TATUM_KMS_AZURE_SECRETVERSION=XXVERSION
TATUM_KMS_AZURE_SECRETNAME=XXSECRETNAME
TATUM_KMS_AZURE_VAULTURL=XXXXVAULTURL
Replace the values with your custom settings
Map Volume: map your home folder to map docker volume to local storage. refer to docker volume mapping for more details https://docs.docker.com/storage/volumes/
Docker run: => Interactive
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
=> Daemon
docker run -d --env-file .env -v $HOME:/root/.tatumrc tatumio/tatum-kms daemon
Example: While the above command will run kms as daemon, you can also use docker run to call specific functions such as:
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
You can shorten the command and use it as follows:
docker run ${COMMON_PARAMS} tatumio/tatum-kms generatemanagedwallet BTC
Where, COMMON_PARAMS can be exported as all the necessary flags for running the container
Tatum KMS is shipped alongside a daemon mode with a set of scripts to communicate with daemon and modify it.
generatewallet chain
- generates wallet for a specific blockchain and echos it to the output. This method does not
add wallet to the managed wallets by Tatum KMS.
bash:$ tatum-kms generatewallet BTC
{
"mnemonic": "urge pulp usage sister evidence arrest palm math please chief egg abuse",
"xpriv": "xprvA1srLWNaGEkhdSJg6cLTMAziUpQcefpu2ZnKH2PXGiXEPKTdVPHjLFp4aZSSqSsaLMNrWXoj6TsyyUqh18T1hbiQkC42aWjXB9HnpmmqrYr",
"xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid",
"testnet": false,
"chain": "BTC"
}
generatemanagedwallet chain
- generates wallet for a specific blockchain and adds it to the managed wallets.
This call echos signatureId of the wallet to be used in API requests to the Tatum API and Extended Public Key of the wallet to pair with Tatum Ledger accounts.
bash:$ tatum-kms generatemanagedwallet BTC
{
"signatureId": "e3015fc0-2112-4c8a-b8bf-353b86f63ba5",
"xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid"
}
storemanagedwallet chain
- stores mnemonic-based wallet for a specific blockchain and adds it to the managed wallets.
This call echos signatureId of the wallet to be used in API requests to the Tatum API and Extended Public Key of the wallet to pair with Tatum Ledger accounts.
bash:$ tatum-kms storemanagedwallet BTC
{
"signatureId": "e3015fc0-2112-4c8a-b8bf-353b86f63ba5",
"xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid"
}
storemanagedprivatekey chain
- store private key of a specific blockchain account and adds it to the managed wallets.
This call echos signatureId of the wallet to be used in API requests to the Tatum API.
bash:$ tatum-kms storemanagedprivatekey BTC
{
"signatureId": "e3015fc0-2112-4c8a-b8bf-353b86f63ba5"
}
getmanagedwallet signatureId
- obtain managed wallet / private key from wallet store.
bash:$ tatum-kms getmanagedwallet e3015fc0-2112-4c8a-b8bf-353b86f63ba5
{
"mnemonic": "urge pulp usage sister evidence arrest palm math please chief egg abuse",
"xpriv": "xprvA1srLWNaGEkhdSJg6cLTMAziUpQcefpu2ZnKH2PXGiXEPKTdVPHjLFp4aZSSqSsaLMNrWXoj6TsyyUqh18T1hbiQkC42aWjXB9HnpmmqrYr",
"xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid",
"testnet": false,
"chain": "BTC"
}
removewallet signatureId
- remove managed wallet from wallet store.
bash:$ tatum-kms removewallet e3015fc0-2112-4c8a-b8bf-353b86f63ba5
getprivatekey signatureId i
- obtain managed wallet from wallet store and generate private key for given derivation index.
bash:$ tatum-kms getprivatekey e3015fc0-2112-4c8a-b8bf-353b86f63ba5 3
{
"privateKey": "L4TUX4PP4X5R9JqotwmHbEYXz3WLrw4FR7FfVmZJoSdMovCV2mEe"
}
getaddress signatureId i
- obtain managed wallet from wallet store and generate address for given derivation index.
bash:$ tatum-kms getaddress e3015fc0-2112-4c8a-b8bf-353b86f63ba5 3
{
"address": "13KvuMxDNT7jDffgSp7QtuLJq6fjpq1Ah7"
}
export
- export 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",
"xpriv": "xprvA1srLWNaGEkhdSJg6cLTMAziUpQcefpu2ZnKH2PXGiXEPKTdVPHjLFp4aZSSqSsaLMNrWXoj6TsyyUqh18T1hbiQkC42aWjXB9HnpmmqrYr",
"xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid",
"testnet": false,
"chain": "BTC"
}
}
Tatum API accepts 3 representations of signatureIdes in its requests:
bash:$ tatum-kms generatemanagedwallet BTC
{
"signatureId": "e3015fc0-2112-4c8a-b8bf-353b86f63ba5",
"xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid"
}
bash:$ tatum-kms storemanagedprivatekey BTC
{
"signatureId": "e3015fc0-2112-4c8a-b8bf-353b86f63ba5"
}
bash:$ tatum-kms generatemanagedwallet BTC
{
"signatureId": "e3015fc0-2112-4c8a-b8bf-353b86f63ba5",
"xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid"
}
error:: TypeError: Cannot read property 'mnemonic' of undefined
You are using wrong signatureId. There are 2 types of signatureId:
This error occurs when you are using your mnemonic based signatureID in the operation, where private key is expected, or you didnt specify an index of the private key to use from the mnemonic based signature ID.