Public specification for the DS Update service
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
diagrams
.editorconfig
.markdownlint.json
LICENSE
README.md

README.md

DSU Service and Protocol 1.0 Specification

2018-11-29 Revision: 1.5

Table of Contents

Introduction

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

The protocol is based on HTTP and the parameters are transferred as POST-variables. The response contains an HTTP header and a brief message for human interpretation. The interface interprets a call as an atomic operation. If errors occur, all changes are rejected and no existing DS records are deleted.

To use DSU, send a TLS-encrypted HTTP POST request to the DSU service.

About this Document

This specification describes protocol version 1.0.

Printable version can be obtained via this link, using the gitprint service.

License

This document is copyright by DK Hostmaster A/S and is licensed under the MIT License, please see the separate LICENSE file for details.

Document History

  • 1.5 2018-11-29

    • Corrected some spelling and grammatical errors
    • Fixed Markdown issues
    • Added information on Wiki
    • Added information on new consolidated sandbox environment
  • 1.4 2018-06-07

    • Added process diagrams
    • Added httpie and curl examples
  • 1.3 2018-06-07

    • Updated DNSSEC information
  • 1.2 2017-04-01

    • Addressed broken links
    • Added information on algorithms 13 and 14 RFC:6605
    • Added information on digest type 4 RFC:6605
    • Added list of supported algorithms and digest types
  • 1.1 2016-06-29

    • Added more information and extended the documentation with license, TOC etc.
  • 1.0 2015-07-04

    • Initial revision on Github

The .dk Registry in Brief

DK Hostmaster is the registry for the ccTLD for Denmark (dk). The current model used in Denmark is based on a sole registry, with DK Hostmaster maintaining the central DNS registry.

The service is not subject to any sorts of standards.

The DS Update Service

Available Environments

DK Hostmaster offers the following environments:

Environment Role Policies
production production This environment will be the production environment for the DK Hostmaster DSU Service
sandbox development This environment is intended for client development towards the DK Hostmaster DSU Service

For more information on deployed please consult the wiki.

Production Environment

  • is_available requests made to this environment will reflect live production data
  • production credentials and proper authorization are needed to access the service

Production environment is available at: https://dsu.dk-hostmaster.dk/1.0

Sandbox Environment

  • Requests made to this environment are resembling production, but are isolated in the sandbox environment

Sandbox is available at: https://dsu-sandbox.dk-hostmaster.dk/1.0

For more information on the consolidated sandbox environment please see the specification.

Encoding

Non-ASCII parameters is first tried interpreted as UTF-8. If this fails, data are assumed to be ISO8859-1.

Security

Parameters

The following parameters are part of the protocol:

userid

This userid must be authorized to operate on the DS keys for the given domain name.

password

This is the password for the given userid.

domain

The domain name which this DS Update pertains. The domain name is transferred encoded using punycode. This means domain name containing Danish letters should be written using the xn-- notation, just as for DNS. For allowed characters please see the DK Hostmaster Name Service specification.

Supported Algorithms

DK Hostmaster currently support the following algorithms from the IANA algorithm listing:

  • 3 DSA (DSA/SHA1) RFC:3110 - do note that use of this algorithm is not recommended since it is deprecated
  • 5 RSASHA1 (RSA/SHA-1) RFC:2539
  • 6 DSA-NSEC3-SHA1 (DSA-NSEC3-SHA1) RFC:5155
  • 7 RSASHA1-NSEC3-SHA1 (RSASHA1-NSEC3-SHA1) RFC:5155
  • 8 RSA/SHA-256 RFC:5702
  • 10 RSA/SHA-512 RFC:5702
  • 13 ECDSA Curve P-256 with SHA-256 RFC:6605
  • 14 ECDSA Curve P-384 with SHA-384 RFC:6605

Supported Digest Types

DS Service Features

Adding DS-keys

Process:

Update DSRECORDS Process

For the parameters defined further down, these rules apply:

An update can contain up to 5 DS keys per domain name. If you wish to specify only 1 key, specify only one set, i.e. keytag1, algorithm1, digest_type1 and digest1.

If you wish to specify two keys, an additional set is specified, i.e. keytag2, algorithm2, digest_type2 and digest2. You may continue this way until you reach the maximum of 5 sets.

The key sets must be specified sequentially starting from 1. E.g. it is not allowed to specify set 1, set 2, set 4 without also specifying set 3.

When a transaction is accepted, all previous DS keys associated with the domain name are deleted. This means that a transaction must contain all DS keys, which are to be associated with the domain name in the future.

keytag1 .. keytag5

The DNSKEY-key's key tag according to RFC:4034 section 5.1.1.

algorithm1 .. algorithm5

The DNSKEY-key's algorithm according to RFC:5702 section 2 for algorithms 8 and 10 and RFC:6605 for algorithms 13 and 14.

digest_type1 .. digest_type5

The digest method used to generate the DS fingerprint according to RFC:4034 section 5.1.3

digest1 .. digest5

The fingerprint digest of the DNSKEY-key according to RFC:4509 section 2.1 or RFC:6605 for digest type 4.

Example 1

Request (last line has been wrapped to increase the readability)

 POST /1.0 HTTP/1.0
 Host: dsu.dk-hostmaster.dk
 Content-Type: application/x-www-form-urlencoded
 Content-Length: 146

 userid=ABCD1234-DK&password=abba4evah&domain=xn--l-4ga.dk&
 keytag1=1551&algorithm1=7&digest_type1=1&
 digest1=CD1B87D20EE5EE5F78FCE25336E6519B838F7DC9
Response
 HTTP/1.0 400 Bad Request
 X-DSU: 496
 Content-Type: text/plain

 Unknown userid

Using curl for addition

curl -v -F 'userid=ABCD1234-DK' \
-F 'password=abba4evah' \
-F 'domain=xn--l-4ga.dk' \
-F 'keytag1=1551' \
-F 'algorithm1=7' \
-F 'digest_type1=1' \
-F 'digest1=CD1B87D20EE5EE5F78FCE25336E6519B838F7DC9' https://dsu.dk-hostmaster.dk/1.0

Using httpie for addition

$ http --form POST https://dsu.dk-hostmaster.dk/1.0 \
userid='ABCD1234-DK' \
password='abba4evah' \
domain='xn--l-4ga.dk' \
keytag1=1551 \
algorithm1=7 \
digest_type1=1 \
digest1=CD1B87D20EE5EE5F78FCE25336E6519B838F7DC9

Deleting DS-keys

Process:

Update DSRECORDS Process

If you wish to delete all DS-keys for a domain name, all values of set 1 must be set to the value DELETE_DS. No further sets are allowed in the same transaction.

If a 530 error is returned, the HTTP header will contain an additional error-code with the name X-DSU. The value can be one of the following:

  • 531 Authentication failed.
  • 532 Authorization failed.
  • 533 Authenticating using this password type is not supported.

Example 2

Request (last line has been wrapped to increase the readability)

 POST /1.0 HTTP/1.0
 Host: dsu.dk-hostmaster.dk
 Content-Type: application/x-www-form-urlencoded
 Content-Length: 118

 userid=ABCD1234-DK&password=abba4evah&domain=a.dk&
 keytag1=DELETE_DS&algorithm1=DELETE_DS&digest_type1=DELETE_DS
 &digest1=DELETE_DS
Response

 HTTP/1.0 200 OK
 Content-Type: text/plain

 OK

Using curl for deletion

curl -v -F 'userid=ABCD1234-DK' \
-F 'password=abba4evah' \
-F 'domain=xn--l-4ga.dk' \
-F 'keytag1=DELETE_DS' \
-F 'algorithm1=DELETE_DS' \
-F 'digest_type1=DELETE_DS' \
-F 'digest1=DELETE_DS' https://dsu.dk-hostmaster.dk/1.0

Using httpie for deletion

$ http --form POST https://dsu.dk-hostmaster.dk/1.0 \
userid='ABCD1234-DK' \
password='abba4evah' \
domain='xn--l-4ga.dk' \
keytag1='DELETE_DS' \
algorithm1='DELETE_DS' \
digest_type1='DELETE_DS' \
digest1='DELETE_DS'

References

Resources

Resources for DK Hostmaster DSU support are listed below.

Mailing list

DK Hostmaster operates a mailing list for discussion and inquiries about the DK Hostmaster DSU service and DNSSEC in general. To subscribe to this list, write to the address below and follow the instructions. Please note that the list is for technical discussion only, any issues beyond the technical scope will not be responded to, please send these to the contact issue reporting address below and they will be passed on to the appropriate entities within DK Hostmaster A/S.

  • tech-discuss+subscribe@liste.dk-hostmaster.dk

Issue Reporting

For issue reporting related to this specification, the DSU implementation or sandbox or production environments, please contact us. You are of course welcome to post these to the mailing list mentioned above, otherwise use the address specified below:

  • info@dk-hostmaster.dk

Demo Client

A demo client is available as open source under a MIT license.

Appendices

HTTP Status Codes

The reply is transferred primarily as HTTP status codes. A text message for human interpretation is also provided. Possible status codes are:

HTTP Status code Message Description
200 OK The request has been processed without problems
400 Bad Request The request is invalid and has been rejected, see sub-status codes 400 segment in the table below
405 Method Not Allowed The method POST or GET, is not allowed
500 Internal Server Error An error occurred in DK Hostmaster's systems
530 Access denied Authentication not successful, see sub-status codes 500 segment in the table below

Reference: IANA: HTTP Status Codes

HTTP Sub-status Codes

If a 400 or 530 error is returned, the HTTP header will contain an additional error code with the name X-DSU. The value can be one of the following:

X-DSU Status code Description
480 Userid not specified
481 Password not specified
482 Missing a parameter
483 Domain name not specified
484 Invalid domain name
485 Invalid userid
486 Invalid digest and digest_type combination
487 The contents of at least one parameter is syntactically wrong
488 At least one DS key has an invalid algorithm
489 Invalid sequence of sets
495 Unknown parameter given
496 Unknown userid
497 Unknown domain name
531 Authentication failed
532 Authorization failed
533 Authenticating using this password type is not supported