dsupdate

README

Go library for updating DS records with Punktum.dk's proprietary DS Update protocol

import "arnested.dk/go/dsupdate"

Package dsupdate is a library for updating DS records with Punktum.dk's (DK Hostmasters) proprietary DS Update protocol.

DS Update is a proprietary protocol and service developed and offered by Punktum as an interface for updating DNSSEC related DS records associated with a .dk domain name.

The service and protocol is documented at https://github.com/Punktum-dk/dsu-service-specification.

This package has functionality to update or delete DS records using the DS Update protocol.

Documentation

Overview

Package dsupdate is a library for updating DS records with Punktum.dk's (DK Hostmasters) proprietary DS Update protocol.

DS Update is a proprietary protocol and service developed and offered by Punktum as an interface for updating DNSSEC related DS records associated with a .dk domain name.

The service and protocol is documented at <https://github.com/Punktum-dk/dsu-service-specification>.

This package has functionality to update or delete DS records using the DS Update protocol.

Example (Delete)

This example deletes existing DS records of the eksempel.dk domain. The deletion is made with at timeout of 5 second specified using a context with a timeout.

package main

import (
	"context"
	"errors"
	"fmt"
	"net/http"
	"time"

	"arnested.dk/go/dsupdate"
)

func main() {
	// Create a client with some fake credentials.
	client := dsupdate.Client{
		Domain:     "eksempel.dk",    // .dk domain name
		UserID:     "ABCD1234-DK",    // Punktum.dk user ID
		Password:   "abba4evah",      // Punktum.dk password
		BaseURL:    dsupdate.Sandbox, // If left out defaults to dsupdate.Production
		HTTPClient: &http.Client{},   // If left out defaults to http.DefaultClient
	}

	// We'll set a 5 second timeout in the deletion using the
	// context package.
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	// Delete the DS record(s) to Punktum.dk.
	resp, err := client.Delete(ctx)

	// If the update failed and a substatus was returned in the
	// "X-DSU" header the error be of the `SubStatus` type.
	var subStatusErr dsupdate.SubStatus
	if errors.As(err, &subStatusErr) {
		fmt.Printf("Failed with DSU substatus error (%d): %s", subStatusErr, subStatusErr)

		return
	}

	// All other errors will be unspecified error of the error
	// interface.
	if err != nil {
		fmt.Printf("Failed with some error: %s", err)

		return
	}

	// If there was no error returned the delete succeeded. `resp`
	// will be the body of whatever was returned from the DS
	// Update service.
	fmt.Printf("Succeeded. Punktum.dk responded with the message in the body: %s", resp)
}

Example (Update)

This example updates the DS records of the eksempel.dk domain. The update is made with at timeout of 5 second specified using a http.Client configured with the timeout..

package main

import (
	"context"
	"errors"
	"fmt"
	"net/http"
	"time"

	"arnested.dk/go/dsupdate"
)

func main() {
	// Create a client with some fake credentials.
	client := dsupdate.Client{
		Domain:   "eksempel.dk",    // .dk domain name
		UserID:   "ABCD1234-DK",    // Punktum.dk user ID
		Password: "abba4evah",      // Punktum.dk password
		BaseURL:  dsupdate.Sandbox, // If left out defaults to dsupdate.Production
		HTTPClient: &http.Client{
			Timeout: 5 * time.Second,
		},
	}

	// Make a slice of DS records.
	records := []dsupdate.DsRecord{
		{
			KeyTag:     43930,
			Algorithm:  8, // RSA/SHA-256
			DigestType: 2, // SHA-256
			Digest:     "E174B66853D0DE1A4E391DFAE924695EB6BF12D28E1A68BDBDB44C4F0D325EA1",
		},
	}

	ctx := context.Background()

	// Post the new DS record(s) to Punktum.dk.
	resp, err := client.Update(ctx, records)

	// If the update failed and a substatus was returned in the
	// "X-DSU" header the error be of the `SubStatus` type.
	var subStatusErr dsupdate.SubStatus
	if errors.As(err, &subStatusErr) {
		fmt.Printf("Failed with DSU substatus error (%d): %s", subStatusErr, subStatusErr)

		return
	}

	// All other errors will be unspecified error of the error
	// interface.
	if err != nil {
		fmt.Printf("Failed with some error: %s", err)

		return
	}

	// If there was no error returned the update succeeded. `resp`
	// will be the body of whatever was returned from the DS
	// Update service ("Request sent to DSU::Version_1_0 okay").
	fmt.Printf("Succeeded. Punktum.dk responded with the message in the body: %s", resp)
}

Index

• type BaseURL
  • func (baseURL BaseURL) String() string
• type Client
  • func (c *Client) Delete(ctx context.Context) ([]byte, error)
  • func (c *Client) Update(ctx context.Context, records []DsRecord) ([]byte, error)
• type DsRecord
• type SubStatus
  • func (e SubStatus) Error() string
  • func (i SubStatus) String() string

Examples

• Package (Delete)
• Package (Update)

Types

type BaseURL

type BaseURL string

BaseURL is the endpoint of the DS Update service.

const (
	// Production environment of Punktum.dk's DSU service.
	Production BaseURL = "https://dsu.dk-hostmaster.dk/1.0"
	// Sandbox environment of Punktum.dk's DSU service.
	Sandbox BaseURL = "https://dsu-sandbox.dk-hostmaster.dk/1.0"
)

Punktum.dk's environments are predefined as constants.

func (BaseURL) String

func (baseURL BaseURL) String() string

String gives you the endpoint as a string. If the BaseURL is not set (the zero value) it will give you the Production environment.

type Client

type Client struct {
	Domain     string  // .dk domain name, i.e eksempel.dk
	UserID     string  // Punktum.dk user ID, i.e. ABCD1234-DK
	Password   string  // Punktum.dk password
	BaseURL    BaseURL // DS Update service base URL. You can use constants dsupdate.Production (default) or dsupdate.Sandbox
	HTTPClient *http.Client
}

Client for doing updates and deletions.

func (*Client) Delete

func (c *Client) Delete(ctx context.Context) ([]byte, error)

Delete DS records.

func (*Client) Update

func (c *Client) Update(ctx context.Context, records []DsRecord) ([]byte, error)

Update DS records.

type DsRecord

type DsRecord struct {
	KeyTag     uint16
	Algorithm  uint8
	DigestType uint8
	Digest     string
}

DsRecord is a DS record.

type SubStatus

type SubStatus int16

SubStatus is the error specified by the DS Upload service. See: https://github.com/DK-Hostmaster/dsu-service-specification#http-sub-status-codes

const (
	UserIDNotSpecified                                   SubStatus = 480 // user ID not specified
	PasswordNotSpecified                                 SubStatus = 481 // password not specified
	MissingAParameter                                    SubStatus = 482 // missing a parameter
	DomainNameNotSpecified                               SubStatus = 483 // domain name not specified
	InvalidDomainName                                    SubStatus = 484 // invalid domain name
	InvalidUserID                                        SubStatus = 485 // invalid user ID
	InvalidDigestAndDigestTypeCombination                SubStatus = 486 // invalid digest and digest type combination
	TheContentsOfAtLeastOneParameterIsSyntacticallyWrong SubStatus = 487 // the contents of at least one parameter is syntactically wrong
	AtLeastOneDSKeyHasAnInvalidAlgorithm                 SubStatus = 488 // at least one DS key has an invalid algorithm
	InvalidSequenceOfSets                                SubStatus = 489 // invalid sequence of sets
	UnknownParameterGiven                                SubStatus = 495 // unknown parameter given
	UnknownUserID                                        SubStatus = 496 // unknown user ID
	UnknownDomainName                                    SubStatus = 497 // unknown domain name
	AuthenticationFailed                                 SubStatus = 531 // authentication failed
	AuthorizationFailed                                  SubStatus = 532 // authorization failed
	AuthenticatingUsingThisPasswordTypeIsNotSupported    SubStatus = 533 // authenticating using this password type is not supported
)

DS Upload Sub-status codes. See: https://github.com/DK-Hostmaster/dsu-service-specification#http-sub-status-codes

func (SubStatus) Error

func (e SubStatus) Error() string

Error describes the substatus error.

func (SubStatus) String

func (i SubStatus) String() string