Canarytokens

# DNS Token

# What is a DNS token

When you create a DNS based Canarytoken, the system gives you a unique Internet resolvable domain name.

Anyone attempting to resolve this domain name, will now trigger an alert.

Why does this matter? Once you are able to get an alert for a web-based token, or a DNS based token, you have the building blocks for squillions of possible tripwires.

# Creating a DNS token

Head on over to canarytokens.org (opens new window) and select DNS token:

Creating a DNS token

Enter your email address along with a reminder that will be easy to understand then click Create:

Created an HTTP token

Copy the hostname and place it somewhere useful.

# Encoding additional information in your token

Your DNS token can carry a small amount of additional custom data when it’s triggered. This can be used for adding incident-specific data to your alert with custom DNS based tokens. Use the following encoding rules to place generic data into your DNS token:

  • Base32 encode your data, and remove any padding '=' characters
  • Insert periods (.) after every 63-bytes
  • Append the magic string '.G'+<2-random-digits>+'.' (e.g. '.G12.' or '.G83.')
  • Append your DNS token This creates a new hostname of the form:
  <base32-string>.<base32-string>.G<2-random-digits>.<dns-token>

Bear in mind the total length of the hostname still cannot exceed 253-bytes, so the amount of raw bytes that can be encoded is ~125. If the data cannot be decoded as UTF-8, it will be returned as a hexlifyed string.

# Example code

Here's a Python example of the encoding rules:

>>> token='pz21qtyfsidipvrsuzs9n2udi.canarytokens.com'
>>> data='I am a teapot, hear me pour! Glug, glug, glug.'
>>> import base64, re, random
>>> '.'.join(filter(lambda x: x,re.split(r'(.{63})', base64.b32encode(data.encode('utf8')).decode('utf8').replace('=','')) + ['G'+str(random.randint(10,99)), token]))
'JEQGC3JAMEQHIZLBOBXXILBANBSWC4RANVSSA4DPOVZCCICHNR2WOLBAM5WHKZZ.MEBTWY5LHFY.G72.pz21qtyfsidipvrsuzs9n2udi.canarytokens.com'

# Reading the transmitted data

The decoded data is shown the incident's history:

Browse to the token's history

← Web Image Token →