Catenis Name Server

This is an implementation of the Catenis Name Service, which is used by Catenis nodes to map their IPFS repository root CID to a hostname so other Catenis nodes can reference it.

The Catenis Name Service

Catenis Name Service serves as a workaround for IPFS' IPNS, which currently does not meet Catenis' performance needs; it takes too long to publish a new name.

Setting up Catenis Name Server

Each Catenis Name Server instance should be assigned an SSH RSA key pair.

Make sure that such keys are saved to the proper config files under the cnsInstance.self key. If necessary, use the following command to generate a new key pair.

ssh-keygen -b 2048 -t rsa -m PEM -f cns1_key

Note: for the purpose of this configuration, the client ID —formatted as <username>@<host-name>— at the end of the public key file generated by the ssh-keygen command is not relevant and should be discarded when copying the public key value.

The required information for accessing the Catenis Name Server instance should then be recorded to a TXT record on catenis.io's DNS by the name cns. That TXT record should contain a JSON with the following keys:

• idx: [Integer] The Catenis Name Server instance index (starting from 1).
• pubKey: [String] The instance's SSH RSA public key.
• port: [Integer] The TCP port on which the server will be listening to incoming connections.
• secure: [Boolean] Indicates whether the connection to the server should be done using a secure link (over HTTPS).

Note: when setting up Catenis Name Server for a non-production environment (i.e., sandbox or development), the name of the TXT record should have a suffix identifying the environment (i.e., cns.sandbox or cns.dev).

The following is an example of such TXT record:

cns TXT {"idx":1,"pubKey":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGVwjPH8Ru5+CSiaXOu50EgB0VQdwzvEvnHpvI+aLMAWFW7tvDjAFctlkUv6Herq7jo0tragdl7munN4PM7cN/HzEI16srEbzFpiovYlBsFciEeFtMjcezO61NPnc5M8sdQj1WKccG9ubMrtcvRIX3MxBSbU2ngYGxqG/65i9NTBmgnrr/3nrXK0N5QiA+wH4QePfZRe+9m6iy3RAPFftUI44yZxw1w7/kxzipiu47NTeaGG+0Oa+3ujjsxNrkzhabuU4wlStaw55/Ynmy8507wTTY2ZPxGXy6K15DE3jkrgumE7UBAgJG5RI712J0VGAbOBEb2jaXDEpH7RIVLX8p","port":8188,"secure":false}

Deploying the application

To deploy the application, issue the command:

npm run predeploy

A tarball named catenis-name-server-<version>.tgz is written to the dist subdirectory.

Note: if deploying the application for a non-production environment (i.e., sandbox or development), use the appropriate alternative npm script (i.e., predeploy-sandbox or predeploy-dev). In that case, the tarball is written to a corresponding subdirectory (i.e., dist/sandbox or dist/dev).

Copy the tarball to the target host and extract its contents, renaming the top-level directory of the extracted contents from package to CtnNameSvr.

tar -xzf catenis-name-server-<version>.tgz && mv package CtnNameSvr

Then change to the top-level directory of the extracted contents (i.e., cd CtnNameSvr), and issue the following commands:

nvm use
npm i

Note: optionally append -g to the npm install command (i.e., npm i -g) to install the application as a global Node.js package. In that case, to execute the application, just issue the command ctnnamesvr.

Starting the application

To start the application, issue the following command from the application's top-level directory (CtnNameSvr):

nvm use && env NODE_CONFIG_ENV='<environment>' CNS_INSTANCE_IDX=<cns_index> node .

Note 1: the term <environment> should be replaced with the appropriate deployment environment; either 'development' (the default, if not set), 'sandbox' or 'production'.

Note 2: the term <cns_index> above should be replaced with the index (starting from 1) of this Catenis Name Server application instance.

Note 3: if the application is installed as a global Node.js package, replace node . with ctnnamesvr.

How it works

Catenis Name Server provides a REST API through which Catenis nodes can reset their own IPFS repository root CID and query for the IPFS repository root CID of other Catenis nodes.

REST API

Authentication

The requests to the Catenis Name Server REST API should be authenticated using the HTTP Signature scheme.

Each Catenis node should be assigned an SSH RSA key pair for signing the HTTP requests. Use the following command to generate such key pair.

ssh-keygen -b 2048 -t rsa -m PEM -f ctn-node0_key

Note: for the purpose of this configuration, the client ID —formatted as <username>@<host-name>— at the end of the public key file generated by the ssh-keygen command is not relevant and should be discarded when copying the public key value.

Catenis Name Server expects to retrieve Catenis nodes' public keys from catenis.io's DNS by looking up TXT records by the name ctn-node. Those TXT records should contain a JSON with the following keys:

• idx: [Integer] The Catenis node index.
• pubKey: [String] The SSH RSA public key.

Note: when using Catenis Name Server on a non-production environment (i.e., sandbox or development), the name of the TXT record should have a suffix identifying the environment (i.e., ctn-node.sandbox or ctn-node.dev).

The following is an example of such TXT record:

ctn-node TXT {"idx":0,"pubKey":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC2q/4V67+BMRrVIZGWLWc27B80kMc/NlJGSXbs2KuN4bmK4iyPA0ycTxavrb1y9eFIXg/ZM613DpeEsK7uaU9wtRZxaI1hFY3oWiEx28gU8Jh4XnBHgSNl4LibAKZIiOtiHOAqCAYUpQuU+j8Kr4GNKzP+QuuwQbOkEpImwv01Mpq+lUpqyvhL0GqMfQNaYvSjV02OZtRcHqQ1CfIuWxfs+iAht1WrW6C4+KZsaRbmZG63ujmvLIwG7zdV3y5NW9NUdoJTM59EHHOQ5yFn985C8Q5QUwnk544TZsMJJ4szVELWSzlrzGFpZfCygkEJmAJVAq+KRBQe/4z6PDfX1qIR"}

Set IPFS repository root CID method

Request: POST /ctn-node/:nodeIdx/ipfs-root

URL parameters:

• nodeIdx: [Number] The index of the Catenis node for which the IPFS repository root CID should be set

Request body: a JSON object containing the following keys:

• cid: [String] New IPFS CID of Catenis node's IPFS repository root.
• lastUpdatedDate: [String] ISO-8601 formatted date and time when CID for this Catenis node's IPFS repository root has last been recorded.

Note: the lastUpdatedDate key is only taken into account (and thus should only be sent) when another Catenis Name Server instance is calling this method.

Success response body: a JSON containing the following keys:

• status: [String] The value 'success'.

Set Multiple IPFS repository root CIDs method

Request: POST /ctn-node/ipfs-root

Request body: a JSON object containing one or more of the following keys:

• <Catenis_node_index>.cid: [String] New IPFS CID of Catenis node's IPFS repository root.
• <Catenis_node_index>.lastUpdatedDate: [String] ISO-8601 formatted date and time when CID for this Catenis node's IPFS repository root has last been recorded.

Note: the term <Catenis_node_index> should be replaced with the index of the Catenis node the IPFS repository root CID of which should be set.

Success response body: a JSON containing the following keys:

• status: [String] The value 'success'.

Note: this method should only be called by another Catenis Name Server instance.

Retrieve IPFS repository root CID method

Request: GET /ctn-node/:nodeIdx/ipfs-root

URL parameters:

• nodeIdx: [Number] The index of the Catenis node for which the IPFS repository root CID should be retrieved.

Success response body: a JSON containing the following keys:

• status: [String] The value 'success'.
• data.cid: [String] The current IPFS CID of Catenis node's IPFS repository root.
• data.lastUpdatedDate: [String] ISO-8601 formatted date and time when CID has been last updated.

Retrieve All IPFS repository root CIDs method

Request: GET /ctn-node/ipfs-root

Query string (optional) parameters:

• updatedSince: [String] ISO-8601 formatted date and time used to filter Catenis IPFS repository root CIDs to be returned.

Success response body: a JSON containing the following keys:

• status: [String] The value 'success'.
• data.<Catenis_node_index>.cid: [String] CID of IPFS repository root for that Catenis node.
• data.<Catenis_node_index>.lastUpdatedDate: [String] ISO-8601 formatted date and time when CID has been last updated.

Note: the term <Catenis_node_index> is replaced with the index of the specific Catenis node.

License

This software is released under the MIT License. Feel free to fork, and modify!

Copyright © 2020-2023, Blockchain of Things Inc.