Skip to content

Instantly share code, notes, and snippets.

@tynes

tynes/name-claim.md

Last active Aug 31, 2020
Embed
What would you like to do?
Domain Name Claiming for Handshake

Handshake Domain Name Claims

The Handshake Network has reserved the Alexa Top 100k domains on chain to make sure that important brands are able to own their name in the system. These names can be claimed using a DNSSEC proof of ownership. This means that the owner of the domain name must place a TXT record at their domain name that includes a controlled address.

For technical instructions, see:

If you use a DNS provider that does not support DNSSEC, this process will be more challenging and the instructions here will need to be used. Please consider switching to a DNS provider that does allow DNSSEC to help make the internet more secure.

Instructions

Make sure to be using the latest versions of hsd and hs-client. It is also possible to claim a name using Kyokan's Bob Wallet. Skip to Claiming the Domain.

DNS Configuration

Some guides are available here:

It may take some time before DNSSEC is activated, be sure that your DNS provider has completed enabling DNSSEC before continuing.

Handshake

  • Install hsd using the installation instructions on the README. This requires Node.js version 10 along with npm, and node-gyp. Instructions may vary based on operating system, please use the appropriate package manager to install these.

hsd Installation

$ git clone https://github.com/handshake-org/hsd
$ cd hsd
$ npm i

Setup

Now start the node so that its possible to create an address. This will create a directory $HOME/.hsd. It is very important that this directory is secure because the wallet keys are in $HOME/.hsd/wallet.

./bin/hsd

hs-client Installation

In another terminal, install hs-client.

$ git clone https://github.com/handshake-org/hs-client
$ cd hs-client
$ npm i

Note: if you are not using the latest version, you will need to pass --network main to every CLI command from hs-client.

Mnemonic Backup

Be sure to back up your mnemonic using the command:

$ ./bin/hsw-cli master

https://hsd-dev.org/api-docs/#get-master-hd-key

Note: this is very important to back up and will result in loss of control of the domain name on Handshake if it is lost. Be sure to correctly back up the mnemonic phrase in a separate place. It should look like a series of common words. These words can be used to create a new wallet and rediscover the HNS and names that are controlled by that wallet.

Setting a Passphrase

If you would like to set a passphrase for the wallet, use the command:

$ curl  http://127.0.0.1:12039/wallet/primary/passphrase \
    -X POST --data '{"passphrase":"NEWPASSWORDGOESHERE"}'

If you are updating a wallet's passphrase, include the an "old" key in the JSON body that contains the old passphrase.

On Windows the command needs to be formatted like this (escaped double quotes in the json):

curl -X POST -H "Content-Type: application/json" \
    --data "{\"passphrase\":\"NEWPASSWORDGOESHERE\"}" \
    http://127.0.0.1:12039/wallet/primary/passphrase

Claiming the Domain

To connect the local wallet to the domain name, use the command: Users running Bob Wallet will want to pass along their API key by including the --api-key APIKEYHERE flag in the below command.

$ ./bin/hsw-rpc createclaim DOMAINNAME

Copy the .txt field in the output and place in a TXT record at the domain using a DNS service provider. It should look something like "hns-claim:qnPxvMRKAAAAAAAA+4mmSeRmfY/8TOEF+ux4cu9H4M4OYKap5Y4LfMO7YUcAFBUOdex4+uplMqefKrIpsyZnyHPn".

Submitting the Domain Claim

After the TXT record has been propagated, use the command:

$ ./bin/hsw-rpc sendclaim DOMAINNAME

This will broadcast a claim to the network. After some time, the claim will be mined. The claim must mature for a period of 30 days before DNS records can be writted to the authenticated database. An additional claim can be sent to reset the 30 day period. This is useful to prevent names from being stolen, since the community has time to coordinate out of band during those 30 days. After the maturity period, the name will now be under control of the local wallet. To update the records, the sendupdate RPC command is useful.

An example here:

$ ./bin/hsw-rpc sendupdate DOMAINNAME \
    '{"records":[{"type":"GLUE4","ns":"ns1.example.com.","address":"127.0.0.1"}]}'

Credits

@pinheadmz

This comment has been minimized.

Copy link

@pinheadmz pinheadmz commented Mar 12, 2020

Suggestion: use https://dnssec-debugger.verisignlabs.com/ to test DNSSEC chain.
https://dnssec-debugger.verisignlabs.com/crypto51.app is an example of a qualified DNSSEC chain for a name that was successfully claimed on Handshake. Note that the keys in the DS records are RSASHA256. Ironically, ICANN.org will not be able to be used to claim icann on Handhsake because .org uses RSASHA1-NSEC3-SHA1 (considered weak and not valid).

See: handshake-org/hsd#399

@tynes

This comment has been minimized.

Copy link
Owner Author

@tynes tynes commented Apr 30, 2020

A new node RPC is being implemented called getdnssecproof here: handshake-org/hsd#261

It will return the Handshake DNSSEC proof for a domain along with verifying it. An error will be thrown if the proof is invalid. This will be helpful for testing out the DNSSEC claim process, along with making the DNSSEC proofs themselves more accessible to application developers.

@Blooniverse

This comment has been minimized.

Copy link

@Blooniverse Blooniverse commented Jun 12, 2020

Alexa's top 100K only? What about brands & entities which don't fall into this category?

@pinheadmz

This comment has been minimized.

Copy link

@pinheadmz pinheadmz commented Jun 12, 2020

@Blooniverse, this isn't really the right place to ask questions or raise issues. But HNS reserved trademark names as well, there was a long application process available before mainnet launched: https://github.com/handshake-org/hs-names

@rayvahey

This comment has been minimized.

Copy link

@rayvahey rayvahey commented Aug 5, 2020

Spotted a typo "The claim must mature for a period of 30 days before DNS records can be writted to the authenticated database."

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.