RFC 9154 | EPP Secure AuthInfo for Transfer | December 2021 |
Gould & Wilhelm | Standards Track | [Page] |
The Extensible Provisioning Protocol (EPP) (RFC 5730) defines the use of authorization information to authorize a transfer of an EPP object, such as a domain name, between clients that are referred to as "registrars". Object-specific, password-based authorization information (see RFCs 5731 and 5733) is commonly used but raises issues related to the security, complexity, storage, and lifetime of authentication information. This document defines an operational practice, using the EPP RFCs, that leverages the use of strong random authorization information values that are short lived, not stored by the client, and stored by the server using a cryptographic hash that provides for secure authorization information that can safely be used for object transfers.¶
This is an Internet Standards Track document.¶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9154.¶
Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The Extensible Provisioning Protocol (EPP) [RFC5730] defines the use of authorization information to authorize a transfer of an EPP object, such as a domain name, between clients that are referred to as "registrars". The authorization information is object specific and has been defined in "Extensible Provisioning Protocol (EPP) Domain Name Mapping" [RFC5731] and "Extensible Provisioning Protocol (EPP) Contact Mapping" [RFC5733] as password-based authorization information. Other authorization mechanisms can be used, but in practice the password-based authorization information has been used at the time of object creation, managed with the object update, and used to authorize an object transfer request. What has not been considered is the security of the authorization information, which includes the complexity of the authorization information, the Time To Live (TTL) of the authorization information, and where and how the authorization information is stored.¶
The current/original lifecycle for authorization information involves long-term storage of encrypted (not hashed) passwords, which presents a significant latent risk of password compromise and is not consistent with current best practices. The mechanisms in this document provide a way to avoid long-term password storage entirely and to only require the storage of hashed (not retrievable) passwords instead of encrypted passwords.¶
This document defines an operational practice, using the EPP RFCs, that leverages the use of strong, random authorization information values that are short lived, not stored by the client, and stored by the server using a cryptographic hash to provide secure authorization information used for transfers. This operational practice can be used to support transfers of any EPP object, where the domain name object as defined in [RFC5731] is used in this document for illustration purposes. Elements of the practice may be used to support the secure use of the authorization information for purposes other than transfer, but any other purposes and the applicable elements are out of scope for this document.¶
The overall goal is to have strong, random authorization information values that are short lived and are either not stored or stored as cryptographic hash values by the non-responsible parties. In a registrant, registrar, and registry model, the registrant registers the object through the registrar to the registry. The registrant is the responsible party, and the registrar and the registry are the non-responsible parties. EPP is a protocol between the registrar and the registry, where the registrar is referred to as the "client" and the registry is referred to as the "server". The following are the elements of the operational practice and how the existing features of the EPP RFCs can be leveraged to satisfy them:¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
XML [W3C.REC-xml-20081126] is case sensitive. Unless stated otherwise, XML specifications and examples provided in this document MUST be interpreted in the character case presented in order to develop a conforming implementation.¶
In examples, "C:" represents lines sent by a protocol client and "S:" represents lines returned by a protocol server. Indentation and empty space in examples are provided only to illustrate element relationships and are not a required feature of this protocol.¶
The examples reference XML namespace prefixes that are used for the associated XML namespaces. Implementations MUST NOT depend on the example XML namespaces and instead employ a proper namespace-aware XML parser and serializer to interpret and output the XML documents. The example namespace prefixes used and their associated XML namespaces include the following:¶
The EPP RFCs refer to "client" and "server", but when it comes to transfers, there are three types of actors that are involved. This document will refer to these actors as "registrant", "registrar", and "registry". [RFC8499] defines these terms formally for the Domain Name System (DNS). The terms are further described below to cover their roles as actors using the authorization information in the transfer process of any object in the registry, such as a domain name or a contact:¶
This document does not define a new protocol; rather, it defines an operational practice using existing EPP features, where the client and the server can signal support for the operational practice using a namespace URI in the login and greeting extension services. The namespace URI "urn:ietf:params:xml:ns:epp:secure-authinfo-transfer-1.0" is used to signal support for the operational practice. The client includes the namespace URI in an <svcExtension> <extURI> element of the <login> command [RFC5730]. The server includes the namespace URI in an <svcExtension> <extURI> element of the greeting [RFC5730].¶
A client that receives the namespace URI in the server's greeting extension services can expect the following supported behavior by the server:¶
A server that receives the namespace URI in the client's <login> command extension services can expect the following supported behavior by the client:¶
The EPP RFCs ([RFC5731] and [RFC5733]) use password-based authorization information to support transfer with the <domain:pw> element [RFC5731] and with the <contact:pw> element [RFC5733]. Other EPP objects that support password-based authorization information for transfer can use secure authorization information as defined in this document. For authorization information to be secure, it must be generated using a strong random value and have a short TTL. The security of the authorization information is defined in the following sections.¶
For authorization information to be secure, it MUST be generated using a secure random value. The authorization information is treated as a password, and the required length L of a password, rounded up to the largest whole number, is based on the size N of the set of characters and the desired entropy H, in the equation L = ROUNDUP(H / log2 N). Given a target entropy, the required length can be calculated after deciding on the set of characters that will be randomized. In accordance with current best practices and noting that the authorization information is a machine-generated value, the implementation SHOULD use at least 128 bits of entropy as the value of H. The lengths below are calculated using that value.¶
Calculation of the required length with 128 bits of entropy and with the set of all printable ASCII characters except space (0x20), which consists of the 94 characters 0x21-0x7E:¶
ROUNDUP(128 / log2 94) =~ ROUNDUP(128 / 6.55) =~ ROUNDUP(19.54) = 20¶
Calculation of the required length with 128 bits of entropy and with the set of case-insensitive alphanumeric characters, which consists of 36 characters (a-z A-Z 0-9):¶
ROUNDUP(128 / log2 36) =~ ROUNDUP(128 / 5.17) =~ ROUNDUP(24.76) = 25¶
The strength of the random authorization information is dependent on the random number generator. Suitably strong random number generators are available in a wide variety of implementation environments, including the interfaces listed in Sections 7.1.2 and 7.1.3 of [RFC4086]. In environments that do not provide interfaces to strong random number generators, the practices defined in [RFC4086] and Section 4.7.1 of the NIST Federal Information Processing Standards (FIPS) Publication 140-2 [FIPS-140-2] can be followed to produce random values that will be resistant to attack. (Note: FIPS 140-2 has been superseded by FIPS 140-3, but FIPS 140-3 does not contain information regarding random number generators.)¶
The authorization information SHOULD only be set when a transfer is in process. This implies that the authorization information has a TTL by which the authorization information is cleared when the TTL expires. The EPP RFCs do not provide definitions for TTL, but since the server supports the setting and unsetting of the authorization information by the sponsoring registrar, the sponsoring registrar can apply a TTL based on client policy. The TTL client policy may be based on proprietary registrar-specific criteria, which provides for a transfer-specific TTL tuned for the particular circumstances of the transaction. The sponsoring registrar will be aware of the TTL, and the sponsoring registrar MUST inform the registrant of the TTL when the authorization information is provided to the registrant.¶
To protect the disclosure of the authorization information, the following requirements apply:¶
To support the authorization information TTL, as described in Section 4.2, the authorization information must have either a set or unset state. Authorization information that is unset is stored with a NULL (undefined) value. Based on the requirement to store the authorization information using a strong one-way cryptographic hash, as described in Section 4.3, authorization information that is set is stored with a non-NULL hashed value. The empty authorization information value is used as input in both the <create> command (Section 5.1) and the <update> command (Section 5.2) to define the unset state. The matching of the authorization information in the <info> command (Section 5.3) and the <transfer> request command (Section 5.4) is based on the following rules:¶
To secure the transfer process using secure authorization information as described in Section 4, the client and server need to implement steps where the authorization information is set only when a transfer is actively in process and ensure that the authorization information is stored securely and transported only over secure channels. The steps for management of the authorization information for transfers include the following:¶
The following sections outline the practices of the EPP commands and responses between the registrar and the registry that supports secure authorization information for transfer.¶
For a <create> command, the registry MUST allow the passing of an empty authorization information value and MAY disallow the passing of a non-empty authorization information value. By having an empty authorization information value on create, the object is initially not involved in the transfer process. Any EPP object extension that supports setting the authorization information with an "eppcom:pwAuthInfoType" element can pass an empty authorization information value. Examples of such extensions are found in [RFC5731] and [RFC5733].¶
Example of passing an empty authorization information value in a domain name <create> command [RFC5731]:¶
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <create> C: <domain:create C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>example.com</domain:name> C: <domain:authInfo> C: <domain:pw/> C: </domain:authInfo> C: </domain:create> C: </create> C: <clTRID>ABC-12345</clTRID> C: </command> C:</epp>¶
Example of passing an empty authorization information value in a contact <create> command [RFC5733]:¶
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <create> C: <contact:create C: xmlns:contact="urn:ietf:params:xml:ns:contact-1.0"> C: <contact:id>sh8013</contact:id> C: <contact:postalInfo type="int"> C: <contact:name>John Doe</contact:name> C: <contact:addr> C: <contact:city>Dulles</contact:city> C: <contact:cc>US</contact:cc> C: </contact:addr> C: </contact:postalInfo> C: <contact:email>jdoe@example.com</contact:email> C: <contact:authInfo> C: <contact:pw/> C: </contact:authInfo> C: </contact:create> C: </create> C: <clTRID>ABC-12345</clTRID> C: </command> C:</epp>¶
For an <update> command, the registry MUST allow the setting and unsetting of the authorization information. The registrar sets the authorization information by first generating a strong, random authorization information value, based on the information provided in Section 4.1, and setting it in the registry in the <update> command. The importance of generating strong authorization information values cannot be overstated: secure transfers are very important to the Internet to mitigate damage in the form of theft, fraud, and other abuse. It is critical that registrars only use strong, randomly generated authorization information values.¶
Because of this, registries may validate the randomness of the authorization information based on the length and character set required by the registry -- for example, validating that an authorization value contains a combination of uppercase, lowercase, and non-alphanumeric characters in an attempt to assess the strength of the value and returning an EPP error result of 2202 ("Invalid authorization information") [RFC5730] if the check fails.¶
Such checks are, by their nature, heuristic and imperfect, and may identify well-chosen authorization information values as being not sufficiently strong. Registrars, therefore, must be prepared for an error response of 2202 and respond by generating a new value and trying again, possibly more than once.¶
Often, the registrar has the "clientTransferProhibited" status set, so to start the transfer process, the "clientTransferProhibited" status needs to be removed, and the strong, random authorization information value needs to be set. The registrar MUST define a TTL, as described in Section 4.2, and if the TTL expires, the registrar will unset the authorization information.¶
Example of removing the "clientTransferProhibited" status and setting the authorization information in a domain name <update> command [RFC5731]:¶
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <update> C: <domain:update C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>example.com</domain:name> C: <domain:rem> C: <domain:status s="clientTransferProhibited"/> C: </domain:rem> C: <domain:chg> C: <domain:authInfo> C: <domain:pw>LuQ7Bu@w9?%+_HK3cayg$55$LSft3MPP C: </domain:pw> C: </domain:authInfo> C: </domain:chg> C: </domain:update> C: </update> C: <clTRID>ABC-12345-XYZ</clTRID> C: </command> C:</epp>¶
When the registrar-defined TTL expires, the sponsoring registrar MUST cancel the transfer process by unsetting the authorization information value and MAY add back statuses like the "clientTransferProhibited" status. Any EPP object extension that supports setting the authorization information with an "eppcom:pwAuthInfoType" element can pass an empty authorization information value. Examples of such extensions are found in [RFC5731] and [RFC5733]. Setting an empty authorization information value unsets the authorization information. [RFC5731] supports an explicit mechanism of unsetting the authorization information, by passing the <domain:null> authorization information value. The registry MUST support unsetting the authorization information by accepting an empty authorization information value and accepting an explicit unset element if it is supported by the object extension.¶
Example of adding the "clientTransferProhibited" status and unsetting the authorization information explicitly in a domain name <update> command [RFC5731]:¶
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <update> C: <domain:update C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>example.com</domain:name> C: <domain:add> C: <domain:status s="clientTransferProhibited"/> C: </domain:add> C: <domain:chg> C: <domain:authInfo> C: <domain:null/> C: </domain:authInfo> C: </domain:chg> C: </domain:update> C: </update> C: <clTRID>ABC-12345-XYZ</clTRID> C: </command> C:</epp>¶
Example of unsetting the authorization information with an empty authorization information value in a domain name <update> command [RFC5731]:¶
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <update> C: <domain:update C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>example.com</domain:name> C: <domain:add> C: <domain:status s="clientTransferProhibited"/> C: </domain:add> C: <domain:chg> C: <domain:authInfo> C: <domain:pw/> C: </domain:authInfo> C: </domain:chg> C: </domain:update> C: </update> C: <clTRID>ABC-12345-XYZ</clTRID> C: </command> C:</epp>¶
Example of unsetting the authorization information with an empty authorization information value in a contact <update> command [RFC5733]:¶
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <update> C: <contact:update C: xmlns:contact="urn:ietf:params:xml:ns:contact-1.0"> C: <contact:id>sh8013</contact:id> C: <contact:chg> C: <contact:authInfo> C: <contact:pw/> C: </contact:authInfo> C: </contact:chg> C: </contact:update> C: </update> C: <clTRID>ABC-12345-XYZ</clTRID> C: </command> C:</epp>¶
For an <info> command, the registry MUST allow the passing of a non-empty authorization information value for verification. The gaining registrar can pre-verify the authorization information provided by the registrant prior to submitting the transfer request with the use of the <info> command. The registry compares the hash of the passed authorization information with the hashed authorization information value stored for the object. When the authorization information is not set or the passed authorization information does not match the previously set value, the registry MUST return an EPP error result code of 2202 [RFC5730].¶
Example of passing a non-empty authorization information value in a domain name <info> command [RFC5731] to verify the authorization information value:¶
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <info> C: <domain:info C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>example.com</domain:name> C: <domain:authInfo> C: <domain:pw>LuQ7Bu@w9?%+_HK3cayg$55$LSft3MPP C: </domain:pw> C: </domain:authInfo> C: </domain:info> C: </info> C: <clTRID>ABC-12345</clTRID> C: </command> C:</epp>¶
The info response in object extensions, such as those defined in [RFC5731] and [RFC5733], MUST NOT include the optional authorization information element with a non-empty authorization value. The authorization information is stored as a hash in the registry, so returning the plain-text authorization information is not possible, unless valid plain-text authorization information is passed in the <info> command. The registry MUST NOT return any indication of whether the authorization information is set or unset to the non-sponsoring registrar by not returning the authorization information element in the response. The registry MAY return an indication to the sponsoring registrar that the authorization information is set by using an empty authorization information value. The registry MAY return an indication to the sponsoring registrar that the authorization information is unset by not returning the authorization information element.¶
Example of returning an empty authorization information value in a domain name info response [RFC5731] to indicate to the sponsoring registrar that the authorization information is set:¶
S:<?xml version="1.0" encoding="UTF-8" standalone="no"?> S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> S: <response> S: <result code="1000"> S: <msg>Command completed successfully</msg> S: </result> S: <resData> S: <domain:infData S: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> S: <domain:name>example.com</domain:name> S: <domain:roid>EXAMPLE1-REP</domain:roid> S: <domain:status s="ok"/> S: <domain:clID>ClientX</domain:clID> S: <domain:authInfo> S: <domain:pw/> S: </domain:authInfo> S: </domain:infData> S: </resData> S: <trID> S: <clTRID>ABC-12345</clTRID> S: <svTRID>54322-XYZ</svTRID> S: </trID> S: </response> S:</epp>¶
For a <transfer> request command, the registry MUST allow the passing of a non-empty authorization information value to authorize a transfer. The registry compares the hash of the passed authorization information with the hashed authorization information value stored for the object. When the authorization information is not set or the passed authorization information does not match the previously set value, the registry MUST return an EPP error result code of 2202 [RFC5730]. Whether the transfer occurs immediately or is pending is up to server policy. When the transfer occurs immediately, the registry MUST return the EPP success result code of 1000 ("Command completed successfully") [RFC5730], and when the transfer is pending, the registry MUST return the EPP success result code of 1001 ("Command completed successfully; action pending"). The losing registrar MUST be informed of a successful transfer request using an EPP <poll> message.¶
Example of passing a non-empty authorization information value in a domain name <transfer> request command [RFC5731] to authorize the transfer:¶
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <transfer op="request"> C: <domain:transfer C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>example1.com</domain:name> C: <domain:authInfo> C: <domain:pw>LuQ7Bu@w9?%+_HK3cayg$55$LSft3MPP C: </domain:pw> C: </domain:authInfo> C: </domain:transfer> C: </transfer> C: <clTRID>ABC-12345</clTRID> C: </command> C:</epp>¶
Upon successful completion of the transfer, the registry MUST automatically unset the authorization information. If the transfer request is not submitted within the TTL (Section 4.2) or the transfer is canceled or rejected, the registrar MUST unset the authorization information, as described in Section 5.2.¶
The goal of the transition considerations is to minimize the impact to the registrars in supporting the Secure Authorization Information Model defined in this document by supporting incremental transition steps. The transition steps are dependent on the starting point of the registry. Registries may have different starting points, since some of the elements of the Secure Authorization Information Model may have already been implemented. The considerations assume a starting point, referred to as the "Classic Authorization Information Model", which incorporates the following steps for management of the authorization information for transfers:¶
The gaps between the Classic Authorization Information Model and the Secure Authorization Information Model include the following:¶
The transition can be handled in the three phases defined in Sections 6.1, 6.2, and 6.3.¶
The goal of "Transition Phase 1 - Features" is to implement the needed features in EPP so that the registrar can optionally implement the Secure Authorization Information Model. The features to implement are broken out by the commands and responses below:¶
The goal of "Transition Phase 2 - Storage" is to transition the registry to use hashed authorization information instead of encrypted authorization information. There is no direct impact on the registrars, since the only visible indication that the authorization information has been hashed is that the set authorization information is not returned in the info response, as addressed in "Transition Phase 1 - Features" (Section 6.1). Transitioning the authorization information storage includes the following three steps:¶
The goal of "Transition Phase 3 - Enforcement" is to complete the implementation of the Secure Authorization Information Model, by enforcing the following:¶
This document uses URNs to describe XML namespaces conforming to the registry mechanism described in [RFC3688]. IANA has assigned the following URI in the "ns" subregistry within the "IETF XML Registry" for secure authorization information for the transfer namespace:¶
IANA has registered the EPP operational practice described in this document in the "Extensions for the Extensible Provisioning Protocol (EPP)" registry as defined in [RFC7451]. The details of the registration are as follows:¶
Section 4.1 defines the use of a secure random value for the generation of authorization information. The client SHOULD choose a length and set of characters that result in at least 128 bits of entropy.¶
Section 4.2 defines the use of an authorization information TTL. The registrar SHOULD only set the authorization information during the transfer process by setting the authorization information at the start of the transfer process and unsetting the authorization information at the end of the transfer process. The TTL value is left up to registrar policy, and the sponsoring registrar MUST inform the registrant of the TTL when providing the authorization information to the registrant.¶
Section 4.3 defines the storage and transport of authorization information. The losing registrar MUST NOT store the authorization information and the gaining registrar MUST only store the authorization information as a "transient" value during the transfer process, where the authorization information MUST NOT be stored after the end of the transfer process. The registry MUST store the authorization information using a one-way cryptographic hash of at least 256 bits and with a per-authorization information random salt with at least 128 bits. All communication that includes the authorization information MUST be over an encrypted channel. The plain-text authorization information MUST NOT be written to any logs by the registrar or the registry.¶
Section 4.4 defines the matching of the authorization information values. The registry stores an unset authorization information value as a NULL (undefined) value to ensure that an empty input authorization information value never matches it. The method used to define a NULL (undefined) value is database specific.¶
The authors wish to thank the following persons for their feedback and suggestions: Michael Bauland, Martin Casanova, Scott Hollenbeck, Benjamin Kaduk, Jody Kolker, Barry Leiba, Patrick Mevzek, Matthew Pozun, Srikanth Veeramachaneni, and Ulrich Wisser.¶