Skip to content

Latest commit

 

History

History
185 lines (148 loc) · 6.2 KB

README.md

File metadata and controls

185 lines (148 loc) · 6.2 KB
Raw

OpenAlias Rest Api

The OpenAlias Rest Api (OAR) seeks to allow web application to take advantage of OpenAlias while we wait for DNSSec to be implemented everywhere.

Performing a Lookup

There is one main endpoint to perform lookups using an HTTP POST request:

https://oar.outdoordevs.com/lookup

The post data should be application/x-www-form-urlencoded and should consist of only a single parameter named "address" and it should contain the domain you want to lookup.

The response body will be a JSON object

{
   "payload": OBJECT,
   "signature": STRING
}

The signature field is signed with the servers private key. This field should be validated with a certificate in your client application. If the signature does not validate then the payload data should not be trusted and your application should report an error.

How to verify a signature

The message to validate will be the contents of the payload field converted to a JSON string with JSON.stringify()

The certificate for the endpoint at oar.outdoordevs.com is located here

import axios from "axios";
let rsa = require('jsrsasign');

axios.post('/api/lookup', {address: address}).then((res) => {
   if (res.data.payload.status === 0) {
      let sig = new rsa.Signature({"alg": "SHA256withRSA"});
      sig.init(certificate); // contents of https://raw.githubusercontent.com/stevemulligan/oar/master/oar.crt
      sig.updateString(JSON.stringify(res.data.payload));
      let isValid = sig.verify(res.data.signature);
   }
});

Payload Object

{
   "status": INTEGER, // 0 means lookup was ok, otherwise there was an error
   "message": STRING, // if there was an error this will explain what happened
   "domain": STRING, // domain name that you are looking up
   "googledns": BOOLEAN, // must be true for result to be considered valid, app should show failure
   "dnssec_valid": BOOLEAN, // must be true otherwise DNSSec not working, app should show failure
   "records": ARRAY, // array of OpenAlias records
}

OpenAlias Record Object

{
   "currency": STRING, // symbol of the currency in the record
   "domain": STRING, // domain name that you are looking up
   "txt": STRING, // raw TXT record in the DNS entry
   "properties": ARRAY, // array of OpenAlias Properties Objects
}

OpenAlias Properties Object

{
   "STRING": "STRING" // key value pair to represent each property of an OpenAlias record
}

Coin Info

The coin info end point returns a permanently cached results from CoinMarketCap api. This is useful to get coin name and and icon.

https://oar.outdoordevs.com/lookup

The post data should be application/x-www-form-urlencoded and should consist of only a single parameter named "symbol" and it should contain a comma separated list of symbols that you want to lookup. Symbols that fail are ignored and not return in the response.

The response body is a json object that is an associative array keyed by coin's symbol and the value is an info object from CMC. The documentation for CMC's info endpoint is here

{
 "BTC": {
   "id": 1,
   "name": "Bitcoin",
   "symbol": "BTC",
   "category": "coin",
   "slug": "bitcoin",
   "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/1.png",
   "tags": [
      "mineable"
   ],
   "urls": {
      "website": [
         "https://bitcoin.org/"
      ],
      "explorer": [
         "https://blockchain.info/",
         "https://live.blockcypher.com/btc/",
         "https://blockchair.com/bitcoin/blocks"
      ],
      "source_code": [
         "https://github.com/bitcoin/"
      ],
      "message_board": [
         "https://bitcointalk.org"
      ],
      "chat": [ ],
      "announcement": [ ],
      "reddit": [
         "https://reddit.com/r/bitcoin"
      ],
      "twitter": [
         "https://twitter.com/Bitcoin"
      ]
   }
  }
}

Running your own REST api

You can setup your own endpoint so that your client applications make requests to your own hardware. You'll want to add a json config file inside the config/ folder, or just edit the defaults.

{
  "app": {
    "key_file": "/etc/ssl/oar.key",
    "key_algo": "SHA256withRSA",
    "key_password": null,
    "port": 8044,
    "cmc_api_file": "/etc/ssl/oar_cmc.key"
  }
}

CMC API Key

You'll need your own CoinmarketCap api key if you want to use the /info endpoint. Place the key in a file in a secure location where the server will be able to access it. Set the path in your config file to point to the location of this file.

Generate Keys

If you want to run your own instance of the OpenAlias Rest Api then you need to generate some keys to use.

sudo openssl req -newkey rsa:2048 -nodes -keyout /etc/ssl/oar.key -x509 -days 365 -out /etc/ssl/oar.crt

writing new private key to '/etc/ssl/oar.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:CA
State or Province Name (full name) []:Ontario
Locality Name (eg, city) []:Ottawa
Organization Name (eg, company) []:Outdoor Devs
Organizational Unit Name (eg, section) []:OpenAlias Rest Api
Common Name (eg, fully qualified host name) []:oar.outdoordevs.com
Email Address []:[email protected]

oar.key is used by the rest server to sign payload data. oar.crt is used by clients calling the REST api to verify the authenticity of the response.

References Used