Skip to content

KeyChain Protocol

Jump to bottom
Avvrik edited this page Nov 28, 2018 · 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, 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. For simple installation tutorials for Windows, MacOs, and Linux go to Installation guides.

Protocol

Generate a key pair

JSON request
{
  "command": "create",
  "params":
   {
      "keyname": "my_key",
      "encrypted": true,
      "curve": "secp256k1",
      "cipher": "aes256"
  }
}
Command

create

Query parameters
Parameter Type Description Value example
encrypted string Requests encryption of the key true
curve string Keychain uses elliptic curve algorithm secp256k1
keyname string Create a name for your key. This will be a mnemonic label of the key - not the actual key my_key
cipher string Specifies encryption type (we use aes) and the size of the key in bits aes256
Response example
{"id":0,"result":"my_key@f9a1554e3f5e30c8"}

Sign transaction in hex format

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

JSON Request
{
  "command": "sign_hex",
  "params":
  {
    "chainid": "de5f4d8974715e20f47c8bb609547c9e66b0b9e31d521199b3d8d6af6da74cb1",
    "transaction": "871689d060721b5cec5a010080841e00000000000011130065cd1d0000000000000000",
    "blockchain_type": "array",
    "keyname": "my_key"
  }
}
Command

sign_hex

Query parameters
Parameter Type Description Value example
chainid string Optional parameter for Array and Bitshares-like blockchains. Chainid is the hash of a genesis file used to identify the chain. de5f4d8974715e20f47c8bb609547c9e66b0b9e31d521199b3d8d6af6da74cb1
transaction string Hex representation of the transaction 871689d060721b5cec5a010080841e00000000000011130065cd1d0000000000000000
blockchain_type string Inserts the name of blockchain you’re using. Possible options: Array, Bitcoin, Ethereum, Bitshares. array
keyname string Inserts the mnemonic label of your key my_key
Response example
{"id":0,"result":"6cc47faa3778d15efeb470cd4154fdceb80633beaed15f0816d93951ffd7629a5fae3fe83c030f5f8a0cea82c1907f85418b93e820ea3b043c116053afae20a300"}
Error example
{"id":0,"error":"Error: keyfile could not found by keyname"}
{"id":0,"error":"4 parse_error_exception: Parse Error\nExpected '\"' but read '�'\n    {\"char\":\"�\"}\n    json.cpp:98 stringFromStream\nwhile parsing token ''\n    {\"token\":\"\"}\n    json.cpp:122 stringFromStream\nError parsing object\n    {}\n    json.cpp:217 objectFromStream\n\n    {\"str\":\"{\\n  \\\"command\\\": \\\"sign_hex\\\",\\n  \\\"params\\\":\\n  {\\n    \\\"chainid\\\": \\\"de5f4d8974715e20f47c8bb609547c9e66b0b9e31d521199b3d8d6af6da74cb1\\\",\\n    \\\"transaction\\\": \\\"871689d060721b5cec5a010080841e00000000000011130065cd1d0000000000000000\\\",\\n    \\\"blockchain_type\\\": \\\"array\\\",\\n    \\\"keyname\\\": \\\"my swap online key@e755d5b98b6ed747\\\"\\n  }\\n�}\"}\n    json.cpp:479 from_string"}
{"id":0,"error":"Parse Error"}

Sign transaction in hash format

JSON Request
{
  "command": "sign_hash",
  "params":
  {
    "sign_type": "VRS_canonical",//default RSV_noncanonical
    "hash": "fe5e4a8974715e20f47c8bb609547c9e66b0b9e31d521199b3d8d6af6da74cb1",
    "keyname": "my_key"
  }
}
Command

sign_hash

Query parameters
Parameter Type Description Value example
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]. VRS_canonical
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. fe5e4a8974715e20f47c8bb609547c9e66b0b9e31d521199b3d8d6af6da74cb1keyname
Response example
{"id":0,"result":"62826b9c7b6bbfcd89456c1e8068e141d6a46b2c1c0166ed25ba8ad6ede320f4454ff116d13f4e679e8224fcca49f49d50c279ed88513a1db7185946e26811ab01"}
{"id":0,"error":"Error: keyfile could not found by keyname"}

List all transactions in JSON format

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

list

Query parameters
Response example
{"id":0,"result":["my_key@47f926e22f376478","my_key@e67871253c263de0","my_key@e755d5b98b6ed747","my_key@f9a1554e3f5e30c8"]}

Calculate public key from private key

JSON Request
{ 
  "command": "public_key",
  "kind": "bitshares", // optional
  "params": 
  {
    "keyname": "my_key"
  }
}
Command

public_key

Query parameters
Parameter Type Description Value example
keyname string Inserts the name of the key from which you want to calculate my_key
Response example
{"id":0,"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
Response example
{"id":0,"result":true}

Unlock private key

Unlock your key when you are ready to use it. It will stay active for a certain time which you can specify under ‘set_unlock_time’ command (see below). The active mode set by ‘set_unlock_time’ command allows to make transactions without entering a passphrase only within the same visit. NB: ‘Sign_hex’ and ‘sign_hash’ commands assume implicit unlocking of your keys.

JSON Request
{
  "command": "unlock"
  "params":
  {
    "keyname": "my_key@be5f6e75878b84ba"
  }
}
Command

unlock

Query parameters
Parameter Type Description Value example
keyname string Inserts the name of the key you want to unlock my_key
Response example
{"id":0,"result":true}

Set active timeout

The keys are locked by default. However, you can unlock them for a particular time. This time can be specified under ‘set_unlock_command’.

{
  "command": "set_unlock_time"
  "params":
  {
    "seconds": "300"
  }
}
Command

set_unlock_time

Query parameters
Parameter Type Description Value example
seconds integer Specifies the time of active key mode in seconds 300
Response example
{"id":0,"result":true}
Clone this wiki locally