API Keys

Raiinmaker Network EAL secures access to all nodes through HMAC keys, which involve a shared secret key stored both on the client and server. HMAC keys are highly secure, efficient, and allow users to add or revoke access easily.

Using coiin or one of the Raiinmaker Network EAL SDKs, the HMAC authorization headers for requests are generated automatically from the Raiinmaker Network EAL credentials file. This file is usually located at ~/.coiin/credentials (location may vary based on operating system, and is configurable). coiin has commands for managing keys in this file.

Key Management

When creating a new chain, a master key will be generated. As a best practice, Raiinmaker Network EAL strongly recommends storing a node’s master key securely, on paper or a device not connected to the Internet. If a malicious actor steals a master key, it cannot be revoked. Instead of using the master key to make requests, Raiinmaker Network EAL recommends that a user generate a new key for each trusted user or access use case and making use of the nickname feature to track keys with human friendly names. These keys can be revoked at any time if they become compromised.

Creation

To create a new key for use, you can run the following command:

$ coiin creds remote add --nickname "My New Key"
{
  "status": 201,
  "response": {
    "key": "6S0c15MghGrpMwzz9EK2j3huQTFwH1EULdmofGXPDuj",
    "id": "EAYRMSXDOSWY",
    "registration_time": 1573691665,
    "nickname": "My New Key"
  },
  "ok": true
}

After creation, verify that the key is available for use:

$ coiin creds remote get "EAYRMSXDOSWY"
{
  "status": 200,
  "response": {
    "id": "EAYRMSXDOSWY",
    "registration_time": 1573691665,
    "nickname": "My New Key"
  },
  "ok": true
}

To add this key to your local credentials file, simply run the coiin creds local add command with your chain’s public ID and follow the prompt:

$ coiin creds local add "dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr"
ENDPOINT: <Internal ID>.<domain>
HMAC KEY ID: EAYRMSXDOSWY
HMAC KEY: *******************************************
Default EAL set to dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr.
Success. New Credentials written to ~/.coiin/credentials

Default Key

The credentials file for your HMAC keys holds a default chain ID to use. If you want to view or change the default chain, you can use the following commands:

$ coiin creds local default get
dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr

$ coiin creds local default set "sj8mz8RvbJMpXiYd7BACvqMfTExtfhT5zqeCj61ww9q4"
Success. Default has been set to "sj8mz8RvbJMpXiYd7BACvqMfTExtfhT5zqeCj61ww9q4".

Modification

You can update the nickname of your HMAC key on the server side by using the coiin creds remote update command:

$ coiin creds remote update "TZRBPXYRCGSM" -n 'Root Key'
{
  "status": 200,
  "response": {
    "success": true
  },
  "ok": true
}

Deletion

To delete a key that is stored on the server side, run coiin creds remote rm

$ coiin creds remote rm "EAYRMSXDOSWY"
{
  "status": 200,
  "response": {
    "success": true
  },
  "ok": true
}

To delete a key that is stored locally, run coiin creds local rm

$ coiin creds local rm "dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr"
dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr credentials have been deleted on this machine.

Listing

To view a list of all server side stored HMAC keys, run coiin creds remote ls

$ coiin creds remote ls
{
  "status": 200,
  "response": {
    "keys": [
      {
        "id": "EAYRMSXDOSWY",
        "registration_time": 1573691665,
        "nickname": "My New Key"
      },
      {
        "id": "TZRBPXYRCGSM",
        "registration_time": 0,
        "nickname": "Root Key"
      }
    ]
  },
  "ok": true
}

To view a list of all locally stored HMAC keys, run coiin creds local ls

$ coiin creds local ls
{
  "dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr": {
    "auth_key": "<hidden>",
    "auth_key_id": "EAYRMSXDOSWY",
    "endpoint": "undefined"
  },
  "default": {
    "dragonchain_id": "dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr"
  }
}

Raiinmaker Network EAL suggests following all reasonable best practices for secure storage and use of API keys. If you plan to have multiple services interacting with a chain, each should use its own API key so that if the service becomes compromised its chain access can be revoked without disrupting other services. API keys that are not in use or have been compromised should be deleted as soon as possible. Even if you do not suspect that a key has been compromised, you should rotate keys periodically.

You can view Google’s best practices for using API keys can be found here.