DK Hostmaster Registrar Portal Service specification
2021-12-02 Revision 3.1
Table of Contents
- Introduction
- RP in Brief
- RP Service
- Implementation Requirements
- IP Whitelisting
- Features
- Account
- DNSSEC
- Domain Name
- Domain Name Application
- Restore Domain Name
- Set auto-expire/renewal for domain name
- Cancel/Delete Domain Name
- Transfer Domain Name
- Generate Authorization for Transfer
- Change Name Servers for Domain Name
- Generate Authorization for Change of Name Servers
- Change Registrant for Domain Name
- Renew Domain Name
- Name Server
- Prepaid
- References
- Resources
- Appendices
Introduction
This document describes the registrar self-service portal (RP) offered by DK Hostmaster.
The document is targeted at registrars as audience.
About this Document
This specification describes version 3.X.X of the DK Hostmaster RP service. Future releases will be reflected in updates to this specification, please see the document history section below.
Screenshots for depicting features can be seen bu clicking the
Do note that the specification describes the latest released service. Service version is listed in the Document History, so given changes implemented in the service are reflected in the specification. Do note that a service might be released to the sandbox environment prior to being released to production after a grace period.
Any future additions and changes to the implementation are not within the scope of this document and will not be discussed or mentioned throughout this document.
This document is owned and maintained by DK Hostmaster A/S and must not be distributed without this information.
All examples provided in the document are fabricated or changed from real data to demonstrate commands etc. any resemblance to actual data are coincidental.
This document is not the authoritative source for business and policy rules and possible discrepancies between this an any authoritative sources are regarded as errors in this document. This document is aimed at being the external technical specification and describes the implementation facing the users and is an interpretation of authoritative sources and can therefor be erroneous.
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
3.1 2021-12-02
- Added documentation for: Generate Authorization for Transfer with the new and improved token format
- Added documentation for: Generate Authorization for Change of Name Servers with the new and improved token format
3.0 2021-09-22
- Relabeled to follow the version number, changes as for revision 2.0
2.0 2021-05-13
- Describes service version 3.X.X
- Added new section on features, the initial features described are:
1.0 2018-11-28
- Initial revision
- Describes service version 2.3.X
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.
RP in Brief
RP is a web based service aimed at registrars and supporting their business and processed towards the DK Hostmaster registry.
RP Service
SSL/TLS Support
The RP service supports the following protocols for transport security:
- TLSv1.2
Available Environments
DK Hostmaster offers the following two environments:
- production
- sandbox
Updates to both environments are announced via the tech-announce mailing list.
Please see the information page for details on subscribing etc.
production
https://rp.dk-hostmaster.dk/
sandbox
https://rp-sandbox.dk-hostmaster.dk/
Implementation Requirements
Active Registrar Account
Access to the RP service requires an active registrar account, please see the information on the process for becoming a registrar.
IP Whitelisting
DK Hostmaster requires whitelisting of IPs for access to the RP service.
Additions and removals of IP addresses can be handled by the registrar itself, but initial setup is currently a manual process handled by DK Hostmaster.
Please submit change requests including registrar handle information to via the regular support channels.
Features
Account
This section describes the registrar account. The term account is used in general sense and does not describe the financial account exclusively unless specified.
Registrar Account Group
The registrar account group is representing the registrar account and consist initially of:
- A registrar handle, representing the account, not used as an operational account
- An administrative account
Additional accounts can be added for specific and general purpose, such as:
- Domain administration (the proxy meta-role)
- Domain registration (the registrar meta-role)
- Billing and finance administration (the payer meta-role)
- Name server administration (the name server administrator meta-role)
- Registrar account administration (the administrator meta-role)
The accounts are all represented towards the system using an email address.
Meta-Roles
The WHOIS system within the DK Hostmaster registry is based on a set of roles (WHOIS roles), used to resolve privileges and permissions.
For domain names these roles are:
- Registrant contact
- Admin/proxy contact
- Billing contact
- Registrar contact
- VID contact
For name servers:
- Name server administrator
The inhabitants of the roles are identified by a handle, generated and issued by the registry.
Registrar portal users created for the Registrar Account Group can be assigned meta-roles, which give the specific registrar portal user access to certain features.
The meta-roles are mapped to the WHOIS roles.
| WHOIS Role | Meta-role | Note |
|---|---|---|
| Registrant | Registrant | This role planned deprecated with the introduction of the registrar management model |
| Admin/Proxy | Proxy | |
| Billing | Payer | |
| Registrar | N/A | This role is an indication of the registrar account administering the domain name |
| Registrar | This role allows for registration of domain names | |
| Name Server Administrator | Name Server Administrator | |
| VID contact | N/A | This role is not available in the registrar portal |
| N/A | Administrator | This role is not available as a WHOIS role |
Portal Users
Create Portal User
Portal users are intended for human users, for accounts for machine to machine interfaces: like EPP, DAS and DSU please use a service user.
Areas of responsibility can be controlled and divided using meta-roles.
The available meta-roles are:
- Proxy
- Registrar
- Payer
- Name Server Administrator
- Administrator
Enable or Disable Portal User
Edit Portal User
Delete Portal User
If a portal user is not longer in use it can be deleted. Disabling the user is also an option.
Service Users
Service users are intended for machine to machine interfaces and currently the following types are available:
- DAS, for more information on the DAS service, please see the DAS Service Specification
- DSU, for more information on the DAS service, please see the DSU Service Specification
- EPP, for more information on the DAS service, please see the EPP Service Specification
A user is created for a specific service and it cannot be used for other services.
It is possible to use more than one service user at a time, which makes sense with service users for specific uses. This can be controlled by setting the relevant Meta-Roles.
The available meta-roles are:
- Proxy
- Registrar
- Payer
- Name Server Administrator
Creating a single account with all the meta-roles, the model is however flexible so you can specify all the service users you need to represent your own systems.
For example, if you have one system for domain registration and management, including DNSSEC and name servers, but another system for renewals.
-
Create a service user representing the administrative system and assign it the:
Proxy,RegistrarandName Server Administratormeta-roles -
Create a service user representing the billing system and assign it the
Payermeta-role
This also holds the benefit of the credentials not having to be shared between the systems, because the service users are separate entities.
Create Service User
Service users are intended for machine to machine interaction, for accounts for people please use a portal user.
Enable or Disable Service User
Edit Service User
Delete Service User
If a service user is not longer in use it can be deleted. Disabling the user is also an option.
Linked WHOIS Handles
The feature is available in the tab: Administration, in the section: Register account, under the menu point: Linked WHOIS handles.
The features offers the following:
- List WHOIS handles linked to the account. Here you should be able to see the registrar account by default
- Link a WHOIS handle
- Create a WHOIS handle
- Unlink a WHOIS handle
- See details/settings per linked WHOIS handle, currently this is limited to associated e-mail addresses
Link WHOIS Handle
When using the feature to link WHOIS handles, meaning they are associated with a registrar account, a list of candidates are presented.
The requirements for linking are strict and if a certain WHOIS handle does not appear in the list, it might be due to data not matching the registrar account data.
Create WHOIS Registrar Account Handle
A new handle will be created with the same data as the registrar account and it will be automatically linked to the registrar account. You can of course unlink the WHOIS handle from the account.
Creating WHOIS handles for end-users, is done using a another feature.
Merge WHOIS Handles
Merging handles, is the ability to collapse several handles into one.
This can be useful if you have more than one billing contact, name server administrator or something and you want to collect all they activities on a single handle for easier administration.
Unlink WHOIS Handle
When unlinking a WHOIS handle from a registrar account, it is no longer possible to administer the assets associated with this handle via the registrar portal (RP) as portal users. Linking has the opposite effect.
Unlinked WHOIS handles have to use the self-service portal (SB) and are no longer formally associated with the registrar account.
Set Management Model Default
The default for the registrar account can be specified in the Registrar Portal.
The feature requires that the portal-user has the meta-role: Administrator to set the default, please see: Meta-Roles for more details.
- Log in to the Registrar Portal
- Click on the "ADMINISTRATION" tab, if is not already displaying
- Click "Contact information" on the administration tab under "Registrar account"
👁️🗨️ - Locate the ""Registration settings" section
👁️🗨️ - Set default/account settings for your registrar account for:
👁️🗨️ a. "Domain name management" b. "Domain name renewal" - Click "SAVE"
The changes are set instantly and will apply to:
- Domain name registrations
- Contact creations
- Transfers of domain names
Done after the setting has been changed.
Set Renewal Policy Default
The default renewal policy for the registrar account can be specified in the Registrar Portal.
The feature requires that the portal-user has the meta-role: Administrator to set the default, please see: Meta-Roles for more details.
Two options are available:
- Automatic renewal (
Auto-renew) - Automatic expiration (
Auto-expire)
The value unless changed by the registrar is automatic renewal, since this was the only available option prior to the introduction automatic expiration.
Automatic renewal means that upon expiration the domain name, if active, will be automatically renewed and the price will be deducted from the registrar account and the specified period will extend the lifespan of the domain name and the updated expiry date will reflect this.
Automatic expiration does the opposite of automatic renewal, when the expiration date is due, the domain name will be suspended and will no longer be active.
Getting the suspension lifted requires a restore domain operation.
DNSSEC
Manage DNSSEC
The feature is available in the tab: WHOIS search, in the section: Name server operations.
If this section is not available, it is due to that no WHOIS-handles has been associated with the registrar account, which act as name server administrators.
As a name server administrator you can add and remove DSRECORDs to and from a domain name linked to your name servers.
Domain
This section describes the processes and features related to domain names.
Domain Application
The feature is available in the tab: WHOIS search, in the section: Register domain name.
The feature requires that the portal-user has the meta-role: Registrar, please see: Meta-Roles for more details.
As described in the "Implementation guide for registration of .dk" there are two methods for registration of domain names.
- Method 1: Requires that the accept of terms and conditions is done at the registrar and this is communicated via the application
- Method 2: Requires that the accept of terms and conditions is done at the registry (with DK Hostmaster)
The application for allows for specification of a timestamp in the field: Date & time, in the section DK Hostmaster's agreement accepted
The entered date has to match the date and time when the registrant accepted the presented terms and conditions.
The fields available in the application form are the following:
| Field | Note |
|---|---|
| Registrar | This is pre-filled with the registrar account handle and cannot be changed, it does not influence the management model directly, it only to handle the application process |
| Reference | This is a registrar reference with can be used to identify and track an application |
| Domain name | This is the domain name to be applied for |
| Authorization code | This is an optional authorization code is for registering domain names offered for a waiting list position. Please see the details on waiting list handling below |
| Registration period | This is the period of the subscription from 1-10 years |
| Management | Choice of management model, either: Registrar Management or Registrant Management. Please see details below on Management Choice |
| Renewal | Choice of renewal policy, either: Auto-renewal or Auto-expire, Please see section on Prepaid |
| PO no. | This is an optional end-customer purchase order number with can be used to identify and track an order |
| Account code | This is an optional end-customer reference number with can be used to identify and track an order |
| Registrant handle | This is the mandatory handle of the designated registrant. Please see details below on Management Choice |
| Proxy handle | This is the optional handle of the designated proxy contact. Please see details below on Management Choice |
| Payer handle | This is the optional handle of the designated billing contact. Please see details below on Management Choice |
| Name servers | These are the mandatory name servers. At least two have to be specified and 7 as a maximum. |
| DK Hostmaster's agreement accepted | This is for manually entering the timestamp for an end-user agreement to the Terms and Condition of DK Hostmaster |
Management Choice
When registering a domain name, the registrar has to decide between one of the two offered management methods:
Registrar managementRegistrant management
The registrar management model extends the control of the registered domain name. Application wise, it has the following implications:
- The
Proxyhandle will not used and will implicitly be the registrar applying for the domain name - The
Payerhandle (billing contact) will not be used and will implicitly be the registrar applying for the domain name
The specified Registrant will have to be under the same management choice as the domain name. It is not possible to register a domain name for registrar management with a registrar managed user and vice-versa.
Waiting List
DK Hostmaster offers a waiting list service, where end-users can sign up for a waiting list position for a given domain name of their interest.
When a domain name is deleted, potential waiting list positions are evaluated and the domain name in question is offered to the first position.
The offering process, starts by an email to the waiting list owner. The waiting list owner has 14 days to accept the offered domain name.
If the offer is accepted the user can take a unique token associated with the offering to a registrar and register the domain name.
If the domain name is going to be registered under registrant management, to the handle of the waiting list owner, the token is not required to authorize the operation.
If the domain name is going to be registrar managed or registered to another handle, the token is required to authorize the application.
Restore Domain
The restore domain feature can be used to restore domain names, which have been suspended, during the redemption period of 30 days. The suspension can be one of:
- When a domain name is suspended due to manual cancellation. See Cancel domain name
- When a domain name has exceeded its expiry date and it is set to automatic expiration. See Set auto-expire/renewal for domain name
The operation will change the registrar account:
- A period fee for one year
- A restoration fee
See current prices at the DK Hostmaster website: Products and Prices. Insufficient funds in the registrar account will not prohibit this operation.
Set auto-expire/renewal for a domain name
The default setting for automatic expiration and renewal can be controlled on an account level and is set when a domain name is created.
It can also be set for a single domain name.
This can be done up to the expiration date of the specific domain name.
Cancel Domain Name
A domain name can be cancelled manually if it is eligible for cancellation.
A manual cancellation cannot be performed on a domain name, which acts as superordinate for one or more name servers, which have delegated domain names.
An automatic cancellation however will be completed.
- Either due to automatic expiration
- Or by DK Hostmaster
In these situations, the subordinate name servers are not deleted, they are marked for deletion.
The domain names delegated to these name servers, might stop responding based on the way they are set up and a change of name servers will be required to get these working again. For the superordinate, the domain name matching the name servers, a restore operation would be required.
The domain name might might become available for registration upon deletion after the 30 day redemption period. It will not be possible to register or take over the name servers marked for deletion. They can only be recreated after successful deletion by the registry.
Transfer Domain Name
The feature requires that the portal-user has the meta-role: Registrar, please see: Meta-Roles for more details.
Generate Authorization for Transfer
An authorization token can be generated/issued for transfer to another registrar, where the receiving registrar via the token has the authorization to perform the operation.
The authorization token has to be communicated out of band.
The token has the format: <role>-<operation>-<unique token>
An example: REG-TRANSFER-098f6bcd4621d373cade4e832627b4f6
- The authorization is generated/issued by a registrar (
REG, for registrar) - The authorization is for a transfer operation (
TRANSFER) - and finally a unique key
Since an authorization could also be issue by the registrant, that example would resemble the following: OWN-TRANSFER-098f6bcd4621d373cade4e832627b4f6
- The authorization is generated/issued by a registrant (
OWN, for registrant/owner) - The authorization is for a transfer operation (
TRANSFER) - and finally a unique key
The authorization expires after 14 days or by use. It can be retracted via the registrar portal, by deletion of the authorization.
Change Name Servers for Domain Name
The feature requires that the portal-user has the meta-role: Name Server Administrator, please see: Meta-Roles for more details.
<a id="(#generate-authorization-for-change-of-name-servers)>
Generate Authorization for Change of Name Servers
An authorization token can be generated/issued for change of name servers by another name server administrator, where the receiving name server administrator via the token has the authorization to perform the operation.
The authorization token has to be communicated out of band.
The token has the format: <role>-<operation>-<unique token>
An example: NSA-REDEL-098f6bcd4621d373cade4e832627b4f6
- The authorization is generated/issued by a registrar (
NSA, for name server administrator) - The authorization is for a transfer operation (
REDEL, for redelegation) - and finally a unique key
Since an authorization could also be issue by the registrant or proxy, those example would resemble the following:
As registrant: OWN-REDEL-098f6bcd4621d373cade4e832627b4f6
- The authorization is generated/issued by a registrant (
OWN, for registrant/owner) - The authorization is for a transfer operation (
REDEL) - and finally a unique key
As proxy PXY-REDEL-098f6bcd4621d373cade4e832627b4f6
- The authorization is generated/issued by a registrant (
PXY, for proxy) - The authorization is for a transfer operation (
REDEL) - and finally a unique key
The authorization expires after 14 days or by use. It can be retracted via the registrar portal, by deletion of the authorization.
Change Registrant for Domain Name
Change of registrant is only possible for a registrar for a registrar managed domain name.
- The domain name has to be eligible for the transfer
- The transfer can only take place within the registrars own portfolio, so it is not possible to do this operation across portfolios. Meaning that the existing registrant and designated registrant both have to be created as uses in the registrars portfolio
Due to the registry requirements for ID-control and agreements to the registry terms and conditions the process might be asynchronous depending on the circumstances of the operation.
- If the request is accompanied by a order confirmation token, this is not requested by the registry
- If the designated registrant already has completed ID-control successfully or is not required to do so
The request will be instant and the change registrant fee will be deducted from the registrar account upon success
-
If the request is not accompanied by an order confirmation token, an accept of the DK Hostmaster's terms and conditions by the registrant, will be requested by the registrar. This request is valid for 14 days
-
If the designated registrant is required to complete ID-control, the registry will, as for accept of terms and conditions, contact the user directly are request the ID-control. The request expires after 14 days
The registrar is notified on all steps of the above process:
- Upon request for accept of terms and conditions
- Upon request for ID-control
- Upon expiration of request for accept of terms and conditions
- Upon expiration of request for ID-control
- Upon rejection of ID-control
- Success of operation
As for the immediate successful execution, the delayed process the change registrant fee will be deducted from the registrar account upon success.
See current prices at the DK Hostmaster website: Products and Prices. Insufficient funds in the registrar account will not prohibit this operation.
Renew Domain Name
The feature requires that the portal-user has the meta-role: Payer, please see: Meta-Roles for more details.
Domain name subscriptions can be renewed manually via the registrar portal. The feature applies to both:
- Registrant managed domain names, where the registrar is appointed as the billing contact
- Registrar managed domain names
This can be done up to the expiration date of the specific domain name. It does not influence automatic renewal or automatic expiration apart from delaying there effective execution and automatic change to the domain name lifespan.
See current prices at the DK Hostmaster website: Products and Prices. Insufficient funds in the registrar account will not prohibit this operation.
Name Server
This section describes the processes and features related to name servers.
The feature requires that the portal-user has the meta-role: Name Server Administrator, please see: Meta-Roles for more details.
Name Server Application
The feature is available in the tab: WHOIS search, in the section: Name server operations.
If this section is not available, it is possibly due to that no WHOIS-handles has been associated with the registrar account, which act as name server administrators.
In order to associate any name server administrators with the registrar account, please use the feature Link WHOIS handles.
In the case of a domain name cancellation and following deletion, any subordinate name servers are not deleted, they are marked for deletion.
The superordinate domain name might might become available for registration upon deletion after the 30 day redemption period. It will not be possible to register or take over the name servers marked for deletion. They can only be recreated after successful deletion by the registry.
Administer Name Servers
When name servers have been created they can be edited.
For name servers, which are subordinate, to a .dk domain in the registrars portfolio. glue records can be added and removed. Glue records are supported for both IP version 4 and 6. Please see the section on the glue record policy in the DK Hostmaster Name Service Specification.
The administrator for the name server can be changed as follows:
- For a name server under registrar management, this can be done by the registrar and the existing name server administrator. There is not requirement that the handled appointed to the task is under the same management model
- For a name server under registrant management, this can be only be done by the existing name server administrator
Name Server Deletion
When a name server no longer is serving any domain names, it is eligible for deletion.
This operation can be performed as follows:
- For a name server under registrar management, this can be done by the registrar and the existing name server administrator
- For a name server under registrant management, this can be only be done by the existing name server administrator
Prepaid
The feature requires that the portal-user has the meta-role: Payer, please see: Meta-Roles for more details.
The registrar account is a prepaid account, meaning the registrar holds the responsibility of keeping the account sufficiently funded.
A set of the billable operations will be declined in case of insufficient funds, they are:
- Create domain name
- Transfer domain name
The other billable operations, not limited by insufficient funding are:
- Automatic renewal
- Manual renewal
- Manual restoration
- Change registrant
Overall the following policies are in place currently.
- Expansion of portfolio requires sufficient funding
- Maintenance of existing portfolio is possible without sufficient funding
For more information on grace periods and handling of these please refer to the registrar agreement.
Add funds to registrar account
Adding funds can to the registrar account can be accomplished in a few ways.
The registrar portal offers, transferring via credit card.
For Danish registrars a unique FIK code has been allocated, which identifies the registrar account
For non-Danish registrars it is possible to do a bank transfer. Handling of bank transfers are manual and are therefor as a minimum subject to registry opening hours and a manual processing time schedules.
The ensure the speediest and most successful processing of bank transfers make sure to provide the required information:
- IBAN
- Your registrar account number
References
List of references used in this document in alphabetical order.
- DK Hostmaster: Become a registrar
- DK Hostmaster: Implementation guide for registration of .dk
- DK Hostmaster: Sandbox Environment Specification
- DK Hostmaster: EPP Service Specification
- DK Hostmaster: Name Service Specification
- DK Hostmaster: Products and Prices
- DK Hostmaster: Registrar Portal Service Specification Screenshots
Resources
A list of resources for DK Hostmaster Registrar Portal service support is located below.
Mailing list
DK Hostmaster operates a mailing list for discussion and inquiries about the DK Hostmaster EPP implementation. 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.
Issue Reporting
For issue reporting related to this specification, the RP implementation or test, sandbox or production environments, please contact us. You are of course welcome to post these to the mailing list mentioned above, otherwise use the regular support channels.