google-nomulus/docs/operational-procedures/tld-security-restrictions.md

TLD security restrictions

Nomulus has several security features that allow registries to impose additional restrictions on which domains are allowed on a TLD and what registrant/nameservers they can have. The restrictions can be applied to an entire TLD or on a per-domain basis. These restrictions are intended for use on closed TLDs that need to allow external registrars, and prevent undesired domain registrations or updates from occurring, e.g. if a registrar makes an error or is compromised. For closed TLDs that do not need external registrars, a simpler solution is to not grant any registrars access to the TLD.

This document outlines the various restrictions available, their use cases, and how to apply them.

TLD-wide nameserver/registrant restrictions

Nomulus allows registry administrators to set registrant contact and/or nameserver restrictions on a TLD. This is typically desired for brand TLDs on which all domains are either self-hosted or restricted to a small set of webhosts.

To configure allowed nameservers on a TLD, use the --allowed_nameservers, --add_allowed_nameservers, and --remove_allowed_nameservers parameters on the update_tld command as follows:

$ nomulus -e {ENVIRONMENT} update_tld --allowed_nameservers {NS1,NS2,...} {TLD}

Note that --allowed_nameservers can also be used with the create_tld command when the TLD is initially created.

To set the allowed registrants, use the analogous --allowed_registrants, --add_allowed_registrants, and --remove_allowed_registrants parameters:

$ nomulus -e {ENVIRONMENT} update_tld \
    --allowed_registrants {CONTACTID1,CONTACTID2,...} {TLD}

When nameserver or registrant restrictions are set on a TLD, any domain mutation flow under that TLD will verify that the supplied nameservers or registrants are not empty and that they are a strict subset of the allowed nameservers and registrants on the TLD. If no restrictions are set, domains can be created or updated without nameservers, but registrant is still always required.

Per-domain nameserver restrictions

Registries can also elect to impose per-domain nameserver restrictions. This restriction is orthogonal to the TLD-wide nameserver restriction detailed above. Any domain mutation must pass both validations (if applicable). In practice, it is recommended to maintain consistency between the two types of lists by making the per-domain allowed nameserver list a subset of the TLD-wide one, because any nameservers that are not included in both lists are effectively disallowed.

The per-domain allowed nameserver lists are configured in reserved list entries with the reservation type NAMESERVER_RESTRICTED. The final element in the entry is the colon-delimited list of nameservers, e.g.:

restrictedsld,NAMESERVER_RESTRICTED,ns1.mycompany.tld:ns2.mycompany.tld

Note that multiple reserved lists can be applied to a TLD. If different reserved lists contain nameserver restrictions for the same label, then the resulting restriction set is the set intersection of all allowed nameserver lists for that label.

Domain create restriction on closed TLDs

Nomulus offers the ability to "lock-down" a TLD so that domain registration is forbidden except for allow-listed domain names. This is achieved by setting the "domain create restricted" option on the TLD using the nomulus tool. Domains are allow-listed for registration by adding them to reserved lists with entries of type NAMESERVER_RESTRICTED. Each domain will thus also need to have explicitly allowed nameservers configured in its reserved list entry, per the previous section.

To apply domain create restriction when creating/updating a TLD, use the --domain_create_restricted parameter as follows:

$ nomulus -e {ENVIRONMENT} [create_tld | update_tld] \
    --domain_create_restricted [true | false] {TLD}

Note that you do not have to set a TLD-wide allowed nameservers list with this option, because it operates independently from the per-domain nameservers restriction that NAMESERVER_RESTRICTED reservation imposes.

In addition to disabling registration of non-allow-listed domains, setting a TLD as domain create restricted also applies the SERVER_UPDATE_PROHIBITED and SERVER_TRANSFER_PROHIBITED statuses to domains upon creation. Any domains on a domain create restricted TLD are therefore virtually immutable, and must be unlocked by the registry operator before each change can be made. For more information on these EPP statuses, see RFC 5731.

To an unlock a locked domain so that a registrar can make changes, the registry operator must remove the status using a nomulus tool command as follows:

$ nomulus -e {ENVIRONMENT} update_server_locks \
    --remove SERVER_UPDATE_PROHIBITED,SERVER_TRANSFER_PROHIBITED \
    --client {REGISTRAR_CLIENT_ID}
    --n {DOMAIN}

Note that these statuses will be reapplied immediately after any transfer/update so long as the TLD is still set to domain create restricted.

Since the domain create restricted facility is intended for use on closed TLDs, validation/server lock does not happen in domain application and allocate flows. Most closed TLDs do not have a sunrise period, so this is fine, but for the unanticipated occasion that a sunrise period is necessary, it suffices to manually ensure that all domains are correct immediately after entering general availability, after which no additional disallowed changes can be made.