Skip to content

KeyChain Protocol

Jump to bottom
Avvrik edited this page Jan 28, 2019 · 64 revisions

Introduction

KeyChain is a standalone app for signing transactions and generating key pairs. It stores private keys in an isolated environment with three-layer security protection making it extremely difficult for loggers, debuggers or spyware to intercept them. KeyChain supports transactions from/to various blockchains, including Ethereum and Ethereum classic, Litecoin, Bitcoin, Bitcoin Cash, and Bitshares.

You can integrate KeyChain into your project as a service through pipe or websocket. For quick step-by-step guides see Pipe integration guide and WebSocket integration guide which can be found in the corresponding API.

Here you can find installation guides for macOS, Windows, and Linux.

Test the KeyChain commands on the demo page here.

You can find error descriptions in the Troubleshooting section.

Protocol

Sign transaction in hex format

NB: You can sign transactions in hex or hash format. For example, for Ethereum transaction, you do not need to pass chainid as a parameter because it is incorporated in the hex.

NB: Please remember that you need to insert your own key name in the parameters when copying the requests!

JSON Request
{
  "command": "sign_hex",
  "params":
  {
    "chainid": "de5f4d8974715e20f47c8bb609547c9e66b0b9e31d521199b3d8d6af6da74cb1",
    "transaction": "871689d060721b5cec5a010080841e00000000000011130065cd1d0000000000000000",
    "blockchain_type": "array",
    "keyname": "my key",
    "unlock_time": 45 
  }
}
Command

sign_hex

Query parameters
Parameter Type Description
chainid string Optional parameter for Array and Bitshares-like blockchains. Chainid is the hash of a genesis file used to identify the chain.
transaction string Hex representation of the transaction.
blockchain_type string Inserts the name of blockchain you’re using. Possible options: Array, Bitcoin, Ethereum, Bitshares.
keyname string Inserts the mnemonic label of your key.
unlock_time integer This parameter is experimental and optional! If this parameter is defined and if it is greater than zero, it unlocks the key for a set number of seconds. While the key is unlocked, the transactions will be signed without the user's approval.
Response format
Field name Type Description
result hex string 65-byte singature in hex-string format.
Response example
{"result":"6cc47faa3778d15efeb470cd4154fdceb80633beaed15f0816d93951ffd7629a5fae3fe83c030f5f8a0cea82c1907f85418b93e820ea3b043c116053afae20a300"}

Sign hash of transaction

This request is suited best for advanced users who are eager to work on a low level. You should have knowledge of how to calculate hash of transaction, given the type of blockchain, and know the type of signature and its packaging.

NB: Please remember that you need to insert your own key name in the parameters when copying the requests!

JSON Request
{
  "command": "sign_hash",
  "params":
  {
    "sign_type": "VRS_canonical",
    "hash": "fe5e4a8974715e20f47c8bb609547c9e66b0b9e31d521199b3d8d6af6da74cb1",
    "keyname": "my key"
  }
}
Command

sign_hash

Query parameters
Parameter Type Description
sign-type string Customizes the way secp256 library is used by choosing one of its arguments through sign-type parameter. It has two possible value options: RSV_noncanonical and VRS_canonical. Default value is RSV_noncanonical. Prefix RSV/VRS means signature struct: [R, S, v] or [v, R, S].
hash string Hash calculated from the transaction. It can be the result of the first calculation or the second - depending on the type of the blockchain. For example, Bitcoin uses two calculations: to sign a bitcoin transaction you need to transmit the final (second) hash. Ethereum and Array make only one calculation to get the hash.
keyname string Inserts the mnemonic label of your key.
Response format
Field name Type Description
result hex string 65-byte signature in hex format.
Response example
{"result":"62826b9c7b6bbfcd89456c1e8068e141d6a46b2c1c0166ed25ba8ad6ede320f4454ff116d13f4e679e8224fcca49f49d50c279ed88513a1db7185946e26811ab01"}

Calculate public key from private key

NB: Please remember that you need to insert your own key name in the parameters when copying the requests!

JSON Request
{ 
  "command": "public_key",
  "params": 
  {
    "keyname": "my key"
  }
}
Command

public_key

Query parameters
Parameter Type Description
keyname string Inserts the name of the key from which you want to calculate a public key.
Response format

64-byte public key. The length of the public key depends on the type of the blockchain. For example, in Ethereum, the length of a public key is 64 bytes.

Field name Type Description
result hex string 64-byte public key.
Response example
{"result":"a7aea4bd112706655cb7014282d2a54658924e69c68f5a54f2cd5f35c6fcba9b610d6ae8549f960ae96e23ffc017f305c1d8664978c8ba8a1cc656fd9d068ef5"}

Lock all unlocked keys

This command protects you from any hostile intervention into the KeyChain while you have left your computer without supervision.

JSON Request
{
  "command": "lock"
}
Command

lock

Query parameters

No

Response format
Field name Type Description
result bool bool result.
Response example
{"result":"true"}

Unlock private key

Unlock your key when you are ready to use it.

NB: This parameter is experimental! Allowing the user to sign transactions without extra authorization is not secure and can be harmful. If unlock_time is greater than zero, you will see an insecure action warning. We do not recommend to use it. Although it might be needed if you want to speed up signing transactions.

NB: Sign_hex and sign_hash commands assume implicit unlocking of your keys.

NB: Please remember that you need to insert your own key name in the parameters when copying the requests!

JSON Request
{
  "command": "unlock"
  "params":
  {
    "keyname": "my key",
    "unlock_time": 45
  }
}
Command

unlock

Query parameters
Parameter Type Description
keyname string Inserts the name of the key you want to unlock.
unlock_time integer When this parameter is specified, it unlocks the key for a set number of seconds. While the key is unlocked, the pass entry window will not appear and the transactions will be signed without the user's approval.
Response format
Field name Type Description
result bool bool result.
Response example
{"result":"true"}

Get information about the current KeyChain version

You can request the details of the current KeyChain version you are using.

JSON Request
{"command":"about"}
Command

about

Query parameters

No

Response format
Field name Type Description
result json object version details as a json object with the following parameters.
version string number of the current version.
git_revision_sha string hash of the commit.
git_revision_age string age of the commit.
compile_date string time of compilation.
boost_version string required version of the boost library.
openssl_version string required openssl version.
build string required operating system.
Response example
{"result":{"version":"0.9.114","git_revision_sha":"59861769dca634d08d5442cb0074d40d8f544e66","git_revision_age":"9 minutes ago","compile_date":"compiled on Dec 12 2018 at 08:11:44","boost_version":"1.66","openssl_version":"OpenSSL 1.1.1  11 Sep 2018","build":"linux 64-bit"}}

Get the number of the current KeyChain version

You can request the number of the current version you are using.

JSON Request
{"command":"version"}
Command

version

Query parameters

No

Response format
Field name Type Description
result string current version number which has the form of "[major].[minor].[build number]".
Response example

{"result":"0.9.114"}

Clone this wiki locally