hostname

Documentation

Overview

Package hostname provides a utility method to generate a hostname which can be used in conjunction with the stateless DNS server https://github.com/taskcluster/stateless-dns-server

Domains generated by this library encode an IP-address, expiration date, a random salt and an HMAC-SHA256 signature truncated to 128 bits.

This provides a mechanism to assign temporary sub-domains names to nodes with a public IP-address. The same problem can also be solved with dynamic DNS server, but such entries often requires clean-up. The beauty of this approach is that the DNS server is state-less, so there is no stale DNS records to discard.

In TaskCluster this is used to assign temporary sub-domain names to EC2 spot nodes, such that we can host HTTPS resources, such as live logs, without updating and cleaning up the state of the DNS server.

Notice, that with IP-address, expiration date, random salt and HMAC-SHA256 signature encoded in the sub-domain label, you cannot decide which sub-domain label you wish to have. Hence, this is only useful in cases were the hostname for your node is transmitted to clients by other means, for example in a message over RabbitMQ or as temporary entry in a database. Further more, to serve HTTPS content you'll need a wild-card SSL certificate, for domain managed by this DNS server.

Note, this obviously doesn't have many applications, as the sub-domain label is stateful. It's mostly for serving HTTPS content from nodes that come and go quickly with minimal setup, where the hostname is transmitted by other means. Generally, any case where you might consider using the default EC2 hostname.

Sub-domain Label Generation

The sub-domain label encodes the following parameters:

• `ip`, address to which the `A` record returned should point,
• `expires`, expiration of sub-domain as number of ms since epoch,
• `salt`, random salt, allowing for generation of multiple sub-domain labels for each IP-address, and,
• `signature`, HMAC-SHA256 signature of `ip`, `expires` and `salt` truncated to 128 bit.

The `expires` property is encoded as a big-endian 64 bit signed integer. The `salt` property is encoded as bit-endian 16 bit unsigned integer. All properties are concatenated and base32 (RFC 3548) encoded to form the sub-domain label.

Index

• func Decode(fqdn, secret, subdomain string) (ip net.IP, expires time.Time, salt [2]byte, err error)
• func New(ip net.IP, subdomain string, expires time.Time, secret string) string

Examples

• Decode
• New

Functions

func Decode

func Decode(fqdn, secret, subdomain string) (ip net.IP, expires time.Time, salt [2]byte, err error)

Decode takes a fully qualified hostname that has been encoded with the stateless dns naming scheme, and returns its IP, expiry time and salt. If the hostname is invalid for any reason, an error will be returned explaining the cause.

Example

package main

import (
	"fmt"
	"log"

	"github.com/taskcluster/stateless-dns-go/hostname"
)

func main() {
	ip, expires, salt, err := hostname.Decode("zmvtoaqaaaavkjlja2i2n2ligiol2idykqa3t7vk4vfakdv6.foo.com", "turnip4tea", "foo.com")
	if err != nil {
		log.Fatalf("Not able to decode example hostname")
	}
	fmt.Println(ip)
	fmt.Println(expires)
	fmt.Println(salt)
}

Output:

203.43.55.2
2016-06-06 11:11:27.889 +0000 UTC
[166 233]

func New

func New(ip net.IP, subdomain string, expires time.Time, secret string) string

New generates a temporary hostname for the given ip, with the given subdomain, having the given expiry, using the given secret.

Example

package main

import (
	"fmt"
	"net"
	"time"

	"github.com/taskcluster/stateless-dns-go/hostname"
)

func main() {
	ip := net.IPv4(byte(203), byte(43), byte(55), byte(2))
	subdomain := "foo.com"
	expires := time.Now().Add(15 * time.Minute)
	secret := "turnip4tea"
	fmt.Println(hostname.New(ip, subdomain, expires, secret))
}