The OpenAlias Rest Api (OAR) seeks to allow web application to take advantage of OpenAlias while we wait for DNSSec to be implemented everywhere.
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.
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);
}
});
{
"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
}
{
"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
}
{
"STRING": "STRING" // key value pair to represent each property of an OpenAlias record
}
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"
]
}
}
}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"
}
}
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.
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 []:support@outdoordevs.com
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.
- https://openalias.org/#extend
- https://kjur.github.io/jsrsasign/
- https://kjur.github.io/jsrsasign/sample/sample-rsasign.html
- https://github.com/kjur/jsrsasign/wiki/Tutorial-for-Signature-class
- https://kjur.github.io/jsrsasign/api/symbols/KJUR.crypto.Signature.html
- https://developers.google.com/speed/public-dns/docs/dns-over-https
- https://wiki.parity.io/JSONRPC-personal-module#personal_sign
- https://wiki.parity.io/JSONRPC-personal-module#personal_ecrecover
- http://restify.com/docs/home