DSU Service and Protocol 1.0 Specification

THIS SERVICE WILL BE DECOMMISSIONED ON JULY 1ST, 2024

2021-09-09 Revision: 3.0

Table of Contents

• Introduction
• About this Document
  • License
  • Document History
• The .dk Registry in Brief
• The DS Update Service
  • Available Environments
    • Production Environment
    • Sandbox Environment
  • Encoding
  • Security
  • Parameters
    • userid
    • password
    • domain
  • Supported Algorithms
  • Supported Digest Types
• DS Service Features
  • Adding DS-keys
    • keytag1 .. keytag5
    • algorithm1 .. algorithm5
    • digest_type1 .. digest_type5
    • digest1 .. digest5
  • Example 1
    • Using curl for addition
    • Using httpie for addition
  • Deleting DS-keys
  • Example 2
    • Using curl for deletion
    • Using httpie for deletion
• References
• Resources
  • Mailing list
  • Issue Reporting
  • Demo Client
• Appendices
  • HTTP Status Codes
  • HTTP Sub-status Codes

Introduction

DSU is short for DS Update. DSU is a proprietary protocol and service developed and offered by Punktum dk 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 and version 3 (3.X.X) of the Punktum dk DSU service.

License

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

Document History

• 3.0 2021-09-09

  • Relabelled the 2.0 version of the specification, so the major version follows the service version number

• 2.0 2021-09-02

  • Updated specification to follow service version 3.0.0
  • Added information on the removal of the concept of DSRECORD ownership introduced with version 3.0.0 of the service

• 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

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

The service is not subject to any sorts of standards.

The DS Update Service

Available Environments

Punktum dk offers the following environments:

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

For more information on deployed please consult the wiki.

Production Environment

• 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 Punktum dk Name Service specification.

Supported Algorithms

Punktum dk 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

• 1 SHA-1 RFC:4509
• 2 SHA-256 RFC:4509
• 4 SHA-384 RFC:6605

DS Service Features

Adding DS-keys

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.

As of version 3.X.X of the service all DSRECORDs that can be deleted are deleted, the concept of ownership of DSRECORDs are removed with this version. A DSRECORDs might not be applicable for deletion, but this will be a very special circumstance.

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:

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.

As of version 3.X.X of the service all DSRECORDs that can be deleted are deleted, the concept of ownership of DSRECORDs are removed with this version. A DSRECORDs might not be applicable for deletion, but this will be a very special circumstance.

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

• RFC:4034: Resource Records for the DNS Security Extensions
• RFC:4509: Use of SHA-256 in DNSSEC Delegation Signer (DS) Resource Records (RRs)
• RFC:5702: Use of SHA-2 Algorithms with RSA in DNSKEY and RRSIG Resource Records for DNSSEC
• RFC:6605: Elliptic Curve Digital Signature Algorithm (DSA) for DNSSEC
• Punktum dk Name Service Specification

Resources

Resources for Punktum dk DSU support are listed below.

Issue Reporting

For issue reporting related to this specification, the DSU implementation or sandbox or production environments, please contact us.

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 Punktum dk'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