Skip to content

KeyChain Protocol

Jump to bottom
Avvrik edited this page Mar 7, 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

NB: You can sign transactions in hex or hash format.

JSON Request
{
  "command": "sign_trx",
  "params":
  {
    "transaction": "871689d060721b5cec5a010080841e00000000000011130065cd1d0000000000000000",
    "blockchain_type": "array",
    "public_key": "62826b9c7b6bbfcd89456c1e8068e141d6a46b2c1c0166ed25ba8ad6ede320f4454ff116d13f4e679e8224fcca49f49d50c279ed88513a1db7185946e26811ab01",
    "unlock_time": 45 
  }
}
Command

sign_trx

Query parameters
Parameter Type Description
transaction hex string Hex representation of the transaction.
blockchain_type enumeration string Inserts the name of blockchain you’re using. Possible options: array, bitcoin, ethereum, bitshares.
public_key hex string 64-byte public key in hex format
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.

JSON Request
{
  "command": "sign_hash",
  "params":
  {
    "sign_type": "VRS_canonical",
    "hash": "fe5e4a8974715e20f47c8bb609547c9e66b0b9e31d521199b3d8d6af6da74cb1",
    "public_key": "62826b9c7b6bbfcd89456c1e8068e141d6a46b2c1c0166ed25ba8ad6ede320f4454ff116d13f4e679e8224fcca49f49d50c279ed88513a1db7185946e26811ab01"
  }
}
Command

sign_hash

Query parameters
Parameter Type Description
sign-type hex 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 hex 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.
public_key hex string 64-byte public key in hex format
Response format
Field name Type Description
result hex string 65-byte signature in hex format.
Response example
{"result":"62826b9c7b6bbfcd89456c1e8068e141d6a46b2c1c0166ed25ba8ad6ede320f4454ff116d13f4e679e8224fcca49f49d50c279ed88513a1db7185946e26811ab01"}

Select a key

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

select_key

Query parameters

No

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_trx and sign_hash commands assume implicit unlocking of your keys.

JSON Request
{
  "command": "unlock"
  "params":
  {
    "public_key": "62826b9c7b6bbfcd89456c1e8068e141d6a46b2c1c0166ed25ba8ad6ede320f4454ff116d13f4e679e8224fcca49f49d50c279ed88513a1db7185946e26811ab01",
    "unlock_time": 45
  }
}
Command

unlock

Query parameters
Parameter Type Description
public_key hex string 64-byte public key in hex format
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