From af942774f4792ed175b91e8fd56ec5c162241bf7 Mon Sep 17 00:00:00 2001 From: mcilwain Date: Fri, 7 Apr 2017 19:33:11 -0700 Subject: [PATCH] Copyedit the TLD security restrictions doc ------------- Created by MOE: https://github.com/google/moe MOE_MIGRATED_REVID=152570631 --- .../tld-security-restrictions.md | 156 ++++++++++-------- 1 file changed, 84 insertions(+), 72 deletions(-) diff --git a/docs/operational-procedures/tld-security-restrictions.md b/docs/operational-procedures/tld-security-restrictions.md index 2ee01c5eb..1d743ec55 100644 --- a/docs/operational-procedures/tld-security-restrictions.md +++ b/docs/operational-procedures/tld-security-restrictions.md @@ -1,107 +1,119 @@ -# Security restrictions for TLD +# TLD security restrictions -Nomulus provides several security features that allow registries to impose -additional restrictions on which domains are allowed on a TLD and which +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. This document outlines the various -restrictions available, their intended use case, and how to use them. +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. -## TLD-wide restrictions +This document outlines the various restrictions available, their use cases, and +how to apply them. -Nomulus allows registry administrators to set registrant contact and nameserver -restrictions on a TLD. Use the following command to set the restrictions when -creating or updating a TLD: +## 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: ```shell -$ nomulus -e production [create_tld | update_tld] \ - --allowed_nameservers {NS1},{NS2},... \ - --allowed_registrants {REG1},{REG2},... \ - {TLD1} {TLD2} ... +$ 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: + +```shell +$ 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 -constitute a subset of the allowed nameservers or registrants on the TLD. Note -that an empty set is not considered a legitimate subset, and consequently when -the restrictions are set for one property, you **must** provide at least one -corresponding value that is allowed. If no restrictions are set, it is allowed -to create/update domains that do not have nameservers on it. Registrant, on the -other hand, is always required. +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 in -Nomulus. This restriction is orthogonal to the TLD-wide nameserver restriction -detailed above, and the allowed nameserver list can be set to an arbitrary list -that is not related to the TLD-wide allowed nameservers list (if any). Any -domain mutation must pass both validations (if applicable). In practice, it is -always 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. +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 maintained in reserved lists with -reservation type `NAMESERVER_RESTRICTED`, using a csv format, which nameservers -delimited by colons. The following example has two allowed nameservers: +The per-domain allowed nameserver lists are configured in [reserved +list](./reserved-list-management.md) entries with the reservation type +`NAMESERVER_RESTRICTED`. The final element in the entry is the colon-delimited +list of nameservers, e.g.: ``` -internaldomain,NAMESERVER_RESTRICTED,ns1.internal.tld:ns1.internal.tld +restrictedsld,NAMESERVER_RESTRICTED,ns1.mycompany.tld:ns2.mycompany.tld ``` -Reserved lists can also prohibit domain registrations for reasons other than -nameserver restrictions. For more details on reserved lists and how they work, -refer to the doc [here](reserved-list-management.md). Note that multiple -reserved lists can be applied to one TLD, and if they happen to contain -nameserver restrictions to the same label, the resulting restriction set is the -intersection of the all allowed nameserver lists for that label. +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 -by default forbidden unless the domain is whitelisted. The typical use case for -this feature is for a closed TLD that wants to enforce greater security by only -allowing registration of domains that are explicitly allowed. Such restriction -on domain creation is achieved by setting the TLD to be "domain create -restricted". The allowed list of domains are read from reserved lists applied on -the TLD, with `NAMESERVER_RESTRICTED` reservation. This means that each domain -will also need to have explicitly allowed nameservers configured in its reserved -list entry, and the per-domain nameserver validation is performed in related -flows. +forbidden except for whitelisted domain names. This is achieved by setting the +"domain create restricted" option on the TLD using the `nomulus` tool. Domains +are whitelisted 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: +To apply domain create restriction when creating/updating a TLD, use the +`--domain_create_restricted` parameter as follows: ```shell -$ nomulus -e production [create_tld | update_tld] \ - --domain_create_restricted {TLD1} {TLD2} ... +$ 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, -because it operates independently from the per-domain nameservers restriction -that `NAMESERVER_RESTRICTED` reservation invokes. +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-whitelisted domains, setting a TLD -as domain create restricted also applies `SERVER_UPDATE_PROHIBITED` and -`SERVER_TRANSFER_PROHIBITED` status to domains automatically when they are -created. Therefore any domains created under such a TLD is virtually immutable. -For more information on EPP status codes, see -[here](https://tools.ietf.org/html/rfc5731#section-2.3). +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](https://tools.ietf.org/html/rfc5731#section-2.3). -The consequence of applying these status code is that no registrar can send -request to modify an existing domain without the registry explicitly allowing it -on a case-by-case basis. If a change does need to be made, the registry must -explicitly remove the status, make changes, and then reapply the status. To -remove/reapply server status, use: +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: ```shell -$ nomulus -e production update_server_locks \ - --[apply | remove] {STATUS1},{STATUS2},... \ - --client {REGISTRAR} +$ nomulus -e {ENVIRONMENT} update_server_locks \ + --remove SERVER_UPDATE_PROHIBITED,SERVER_TRANSFER_PROHIBITED \ + --client {REGISTRAR_CLIENT_ID} --n {DOMAIN} ``` -Note that domain create restricted is intended for closed TLDs, as such, the -validation only happens in regular domain create/update flows. Domain -application and allocate are usually not applicable to closed TLDs because there -is no sunrise period. Therefore no domain whitelist validation against the -reserved lists is performed during these flows, nor are server prohibited status -applied. +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.