Skip to content

KeyChain Protocol

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

You can find error descriptions in the Error Handling section.

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

When you pass a short key name in the create command, you get an exended name which consists of the prefix and first 8 bytes of the hash. After that, you will need to pass it as a value for the keyname parameter.

Field name Type Description Value example
result string extended key name my_key@f9a1554e3f5e30c8

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 chain-id as a parameter because it is incorporated in the hex.

JSON Request
{
  "command": "sign_hex",
  "params":
  {
    "chainid": "de5f4d8974715e20f47c8bb609547c9e66b0b9e31d521199b3d8d6af6da74cb1",
    "transaction": "871689d060721b5cec5a010080841e00000000000011130065cd1d0000000000000000",
    "blockchain_type": "array",
    "keyname": "my_key@f9a1554e3f5e30c8"
  }
}
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@f9a1554e3f5e30c8
Response example
Field name Type Description Value example
result hex string 65-byte singature in hex-string format 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",//default RSV_noncanonical
    "hash": "fe5e4a8974715e20f47c8bb609547c9e66b0b9e31d521199b3d8d6af6da74cb1",
    "keyname": "my_key@f9a1554e3f5e30c8"
  }
}
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
Field name Type Description Value example
result hex string 65-byte signature in hex format 62826b9c7b6bbfcd89456c1e8068e141d6a46b2c1c0166ed25ba8ad6ede320f4454ff116d13f4e679e8224fcca49f49d50c279ed88513a1db7185946e26811ab01

List all key names

All full key names of the private keys that are kept on your computer.

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

list

Query parameters
Response example
Field name Type Description Value example
result JSON array of strings list of key names my key@47f926e22f376478","my key@e67871253c263de0","my key@e755d5b98b6ed747","my key@f9a1554e3f5e30c8"

Calculate public key from private key

JSON Request
{ 
  "command": "public_key",
  "params": 
  {
    "keyname": "my_key@f9a1554e3f5e30c8"
  }
}
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@f9a1554e3f5e30c8
Response example

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 Value example
result hex string 64-byte public key 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
Field name Type Description Value example
result bool bool 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. This is done separately for each particular key. 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@f9a1554e3f5e30c8
Response example
Field name Type Description Value example
result bool bool 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
Field name Type Description Value example
result bool bool result true
Clone this wiki locally