Extensible Provisioning Protocol (EPP) Secure Authorization Information for Transfer
RFC 9154
| Document | Type | RFC - Proposed Standard (December 2021) | |
|---|---|---|---|
| Authors | James Gould , Richard Wilhelm | ||
| Last updated | 2021-12-30 | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Formats | |||
| Additional resources | Mailing list discussion | ||
| IESG | Responsible AD | Murray Kucherawy | |
| Send notices to | (None) |
RFC 9154
Internet Engineering Task Force (IETF) J. Gould
Request for Comments: 9154 R. Wilhelm
Category: Standards Track Verisign, Inc.
ISSN: 2070-1721 December 2021
Extensible Provisioning Protocol (EPP) Secure Authorization Information
for Transfer
Abstract
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.
Status of This Memo
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 Notice
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.
Table of Contents
1. Introduction
1.1. Conventions Used in This Document
2. Registrant, Registrar, Registry
3. Signaling Client and Server Support
4. Secure Authorization Information
4.1. Secure Random Authorization Information
4.2. Authorization Information Time To Live (TTL)
4.3. Authorization Information Storage and Transport
4.4. Authorization Information Matching
5. Create, Transfer, and Secure Authorization Information
5.1. <Create> Command
5.2. <Update> Command
5.3. <Info> Command and Response
5.4. <Transfer> Request Command
6. Transition Considerations
6.1. Transition Phase 1 - Features
6.2. Transition Phase 2 - Storage
6.3. Transition Phase 3 - Enforcement
7. IANA Considerations
7.1. XML Namespace
7.2. EPP Extension Registry
8. Security Considerations
9. References
9.1. Normative References
9.2. Informative References
Acknowledgements
Authors' Addresses
1. Introduction
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:
Strong Random Authorization Information: The EPP RFCs define the
password-based authorization information value using an XML
schema "normalizedString" type, so they don't restrict what can
be used in any substantial way. This operational practice
defines the recommended mechanism for creating a strong random
authorization value that would be generated by the client.
Short-Lived Authorization Information: The EPP RFCs don't explicitly
support short-lived authorization information or a TTL for
authorization information, but there are EPP RFC features that
can be leveraged to support short-lived authorization
information. All of these features are compatible with the EPP
RFCs, though not mandatory to implement. As stated in
Section 2.6 of [RFC5731], authorization information is assigned
when a domain object is created, which results in long-lived
authorization information. This specification changes the nature
of the authorization information from long lived to short lived.
If authorization information is set only when a transfer is in
process, the server needs to support an empty authorization
information value on create, support setting and unsetting
authorization information, and support automatically unsetting
the authorization information upon a successful transfer. All of
these features can be supported by the EPP RFCs.
Storing Authorization Information Securely: The EPP RFCs don't
specify where and how the authorization information is stored in
the client or the server, so there are no restrictions on
defining an operational practice for storing the authorization
information securely. The operational practice will require the
client to not store the authorization information and will
require the server to store the authorization information using a
cryptographic hash with at least a 256-bit hash function, such as
SHA-256 [FIPS-180-4], and with a per-authorization information
random salt with at least 128 bits. Returning the authorization
information set in an EPP info response will not be supported.
1.1. Conventions Used in This Document
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:
domain: urn:ietf:params:xml:ns:domain-1.0
contact: urn:ietf:params:xml:ns:contact-1.0
2. Registrant, Registrar, Registry
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:
Registrant: [RFC8499] defines the registrant as "an individual or
organization on whose behalf a name in a zone is registered by
the registry." The registrant can be the owner of any object in
the registry, such as a domain name or a contact. The registrant
interfaces with the registrar for provisioning the objects. A
transfer is coordinated by the registrant to transfer the
sponsorship of the object from one registrar to another. The
authorization information is meant to authenticate the registrant
as the owner of the object to the non-sponsoring registrar and to
authorize the transfer.
Registrar: [RFC8499] defines the registrar as "a service provider
that acts as a go-between for registrants and registries." The
registrar interfaces with the registrant for the provisioning of
objects, such as domain names and contacts, and with the
registries to satisfy the registrant's provisioning requests. A
registrar may (1) directly interface with the registrant or
(2) indirectly interface with the registrant, typically through
one or more resellers. Implementing a transfer using secure
authorization information extends through the registrar's
reseller channel up to the direct interface with the registrant.
The registrar's interface with the registries uses EPP. The
registrar's interface with its reseller channel or the registrant
is registrar specific. In the EPP RFCs, the registrar is
referred to as the "client", since EPP is the protocol used
between the registrar and the registry. The sponsoring registrar
is the authorized registrar to manage objects on behalf of the
registrant. A non-sponsoring registrar is not authorized to
manage objects on behalf of the registrant. A transfer of an
object's sponsorship is from one registrar, referred to as the
"losing registrar", to another registrar, referred to as the
"gaining registrar".
Registry: [RFC8499] defines the registry as "the administrative
operation of a zone that allows registration of names within that
zone." The registry typically interfaces with the registrars
over EPP and generally does not interact directly with the
registrant. In the EPP RFCs, the registry is referred to as the
"server", since EPP is the protocol used between the registrar
and the registry. The registry has a record of the sponsoring
registrar for each object and provides the mechanism (over EPP)
to coordinate a transfer of an object's sponsorship between
registrars.
3. Signaling Client and Server Support
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:
1. Support for an empty authorization information value with a
<create> command.
2. Support for unsetting authorization information with an <update>
command.
3. Support for validating authorization information with an <info>
command.
4. Support for not returning an indication of whether the
authorization information is set or unset to the non-sponsoring
registrar.
5. Support for returning an empty authorization information value to
the sponsoring registrar when the authorization information is
set in an info response.
6. Support for allowing the passing of a matching non-empty
authorization information value to authorize a transfer.
7. Support for automatically unsetting the authorization information
upon successful completion of a transfer.
A server that receives the namespace URI in the client's <login>
command extension services can expect the following supported
behavior by the client:
1. Support for the generation of authorization information using a
secure random value.
2. Support for only setting the authorization information when a
transfer is in process.
4. Secure Authorization Information
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.
4.1. Secure Random Authorization Information
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 / log_2 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 / log_2 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 / log_2 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.)
4.2. Authorization Information Time To Live (TTL)
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.
4.3. Authorization Information Storage and Transport
To protect the disclosure of the authorization information, the
following requirements apply:
1. The authorization information MUST be stored by the registry
using a strong one-way cryptographic hash with at least a 256-bit
hash function, such as SHA-256 [FIPS-180-4], and with a per-
authorization information random salt with at least 128 bits.
2. An empty authorization information value MUST be stored as an
undefined value that is referred to as a "NULL" value. The
representation of a NULL (undefined) value is dependent on the
type of database used.
3. The authorization information MUST NOT be stored by the losing
registrar.
4. The authorization information MUST only be stored by the gaining
registrar as a "transient" value in support of the transfer
process.
5. The plain-text version of the authorization information MUST NOT
be written to any logs by a registrar or the registry, nor
otherwise recorded where it will persist beyond the transfer
process.
6. All communication that includes the authorization information
MUST be over an encrypted channel (for example, see [RFC5734])
for EPP.
7. The registrar's interface for communicating the authorization
information with the registrant MUST be over an authenticated and
encrypted channel.
4.4. Authorization Information Matching
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:
1. Any input authorization information value MUST NOT match an unset
authorization information value. For example, in [RFC5731] the
input <domain:pw>2fooBAR</domain:pw> must not match an unset
authorization information value that used <domain:null/> or
<domain:pw/>.
2. An empty input authorization information value MUST NOT match any
set authorization information value.
3. A non-empty input authorization information value MUST be hashed
and matched against the set authorization information value,
which is stored using the same hash algorithm.
5. Create, Transfer, and Secure Authorization Information
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:
1. The registrant requests to register the object with the
registrar. The registrar sends the <create> command with an
empty authorization information value to the registry, as
described in Section 5.1.
2. The registrant requests from the losing registrar the
authorization information to provide to the gaining registrar.
3. The losing registrar generates a secure random authorization
information value and sends it to the registry, as described in
Section 5.2, and then provides it to the registrant.
4. The registrant provides the authorization information value to
the gaining registrar.
5. The gaining registrar optionally verifies the authorization
information with the <info> command to the registry, as described
in Section 5.3.
6. The gaining registrar sends the transfer request with the
authorization information to the registry, as described in
Section 5.4.
7. If the transfer completes successfully, the registry
automatically unsets the authorization information; otherwise,
the losing registrar unsets the authorization information when
the TTL expires; see Section 5.2.
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.
5.1. <Create> Command
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>
5.2. <Update> Command
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&Satran, et al. Standards Track [Page 187]
RFC 3720 iSCSI April 2004
holds for a single connection session with regard to connection
restart. The keys that fall into this category have the use: LO
(Leading Only).
Keys that can only be used during login have the use: IO (initialize
only), while those that can be used in both the Login Phase and Full
Feature Phase have the use: ALL.
Keys that can only be used during Full Feature Phase use FFPO (Full
Feature Phase only).
Keys marked as Any-Stage may also appear in the SecurityNegotiation
stage while all other keys described in this chapter are operational
keys.
Keys that do not require an answer are marked as Declarative.
Key scope is indicated as session-wide (SW) or connection-only (CO).
Result function, wherever mentioned, states the function that can be
applied to check the validity of the responder selection. Minimum
means that the selected value cannot exceed the offered value.
Maximum means that the selected value cannot be lower than the
offered value. AND means that the selected value must be a possible
result of a Boolean "and" function with an arbitrary Boolean value
(e.g., if the offered value is No the selected value must be No). OR
means that the selected value must be a possible result of a Boolean
"or" function with an arbitrary Boolean value (e.g., if the offered
value is Yes the selected value must be Yes).
12.1. HeaderDigest and DataDigest
Use: IO
Senders: Initiator and Target
Scope: CO
HeaderDigest = <list-of-values>
DataDigest = <list-of-values>
Default is None for both HeaderDigest and DataDigest.
Digests enable the checking of end-to-end, non-cryptographic data
integrity beyond the integrity checks provided by the link layers and
the covering of the whole communication path including all elements
that may change the network level PDUs such as routers, switches, and
proxies.
Satran, et al. Standards Track [Page 188]
RFC 3720 iSCSI April 2004
The following table lists cyclic integrity checksums that can be
negotiated for the digests and that MUST be implemented by every
iSCSI initiator and target. These digest options only have error
detection significance.
+---------------------------------------------+
| Name | Description | Generator |
+---------------------------------------------+
| CRC32C | 32 bit CRC |0x11edc6f41|
+---------------------------------------------+
| None | no digest |
+---------------------------------------------+
The generator polynomial for this digest is given in
hex-notation (e.g., 0x3b stands for 0011 1011 and the polynomial is
x**5+X**4+x**3+x+1).
When the Initiator and Target agree on a digest, this digest MUST be
used for every PDU in Full Feature Phase.
Padding bytes, when present in a segment covered by a CRC, SHOULD be
set to 0 and are included in the CRC.
The CRC MUST be calculated by a method that produces the same
results as the following process:
- The PDU bits are considered as the coefficients of a
polynomial M(x) of degree n-1; bit 7 of the lowest numbered
byte is considered the most significant bit (x^n-1), followed
by bit 6 of the lowest numbered byte through bit 0 of the
highest numbered byte (x^0).
- The most significant 32 bits are complemented.
- The polynomial is multiplied by x^32 then divided by G(x). The
generator polynomial produces a remainder R(x) of degree <= 31.
- The coefficients of R(x) are considered a 32 bit sequence.
- The bit sequence is complemented and the result is the CRC.
- The CRC bits are mapped into the digest word. The x^31
coefficient in bit 7 of the lowest numbered byte of the digest
continuing through to the byte up to the x^24 coefficient in
bit 0 of the lowest numbered byte, continuing with the x^23
coefficient in bit 7 of next byte through x^0 in bit 0 of the
highest numbered byte.
Satran, et al. Standards Track [Page 189]
RFC 3720 iSCSI April 2004
- Computing the CRC over any segment (data or header) extended
to include the CRC built using the generator 0x11edc6f41 will
always get the value 0x1c2d19ed as its final remainder (R(x)).
This value is given here in its polynomial form (i.e., not
mapped as the digest word).
For a discussion about selection criteria for the CRC, see
[RFC3385]. For a detailed analysis of the iSCSI polynomial, see
[Castagnoli93].
Private or public extension algorithms MAY also be negotiated for
digests. Whenever a private or public digest extension algorithm is
part of the default offer (the offer made in absence of explicit
administrative action) the implementer MUST ensure that CRC32C is
listed as an alternative in the default offer and "None" is not
part of the default offer.
Extension digest algorithms MUST be named using one of the following
two formats:
a) Y-reversed.vendor.dns_name.do_something=
b) Y<#><IANA-registered-string>=
Digests named using the Y- format are used for private purposes
(unregistered). Digests named using the Y# format (public extension)
must be registered with IANA and MUST be described by an
informational RFC.
For private extension digests, to identify the vendor, we suggest
you use the reversed DNS-name as a prefix to the proper digest
names.
The part of digest-name following Y- and Y# MUST conform to the
format for standard-label specified in Section 5.1 Text Format.
Support for public or private extension digests is OPTIONAL.
12.2. MaxConnections
Use: LO
Senders: Initiator and Target
Scope: SW
Irrelevant when: SessionType=Discovery
MaxConnections=<numerical-value-from-1-to-65535>
Default is 1.
Result function is Minimum.
Satran, et al. Standards Track [Page 190]
RFC 3720 iSCSI April 2004
Initiator and target negotiate the maximum number of connections
requested/acceptable.
12.3. SendTargets
Use: FFPO
Senders: Initiator
Scope: SW
For a complete description, see Appendix D. - SendTargets
Operation -.
12.4. TargetName
Use: IO by initiator, FFPO by target - only as response to a
SendTargets, Declarative, Any-Stage
Senders: Initiator and Target
Scope: SW
TargetName=<iSCSI-name-value>
Examples:
TargetName=iqn.1993-11.com.disk-vendor:diskarrays.sn.45678
TargetName=eui.020000023B040506
The initiator of the TCP connection MUST provide this key to the
remote endpoint in the first login request if the initiator is not
establishing a discovery session. The iSCSI Target Name specifies
the worldwide unique name of the target.
The TargetName key may also be returned by the "SendTargets" text
request (which is its only use when issued by a target).
TargetName MUST not be redeclared within the login phase.
Satran, et al. Standards Track [Page 191]
RFC 3720 iSCSI April 2004
12.5. InitiatorName
Use: IO, Declarative, Any-Stage
Senders: Initiator
Scope: SW
InitiatorName=<iSCSI-name-value>
Examples:
InitiatorName=iqn.1992-04.com.os-vendor.plan9:cdrom.12345
InitiatorName=iqn.2001-02.com.ssp.users:customer235.host90
The initiator of the TCP connection MUST provide this key to the
remote endpoint at the first Login of the Login Phase for every
connection. The InitiatorName key enables the initiator to identify
itself to the remote endpoint.
InitiatorName MUST not be redeclared within the login phase.
12.6. TargetAlias
Use: ALL, Declarative, Any-Stage
Senders: Target
Scope: SW
TargetAlias=<iSCSI-local-name-value>
Examples:
TargetAlias=Bob-s Disk
TargetAlias=Database Server 1 Log Disk
TargetAlias=Web Server 3 Disk 20
If a target has been configured with a human-readable name or
description, this name SHOULD be communicated to the initiator during
a Login Response PDU if SessionType=Normal (see Section 12.21
SessionType). This string is not used as an identifier, nor is it
meant to be used for authentication or authorization decisions. It
can be displayed by the initiator's user interface in a list of
targets to which it is connected.
Satran, et al. Standards Track [Page 192]
RFC 3720 iSCSI April 2004
12.7. InitiatorAlias
Use: ALL, Declarative, Any-Stage
Senders: Initiator
Scope: SW
InitiatorAlias=<iSCSI-local-name-value>
Examples:
InitiatorAlias=Web Server 4
InitiatorAlias=spyalley.nsa.gov
InitiatorAlias=Exchange Server
If an initiator has been configured with a human-readable name or
description, it SHOULD be communicated to the target during a Login
Request PDU. If not, the host name can be used instead. This string
is not used as an identifier, nor is meant to be used for
authentication or authorization decisions. It can be displayed by
the target's user interface in a list of initiators to which it is
connected.
12.8. TargetAddress
Use: ALL, Declarative, Any-Stage
Senders: Target
Scope: SW
TargetAddress=domainname[:port][,portal-group-tag]
The domainname can be specified as either a DNS host name, a
dotted-decimal IPv4 address, or a bracketed IPv6 address as specified
in [RFC2732].
If the TCP port is not specified, it is assumed to be the
IANA-assigned default port for iSCSI (see Section 13 IANA
Considerations).
If the TargetAddress is returned as the result of a redirect status
in a login response, the comma and portal group tag MUST be omitted.
If the TargetAddress is returned within a SendTargets response, the
portal group tag MUST be included.
Satran, et al. Standards Track [Page 193]
RFC 3720 iSCSI April 2004
Examples:
TargetAddress=10.0.0.1:5003,1
TargetAddress=[1080:0:0:0:8:800:200C:417A],65
TargetAddress=[1080::8:800:200C:417A]:5003,1
TargetAddress=computingcenter.example.com,23
Use of the portal-group-tag is described in Appendix D.
- SendTargets Operation -. The formats for the port and
portal-group-tag are the same as the one specified in Section 12.9
TargetPortalGroupTag.
12.9. TargetPortalGroupTag
Use: IO by target, Declarative, Any-Stage
Senders: Target
Scope: SW
TargetPortalGroupTag=<16-bit-binary-value>
Examples:
TargetPortalGroupTag=1
The target portal group tag is a 16-bit binary-value that uniquely
identifies a portal group within an iSCSI target node. This key
carries the value of the tag of the portal group that is servicing
the Login request. The iSCSI target returns this key to the
initiator in the Login Response PDU to the first Login Request PDU
that has the C bit set to 0 when TargetName is given by the
initiator.
For the complete usage expectations of this key see Section 5.3 Login
Phase.
12.10. InitialR2T
Use: LO
Senders: Initiator and Target
Scope: SW
Irrelevant when: SessionType=Discovery
InitialR2T=<boolean-value>
Examples:
I->InitialR2T=No
T->InitialR2T=No
Satran, et al. Standards Track [Page 194]
RFC 3720 iSCSI April 2004
Default is Yes.
Result function is OR.
The InitialR2T key is used to turn off the default use of R2T for
unidirectional and the output part of bidirectional commands, thus
allowing an initiator to start sending data to a target as if it has
received an initial R2T with Buffer Offset=Immediate Data Length and
Desired Data Transfer Length=(min(FirstBurstLength, Expected Data
Transfer Length) - Received Immediate Data Length).
The default action is that R2T is required, unless both the initiator
and the target send this key-pair attribute specifying InitialR2T=No.
Only the first outgoing data burst (immediate data and/or separate
PDUs) can be sent unsolicited (i.e., not requiring an explicit R2T).
12.11. ImmediateData
Use: LO
Senders: Initiator and Target
Scope: SW
Irrelevant when: SessionType=Discovery
ImmediateData=<boolean-value>
Default is Yes.
Result function is AND.
The initiator and target negotiate support for immediate data. To
turn immediate data off, the initiator or target must state its
desire to do so. ImmediateData can be turned on if both the
initiator and target have ImmediateData=Yes.
If ImmediateData is set to Yes and InitialR2T is set to Yes
(default), then only immediate data are accepted in the first burst.
If ImmediateData is set to No and InitialR2T is set to Yes, then the
initiator MUST NOT send unsolicited data and the target MUST reject
unsolicited data with the corresponding response code.
If ImmediateData is set to No and InitialR2T is set to No, then the
initiator MUST NOT send unsolicited immediate data, but MAY send one
unsolicited burst of Data-Out PDUs.
If ImmediateData is set to Yes and InitialR2T is set to No, then the
initiator MAY send unsolicited immediate data and/or one unsolicited
burst of Data-Out PDUs.
Satran, et al. Standards Track [Page 195]
RFC 3720 iSCSI April 2004
The following table is a summary of unsolicited data options:
+----------+-------------+------------------+--------------+
|InitialR2T|ImmediateData| Unsolicited |Immediate Data|
| | | Data Out PDUs | |
+----------+-------------+------------------+--------------+
| No | No | Yes | No |
+----------+-------------+------------------+--------------+
| No | Yes | Yes | Yes |
+----------+-------------+------------------+--------------+
| Yes | No | No | No |
+----------+-------------+------------------+--------------+
| Yes | Yes | No | Yes |
+----------+-------------+------------------+--------------+
12.12. MaxRecvDataSegmentLength
Use: ALL, Declarative
Senders: Initiator and Target
Scope: CO
MaxRecvDataSegmentLength=<numerical-value-512-to-(2**24-1)>
Default is 8192 bytes.
The initiator or target declares the maximum data segment length in
bytes it can receive in an iSCSI PDU.
The transmitter (initiator or target) is required to send PDUs with a
data segment that does not exceed MaxRecvDataSegmentLength of the
receiver.
A target receiver is additionally limited by MaxBurstLength for
solicited data and FirstBurstLength for unsolicited data. An
initiator MUST NOT send solicited PDUs exceeding MaxBurstLength nor
unsolicited PDUs exceeding FirstBurstLength (or
FirstBurstLength-Immediate Data Length if immediate data were sent).
12.13. MaxBurstLength
Use: LO
Senders: Initiator and Target
Scope: SW
Irrelevant when: SessionType=Discovery
MaxBurstLength=<numerical-value-512-to-(2**24-1)>
Satran, et al. Standards Track [Page 196]
RFC 3720 iSCSI April 2004
Default is 262144 (256 Kbytes).
Result function is Minimum.
The initiator and target negotiate maximum SCSI data payload in bytes
in a Data-In or a solicited Data-Out iSCSI sequence. A sequence
consists of one or more consecutive Data-In or Data-Out PDUs that end
with a Data-In or Data-Out PDU with the F bit set to one.
12.14. FirstBurstLength
Use: LO
Senders: Initiator and Target
Scope: SW
Irrelevant when: SessionType=Discovery
Irrelevant when: ( InitialR2T=Yes and ImmediateData=No )
FirstBurstLength=<numerical-value-512-to-(2**24-1)>
Default is 65536 (64 Kbytes).
Result function is Minimum.
The initiator and target negotiate the maximum amount in bytes of
unsolicited data an iSCSI initiator may send to the target during the
execution of a single SCSI command. This covers the immediate data
(if any) and the sequence of unsolicited Data-Out PDUs (if any) that
follow the command.
FirstBurstLength MUST NOT exceed MaxBurstLength.
12.15. DefaultTime2Wait
Use: LO
Senders: Initiator and Target
Scope: SW
DefaultTime2Wait=<numerical-value-0-to-3600>
Default is 2.
Result function is Maximum.
The initiator and target negotiate the minimum time, in seconds, to
wait before attempting an explicit/implicit logout or an active task
reassignment after an unexpected connection termination or a
connection reset.
A value of 0 indicates that logout or active task reassignment can be
attempted immediately.
Satran, et al. Standards Track [Page 197]
RFC 3720 iSCSI April 2004
12.16. DefaultTime2Retain
Use: LO Senders: Initiator and Target Scope: SW
DefaultTime2Retain=<numerical-value-0-to-3600>
Default is 20. Result function is Minimum.
The initiator and target negotiate the maximum time, in seconds after
an initial wait (Time2Wait), before which an active task reassignment
is still possible after an unexpected connection termination or a
connection reset.
This value is also the session state timeout if the connection in
question is the last LOGGED_IN connection in the session.
A value of 0 indicates that connection/task state is immediately
discarded by the target.
12.17. MaxOutstandingR2T
Use: LO
Senders: Initiator and Target
Scope: SW
MaxOutstandingR2T=<numerical-value-from-1-to-65535>
Irrelevant when: SessionType=Discovery
Default is 1.
Result function is Minimum.
Initiator and target negotiate the maximum number of outstanding R2Ts
per task, excluding any implied initial R2T that might be part of
that task. An R2T is considered outstanding until the last data PDU
(with the F bit set to 1) is transferred, or a sequence reception
timeout (Section 6.1.4.1 Recovery Within-command) is encountered for
that data sequence.
12.18. DataPDUInOrder
Use: LO
Senders: Initiator and Target
Scope: SW
Irrelevant when: SessionType=Discovery
DataPDUInOrder=<boolean-value>
Satran, et al. Standards Track [Page 198]
RFC 3720 iSCSI April 2004
Default is Yes.
Result function is OR.
No is used by iSCSI to indicate that the data PDUs within sequences
can be in any order. Yes is used to indicate that data PDUs within
sequences have to be at continuously increasing addresses and
overlays are forbidden.
12.19. DataSequenceInOrder
Use: LO
Senders: Initiator and Target
Scope: SW
Irrelevant when: SessionType=Discovery
DataSequenceInOrder=<boolean-value>
Default is Yes.
Result function is OR.
A Data Sequence is a sequence of Data-In or Data-Out PDUs that end
with a Data-In or Data-Out PDU with the F bit set to one. A Data-Out
sequence is sent either unsolicited or in response to an R2T.
Sequences cover an offset-range.
If DataSequenceInOrder is set to No, Data PDU sequences may be
transferred in any order.
If DataSequenceInOrder is set to Yes, Data Sequences MUST be
transferred using continuously non-decreasing sequence offsets (R2T
buffer offset for writes, or the smallest SCSI Data-In buffer offset
within a read data sequence).
If DataSequenceInOrder is set to Yes, a target may retry at most the
last R2T, and an initiator may at most request retransmission for the
last read data sequence. For this reason, if ErrorRecoveryLevel is
not 0 and DataSequenceInOrder is set to Yes then MaxOustandingR2T
MUST be set to 1.
12.20. ErrorRecoveryLevel
Use: LO
Senders: Initiator and Target
Scope: SW
ErrorRecoveryLevel=<numerical-value-0-to-2>
Satran, et al. Standards Track [Page 199]
RFC 3720 iSCSI April 2004
Default is 0.
Result function is Minimum.
The initiator and target negotiate the recovery level supported.
Recovery levels represent a combination of recovery capabilities.
Each recovery level includes all the capabilities of the lower
recovery levels and adds some new ones to them.
In the description of recovery mechanisms, certain recovery classes
are specified. Section 6.1.5 Error Recovery Hierarchy describes the
mapping between the classes and the levels.
12.21. SessionType
Use: LO, Declarative, Any-Stage
Senders: Initiator
Scope: SW
SessionType= <Discovery|Normal>
Default is Normal.
The initiator indicates the type of session it wants to create. The
target can either accept it or reject it.
A discovery session indicates to the Target that the only purpose of
this Session is discovery. The only requests a target accepts in
this type of session are a text request with a SendTargets key and a
logout request with reason "close the session".
The discovery session implies MaxConnections = 1 and overrides both
the default and an explicit setting.
12.22. The Private or Public Extension Key Format
Use: ALL
Senders: Initiator and Target
Scope: specific key dependent
X-reversed.vendor.dns_name.do_something=
or
X<#><IANA-registered-string>=
Satran, et al. Standards Track [Page 200]
RFC 3720 iSCSI April 2004
Keys with this format are used for public or private extension
purposes. These keys always start with X- if unregistered with IANA
(private) or X# if registered with IANA (public).
For unregistered keys, to identify the vendor, we suggest you use the
reversed DNS-name as a prefix to the key-proper.
The part of key-name following X- and X# MUST conform to the format
for key-name specified in Section 5.1 Text Format.
For IANA registered keys the string following X# must be registered
with IANA and the use of the key MUST be described by an
informational RFC.
Vendor specific keys MUST ONLY be used in normal sessions.
Support for public or private extension keys is OPTIONAL.
13. IANA Considerations
This section conforms to [RFC2434].
The well-known user TCP port number for iSCSI connections assigned by
IANA is 3260 and this is the default iSCSI port. Implementations
needing a system TCP port number may use port 860, the port assigned
by IANA as the iSCSI system port; however in order to use port 860,
it MUST be explicitly specified - implementations MUST NOT default to
use of port 860, as 3260 is the only allowed default.
Extension keys, authentication methods, or digest types for which a
vendor or group of vendors intend to provide publicly available
descriptions MUST be described by an RFC and MUST be registered with
IANA.
The IANA has set up the following three registries:
a) iSCSI extended key registry
b) iSCSI authentication methods registry
c) iSCSI digests registry
[RFC3723] also instructs IANA to maintain a registry for the values
of the SRP_GROUP key. The format of these values must conform to the
one specified for iSCSI extension item-label in Section 13.5.4
Standard iSCSI extension item-label format.
Satran, et al. Standards Track [Page 201]
RFC 3720 iSCSI April 2004
For the iSCSI authentication methods registry and the iSCSI digests
registry, IANA MUST also assign a 16-bit unsigned integer number (the
method number for the authentication method and the digest number for
the digest).
The following initial values for the registry for authentication
methods are specified by the standards action of this document:
Authentication Method | Number |
+----------------------------------------+--------+
| CHAP | 1 |
+----------------------------------------+--------+
| SRP | 2 |
+----------------------------------------+--------+
| KRB5 | 3 |
+----------------------------------------+--------+
| SPKM1 | 4 |
+----------------------------------------+--------+
| SPKM2 | 5 |
+----------------------------------------+--------+
All other record numbers from 0 to 255 are reserved. IANA will
register numbers above 255.
Authentication methods with numbers above 255 MUST be unique within
the registry and MUST be used with the prefix Z#.
The following initial values for the registry for digests are
specified by the standards action of this document:
Digest | Number |
+----------------------------------------+--------+
| CRC32C | 1 |
+----------------------------------------+--------+
All other record numbers from 0 to 255 are reserved. IANA will
register numbers above 255.
Digests with numbers above 255 MUST be unique within the registry and
MUST be used with the prefix Y#.
The RFC that describes the item to be registered MUST indicate in the
IANA Considerations section the string and iSCSI registry to which it
should be recorded.
Extension Keys, Authentication Methods, and digests (iSCSI extension
items) must conform to a number of requirements as described below.
Satran, et al. Standards Track [Page 202]
RFC 3720 iSCSI April 2004
13.1. Naming Requirements
Each iSCSI extension item must have a unique name in its category.
This name will be used as a standard-label for the key, access
method, or digest and must conform to the syntax specified in Section
13.5.4 Standard iSCSI extension item-label format for iSCSI extension
item-labels.
13.2. Mechanism Specification Requirements
For iSCSI extension items all of the protocols and procedures used by
a given iSCSI extension item must be described, either in the
specification of the iSCSI extension item itself or in some other
publicly available specification, in sufficient detail for the iSCSI
extension item to be implemented by any competent implementor. Use
of secret and/or proprietary methods in iSCSI extension items are
expressly prohibited. In addition, the restrictions imposed by
[RFC1602] on the standardization of patented algorithms must be
respected.
13.3. Publication Requirements
All iSCSI extension items must be described by an RFC. The RFC may
be informational rather than Standards-Track, although Standards
Track review and approval are encouraged for all iSCSI extension
items.
13.4. Security Requirements
Any known security issues that arise from the use of the iSCSI
extension item must be completely and fully described. It is not
required that the iSCSI extension item be secure or that it be free
from risks, but that the known risks be identified. Publication of a
new iSCSI extension item does not require an exhaustive security
review, and the security considerations section is subject to
continuing evaluation.
Additional security considerations should be addressed by publishing
revised versions of the iSCSI extension item specification.
For each of these registries, IANA must record the registered string,
which MUST conform to the format rules described in Section 13.5.4
Standard iSCSI extension item-label format for iSCSI extension
item-labels, and the RFC number that describes it. The key prefix
(X#, Y# or Z#) is not part of the recorded string.
Satran, et al. Standards Track [Page 203]
RFC 3720 iSCSI April 2004
13.5. Registration Procedure
Registration of a new iSCSI extension item starts with the
construction of an Internet Draft to become an RFC.
13.5.1. Present the iSCSI extension item to the Community
Send a proposed access type specification to the IPS WG mailing list,
or if the IPS WG is disbanded at the registration time, to a mailing
list designated by the IETF Transport Area Director for a review
period of a month. The intent of the public posting is to solicit
comments and feedback on the iSCSI extension item specification and a
review of any security considerations.
13.5.2. iSCSI extension item review and IESG approval
When the one month period has passed, the IPS WG chair or a person
nominated by the IETF Transport Area Director (the iSCSI extension
item reviewer) forwards the Internet Draft to the IESG for
publication as an informational RFC or rejects it. If the
specification is a standards track document, the usual IETF
procedures for such documents are followed.
Decisions made by the iSCSI extension item reviewer must be published
within two weeks after the month-long review period. Decisions made
by the iSCSI extension item reviewer can be appealed through the IESG
appeal process.
13.5.3. IANA Registration
Provided that the iSCSI extension item has either passed review or
has been successfully appealed to the IESG, and the specification is
published as an RFC, then IANA will register the iSCSI extension item
and make the registration available to the community.
13.5.4. Standard iSCSI extension item-label format
The following character symbols are used iSCSI extension item-labels
(the hexadecimal values represent Unicode code points):
(a-z, A-Z) - letters
(0-9) - digits
"." (0x2e) - dot
"-" (0x2d) - minus
"+" (0x2b) - plus
"@" (0x40) - commercial at
"_" (0x5f) - underscore
Satran, et al. Standards Track [Page 204]
RFC 3720 iSCSI April 2004
An iSCSI extension item-label is a string of one or more characters
that consist of letters, digits, dot, minus, plus, commercial at, or
underscore. An iSCSI extension item-label MUST begin with a capital
letter and must not exceed 63 characters.
13.6. IANA Procedures for Registering iSCSI extension items
The identity of the iSCSI extension item reviewer is communicated to
the IANA by the IESG. Then, the IANA only acts in response to iSCSI
extension item definitions that are approved by the iSCSI extension
item reviewer and forwarded by the reviewer to the IANA for
registration, or in response to a communication from the IESG that an
iSCSI extension item definition appeal has overturned the iSCSI
extension item reviewer's ruling.
References
Normative References
[CAM] ANSI X3.232-199X, Common Access Method-3.
[EUI] "Guidelines for 64-bit Global Identifier (EUI-64)",
http:
//standards.ieee.org/regauth/oui/tutorials/EUI64.html
[OUI] "IEEE OUI and Company_Id Assignments",
http://standards.ieee.org/regauth/oui
[RFC791] Postel, J., "Internet Protocol", STD 5, RFC 791,
September 1981.
[RFC793] Postel, J., "Transmission Control Protocol", STD 7,
RFC 793, September 1981.
[RFC1035] Mockapetris, P., "Domain Names - Implementation and
Specification", STD 13, RFC 1035, November 1987.
[RFC1122] Braden, R., Ed., "Requirements for Internet Hosts-
Communication Layer", STD 3, RFC 1122, October 1989.
[RFC1510] Kohl, J. and C. Neuman, "The Kerberos Network
Authentication Service (V5)", RFC 1510, September
1993.
[RFC1737] Sollins, K. and L. Masinter "Functional Requirements
for Uniform Resource Names"RFC 1737, December 1994.
Satran, et al. Standards Track [Page 205]
RFC 3720 iSCSI April 2004
[RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism",
RFC 1964, June 1996.
[RFC1982] Elz, R. and R. Bush, "Serial Number Arithmetic", RFC
1982, August 1996.
[RFC1994] Simpson, W., "PPP Challenge Handshake Authentication
Protocol (CHAP)", RFC 1994, August 1996.
[RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism
(SPKM)", RFC 2025, October 1996.
[RFC2045] Borenstein, N. and N. Freed, "MIME (Multipurpose
Internet Mail Extensions) Part One: Mechanisms for
Specifying and Describing the Format of Internet
Message Bodies", RFC 2045, November 1996.
[RFC2119] Bradner, S. "Key Words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2279] Yergeau, F., "UTF-8, a Transformation Format of ISO
10646", RFC 2279 October 1996.
[RFC2373] Hinden, R. and S. Deering, "IP Version 6 Addressing
Architecture", RFC 2373, July 1998.
[RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter "Uniform
Resource Identifiers", RFC 2396, August 1998.
[RFC2401] Kent, S. and R. Atkinson, "Security Architecture for
the Internet Protocol", RFC 2401, November 1998.
[RFC2404] Madson, C. and R. Glenn, "The Use of HMAC-SHA-1-96
within ESP and AH", RFC 2404, November 1998.
[RFC2406] Kent, S. and R. Atkinson, "IP Encapsulating Security
Payload (ESP)", RFC 2406, November 1998.
[RFC2407] Piper, D., "The Internet IP Security Domain of
Interpretation of ISAKMP", RFC 2407, November 1998.
[RFC2409] Harkins, D. and D. Carrel, "The Internet Key Exchange
(IKE)", RFC2409, November 1998.
[RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing
an IANA Considerations Section in RFCs.", BCP 26, RFC
2434, October 1998.
Satran, et al. Standards Track [Page 206]
RFC 3720 iSCSI April 2004
[RFC2451] Pereira, R. and R. Adams " The ESP CBC-Mode Cipher
Algorithms", RFC 2451, November 1998.
[RFC2732] Hinden, R., Carpenter, B. and L. Masinter, "Format for
Literal IPv6 Addresses in URL's", RFC 2451, December
1999.
[RFC2945] Wu, T., "The SRP Authentication and Key Exchange
System", RFC 2945, September 2000.
[RFC3066] Alvestrand, H., "Tags for the Identification of
Languages", STD 47, RFC 3066, January 2001.
[RFC3454] Hoffman, P. and M. Blanchet, "Preparation of
Internationalized Strings ("stringprep")", RFC 3454,
December 2002.
[RFC3566] Frankel, S. and H. Herbert, "The AES-XCBC-MAC-96
Algorithm and Its Use With IPsec", RFC 3566, September
2003.
[RFC3686] Housley, R., "Using Advanced Encryption Standard (AES)
Counter Mode with IPsec Encapsulating Security Payload
(ESP)", RFC 3686, January 2004.
[RFC3722] Bakke, M., "String Profile for Internet Small Computer
Systems Interface (iSCSI) Names", RFC 3722, March
2004.
[RFC3723] Aboba, B., Tseng, J., Walker, J., Rangan, V. and F.
Travostino, "Securing Block Storage Protocols over
IP", RFC 3723, March 2004.
[SAM2] T10/1157D, SCSI Architecture Model - 2 (SAM-2).
[SBC] NCITS.306-1998, SCSI-3 Block Commands (SBC).
[SPC3] T10/1416-D, SCSI Primary Commands-3.
[UNICODE] Unicode Standard Annex #15, "Unicode Normalization
Forms", http://www.unicode.org/unicode/reports/tr15
Satran, et al. Standards Track [Page 207]
RFC 3720 iSCSI April 2004
Informative References
[BOOT] P. Sarkar, et al., "Bootstrapping Clients using the
iSCSI Protocol", Work in Progress, July 2003.
[Castagnoli93] G. Castagnoli, S. Braeuer and M. Herrman "Optimization
of Cyclic Redundancy-Check Codes with 24 and 32 Parity
Bits", IEEE Transact. on Communications, Vol. 41, No.
6, June 1993.
[CORD] Chadalapaka, M. and R. Elliott, "SCSI Command
Ordering Considerations with iSCSI", Work in Progress.
[RFC3347] Krueger, M., Haagens, R., Sapuntzakis, C. and M.
Bakke, "Small Computer Systems Interface protocol over
the Internet (iSCSI) Requirements and Design
Considerations", RFC 3347, July 2002.
[RFC3385] Sheinwald, D., Staran, J., Thaler, P. and V. Cavanna,
"Internet Protocol Small Computer System Interface
(iSCSI) Cyclic Redundancy Check (CRC)/Checksum
Considerations", RFC 3385, September 2002.
[RFC3721] Bakke M., Hafner, J., Hufferd, J., Voruganti, K. and
M. Krueger, "Internet Small Computer Systems Interface
(iSCSI) Naming and Discovery, RFC 3721, March 2004.
[SEQ-EXT] Kent, S., "IP Encapsulating Security Payload (ESP)",
Work in Progress, July 2002.
Satran, et al. Standards Track [Page 208]
RFC 3720 iSCSI April 2004
Appendix A. Sync and Steering with Fixed Interval Markers
This appendix presents a simple scheme for synchronization (PDU
boundary retrieval). It uses markers that include synchronization
information placed at fixed intervals in the TCP stream.
A Marker consists of:
Byte / 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0| Next-iSCSI-PDU-start pointer - copy #1 |
+---------------+---------------+---------------+---------------+
4| Next-iSCSI-PDU-start pointer - copy #2 |
+---------------+---------------+---------------+---------------+
The Marker scheme uses payload byte stream counting that includes
every byte placed by iSCSI in the TCP stream except for the markers
themselves. It also excludes any bytes that TCP counts but are not
originated by iSCSI.
Markers MUST NOT be included in digest calculation.
The Marker indicates the offset to the next iSCSI PDU header. The
Marker is eight bytes in length and contains two 32-bit offset fields
that indicate how many bytes to skip in the TCP stream in order to
find the next iSCSI PDU header. The marker uses two copies of the
pointer so that a marker that spans a TCP packet boundary should
leave at least one valid copy in one of the packets.
The structure and semantics of an inserted marker are independent of
the marker interval.
The use of markers is negotiable. The initiator and target MAY
indicate their readiness to receive and/or send markers during login
separately for each connection. The default is No.
A.1. Markers At Fixed Intervals
A marker is inserted at fixed intervals in the TCP byte stream.
During login, each end of the iSCSI session specifies the interval at
which it is willing to receive the marker, or it disables the marker
altogether. If a receiver indicates that it desires a marker, the
sender MAY agree (during negotiation) and provide the marker at the
desired interval. However, in certain environments, a sender that
does not provide markers to a receiver that wants markers may suffer
an appreciable performance degradation.
Satran, et al. Standards Track [Page 209]
RFC 3720 iSCSI April 2004
The marker interval and the initial marker-less interval are counted
in terms of the bytes placed in the TCP stream data by iSCSI.
When reduced to iSCSI terms, markers MUST indicate the offset to a
4-byte word boundary in the stream. The least significant two bits
of each marker word are reserved and are considered 0 for offset
computation.
Padding iSCSI PDU payloads to 4-byte word boundaries simplifies
marker manipulation.
A.2. Initial Marker-less Interval
To enable the connection setup including the Login Phase negotiation,
marking (if any) is only started at the first marker interval after
the end of the Login Phase. However, in order to enable the marker
inclusion and exclusion mechanism to work without knowledge of the
length of the Login Phase, the first marker will be placed in the TCP
stream as if the Marker-less interval had included markers.
Thus, all markers appear in the stream at locations conforming to the
formula: [(MI + 8) * n - 8] where MI = Marker Interval, n = integer
number.
For example, if the marker interval is 512 bytes and the login ended
at byte 1003 (first iSCSI placed byte is 0), the first marker will be
inserted after byte 1031 in the stream.
A.3. Negotiation
The following operational key=value pairs are used to negotiate the
fixed interval markers. The direction (output or input) is relative
to the initiator.
A.3.1. OFMarker, IFMarker
Use: IO
Senders: Initiator and Target
Scope: CO
OFMarker=<boolean-value>
IFMarker=<boolean-value>
Default is No.
Result function is AND.
Satran, et al. Standards Track [Page 210]
RFC 3720 iSCSI April 2004
OFMarker is used to turn on or off the initiator to target markers
on the connection. IFMarker is used to turn on or off the target to
initiator markers on the connection.
Examples:
I->OFMarker=Yes,IFMarker=Yes
T->OFMarker=Yes,IFMarker=Yes
Results in the Marker being used in both directions while:
I->OFMarker=Yes,IFMarker=Yes
T->OFMarker=Yes,IFMarker=No
Results in Marker being used from the initiator to the target, but
not from the target to initiator.
A.3.2. OFMarkInt, IFMarkInt
Use: IO
Senders: Initiator and Target
Scope: CO
OFMarkInt is Irrelevant when: OFMarker=No
IFMarkInt is Irrelevant when: IFMarker=No
Offering:
OFMarkInt=<numeric-range-from-1-to-65535>
IFMarkInt=<numeric-range-from-1-to-65535>
Responding:
OFMarkInt=<numeric-value-from-1-to-65535>|Reject
IFMarkInt=<numeric-value-from-1-to-65535>|Reject
OFMarkInt is used to set the interval for the initiator to target
markers on the connection. IFMarkInt is used to set the interval for
the target to initiator markers on the connection.
For the offering, the initiator or target indicates the minimum to
maximum interval (in 4-byte words) it wants the markers for one or
both directions. In case it only wants a specific value, only a
single value has to be specified. The responder selects a value
within the minimum and maximum offered or the only value offered or
indicates through the xFMarker key=value its inability to set and/or
receive markers. When the interval is unacceptable the responder
answers with "Reject". Reject is resetting the marker function in
the specified direction (Output or Input) to No.
Satran, et al. Standards Track [Page 211]
RFC 3720 iSCSI April 2004
The interval is measured from the end of a marker to the beginning of
the next marker. For example, a value of 1024 means 1024 words (4096
bytes of iSCSI payload between markers).
The default is 2048.
Appendix B. Examples
B.1. Read Operation Example
+------------------+-----------------------+----------------------+
|Initiator Function| PDU Type | Target Function |
+------------------+-----------------------+----------------------+
| Command request |SCSI Command (READ)>>> | |
| (read) | | |
+------------------+-----------------------+----------------------+
| | |Prepare Data Transfer |
+------------------+-----------------------+----------------------+
| Receive Data | <<< SCSI Data-In | Send Data |
+------------------+-----------------------+----------------------+
| Receive Data | <<< SCSI Data-In | Send Data |
+------------------+-----------------------+----------------------+
| Receive Data | <<< SCSI Data-In | Send Data |
+------------------+-----------------------+----------------------+
| | <<< SCSI Response |Send Status and Sense |
+------------------+-----------------------+----------------------+
| Command Complete | | |
+------------------+-----------------------+----------------------+
Satran, et al. Standards Track [Page 212]
RFC 3720 iSCSI April 2004
B.2. Write Operation Example
+------------------+-----------------------+---------------------+
|Initiator Function| PDU Type | Target Function |
+------------------+-----------------------+---------------------+
| Command request |SCSI Command (WRITE)>>>| Receive command |
| (write) | | and queue it |
+------------------+-----------------------+---------------------+
| | | Process old commands|
+------------------+-----------------------+---------------------+
| | | Ready to process |
| | <<< R2T | WRITE command |
+------------------+-----------------------+---------------------+
| Send Data | SCSI Data-Out >>> | Receive Data |
+------------------+-----------------------+---------------------+
| | <<< R2T | Ready for data |
+------------------+-----------------------+---------------------+
| | <<< R2T | Ready for data |
+------------------+-----------------------+---------------------+
| Send Data | SCSI Data-Out >>> | Receive Data |
+------------------+-----------------------+---------------------+
| Send Data | SCSI Data-Out >>> | Receive Data |
+------------------+-----------------------+---------------------+
| | <<< SCSI Response |Send Status and Sense|
+------------------+-----------------------+---------------------+
| Command Complete | | |
+------------------+-----------------------+---------------------+
Satran, et al. Standards Track [Page 213]
RFC 3720 iSCSI April 2004
B.3. R2TSN/DataSN Use Examples
Output (write) data DataSN/R2TSN Example
+------------------+-----------------------+----------------------+
|Initiator Function| PDU Type & Content | Target Function |
+------------------+-----------------------+----------------------+
| Command request |SCSI Command (WRITE)>>>| Receive command |
| (write) | | and queue it |
+------------------+-----------------------+----------------------+
| | | Process old commands |
+------------------+-----------------------+----------------------+
| | <<< R2T | Ready for data |
| | R2TSN = 0 | |
+------------------+-----------------------+----------------------+
| | <<< R2T | Ready for more data |
| | R2TSN = 1 | |
+------------------+-----------------------+----------------------+
| Send Data | SCSI Data-Out >>> | Receive Data |
| for R2TSN 0 | DataSN = 0, F=0 | |
+------------------+-----------------------+----------------------+
| Send Data | SCSI Data-Out >>> | Receive Data |
| for R2TSN 0 | DataSN = 1, F=1 | |
+------------------+-----------------------+----------------------+
| Send Data | SCSI Data >>> | Receive Data |
| for R2TSN 1 | DataSN = 0, F=1 | |
+------------------+-----------------------+----------------------+
| | <<< SCSI Response |Send Status and Sense |
| | ExpDataSN = 0 | |
+------------------+-----------------------+----------------------+
| Command Complete | | |
+------------------+-----------------------+----------------------+
Satran, et al. Standards Track [Page 214]
RFC 3720 iSCSI April 2004
Input (read) data DataSN Example
+------------------+-----------------------+----------------------+
|Initiator Function| PDU Type | Target Function |
+------------------+-----------------------+----------------------+
| Command request |SCSI Command (READ)>>> | |
| (read) | | |
+------------------+-----------------------+----------------------+
| | | Prepare Data Transfer|
+------------------+-----------------------+----------------------+
| Receive Data | <<< SCSI Data-In | Send Data |
| | DataSN = 0, F=0 | |
+------------------+-----------------------+----------------------+
| Receive Data | <<< SCSI Data-In | Send Data |
| | DataSN = 1, F=0 | |
+------------------+-----------------------+----------------------+
| Receive Data | <<< SCSI Data-In | Send Data |
| | DataSN = 2, F=1 | |
+------------------+-----------------------+----------------------+
| | <<< SCSI Response |Send Status and Sense |
| | ExpDataSN = 3 | |
+------------------+-----------------------+----------------------+
| Command Complete | | |
+------------------+-----------------------+----------------------+
Satran, et al. Standards Track [Page 215]
RFC 3720 iSCSI April 2004
Bidirectional DataSN Example
+------------------+-----------------------+----------------------+
|Initiator Function| PDU Type | Target Function |
+------------------+-----------------------+----------------------+
| Command request |SCSI Command >>> | |
| (Read-Write) | Read-Write | |
+------------------+-----------------------+----------------------+
| | | Process old commands |
+------------------+-----------------------+----------------------+
| | <<< R2T | Ready to process |
| | R2TSN = 0 | WRITE command |
+------------------+-----------------------+----------------------+
| * Receive Data | <<< SCSI Data-In | Send Data |
| | DataSN = 1, F=0 | |
+------------------+-----------------------+----------------------+
| * Receive Data | <<< SCSI Data-In | Send Data |
| | DataSN = 2, F=1 | |
+------------------+-----------------------+----------------------+
| * Send Data | SCSI Data-Out >>> | Receive Data |
| for R2TSN 0 | DataSN = 0, F=1 | |
+------------------+-----------------------+----------------------+
| | <<< SCSI Response |Send Status and Sense |
| | ExpDataSN = 3 | |
+------------------+-----------------------+----------------------+
| Command Complete | | |
+------------------+-----------------------+----------------------+
*) Send data and Receive Data may be transferred simultaneously as in
an atomic Read-Old-Write-New or sequentially as in an atomic
Read-Update-Write (in the latter case the R2T may follow the received
data).
Satran, et al. Standards Track [Page 216]
RFC 3720 iSCSI April 2004
Unsolicited and immediate output (write) data with DataSN Example
+------------------+-----------------------+----------------------+
|Initiator Function| PDU Type & Content | Target Function |
+------------------+-----------------------+----------------------+
| Command request |SCSI Command (WRITE)>>>| Receive command |
| (write) |F=0 | and data |
|+ Immediate data | | and queue it |
+------------------+-----------------------+----------------------+
| Send Unsolicited | SCSI Write Data >>> | Receive more Data |
| Data | DataSN = 0, F=1 | |
+------------------+-----------------------+----------------------+
| | | Process old commands |
+------------------+-----------------------+----------------------+
| | <<< R2T | Ready for more data |
| | R2TSN = 0 | |
+------------------+-----------------------+----------------------+
| Send Data | SCSI Write Data >>> | Receive Data |
| for R2TSN 0 | DataSN = 0, F=1 | |
+------------------+-----------------------+----------------------+
| | <<< SCSI Response |Send Status and Sense |
| | | |
+------------------+-----------------------+----------------------+
| Command Complete | | |
+------------------+-----------------------+----------------------+
B.4. CRC Examples
N.B. all Values are Hexadecimal
32 bytes of zeroes:
Byte: 0 1 2 3
0: 00 00 00 00
...
28: 00 00 00 00
CRC: aa 36 91 8a
32 bytes of ones:
Byte: 0 1 2 3
0: ff ff ff ff
...
28: ff ff ff ff
Satran, et al. Standards Track [Page 217]
RFC 3720 iSCSI April 2004
CRC: 43 ab a8 62
32 bytes of incrementing 00..1f:
Byte: 0 1 2 3
0: 00 01 02 03
...
28: 1c 1d 1e 1f
CRC: 4e 79 dd 46
32 bytes of decrementing 1f..00:
Byte: 0 1 2 3
0: 1f 1e 1d 1c
...
28: 03 02 01 00
CRC: 5c db 3f 11
An iSCSI - SCSI Read (10) Command PDU
Byte: 0 1 2 3
0: 01 c0 00 00
4: 00 00 00 00
8: 00 00 00 00
12: 00 00 00 00
16: 14 00 00 00
20: 00 00 04 00
24: 00 00 00 14
28: 00 00 00 18
32: 28 00 00 00
36: 00 00 00 00
40: 02 00 00 00
44: 00 00 00 00
CRC: 56 3a 96 d9
Satran, et al. Standards Track [Page 218]
lt;/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>
5.3. <Info> Command and Response
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>
5.4. <Transfer> Request Command
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.
6. Transition Considerations
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:
1. The registrant requests to register the object with the
registrar. The registrar sends the <create> command, with a non-
empty authorization information value, to the registry. The
registry stores the authorization information as an encrypted
value and requires a non-empty authorization information value
for the life of the object. The registrar may store the long-
lived authorization information.
2. At the time of transfer, the registrant requests from the losing
registrar the authorization information to provide to the gaining
registrar.
3. The losing registrar retrieves the locally stored authorization
information or queries the registry for authorization information
using the <info> command, and provides it to the registrant. If
the registry is queried, the authorization information is
decrypted and the plain-text authorization information is
returned in the info response to the registrar.
4. The registrant provides the authorization information value to
the gaining registrar.
5. The gaining registrar optionally verifies the authorization
information with the <info> command to the registry, by passing
the authorization information in the <info> command to the
registry.
6. The gaining registrar sends the transfer request with the
authorization information to the registry. The registry will
decrypt the stored authorization information to compare to the
passed authorization information.
7. If the transfer completes successfully, the authorization
information is not touched by the registry and may be updated by
the gaining registrar using the <update> command. If the
transfer is canceled or rejected, the losing registrar may reset
the authorization information using the <update> command.
The gaps between the Classic Authorization Information Model and the
Secure Authorization Information Model include the following:
1. Registry requirement for a non-empty authorization information
value on create and for the life of the object versus the
authorization information not being set on create and only being
set when a transfer is in process.
2. Registry not allowing the authorization information to be unset
versus providing support for unsetting the authorization
information in the <update> command.
3. Registry storing the authorization information as an encrypted
value versus a hashed value.
4. Registry support for returning the authorization information
versus not returning the authorization information in the info
response.
5. Registry not touching the authorization information versus the
registry automatically unsetting the authorization information
upon a successful transfer.
6. Registry possibly validating a shorter authorization information
value using password complexity rules versus validating the
randomness of a longer authorization information value that meets
the required bits of entropy.
The transition can be handled in the three phases defined in
Sections 6.1, 6.2, and 6.3.
6.1. Transition Phase 1 - Features
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:
<Create> Command: Change the <create> command to make the
authorization information optional, by allowing both a non-empty
value and an empty value. This enables a registrar to optionally
create objects without an authorization information value, as
described in Section 5.1.
<Update> Command: Change the <update> command to allow unsetting the
authorization information, as described in Section 5.2. This
enables the registrar to optionally unset the authorization
information when the TTL expires or when the transfer is canceled
or rejected.
Transfer Approve Command and Transfer Auto-Approve: Change the
transfer approve command and the transfer auto-approve to
automatically unset the authorization information. This sets the
default state of the object to not have the authorization
information set. The registrar implementing the Secure
Authorization Information Model will not set the authorization
information for an inbound transfer, and the registrar
implementing the Classic Authorization Information Model will set
the new authorization information upon a successful transfer.
Info Response: Change the <info> command to not return the
authorization information in the info response, as described in
Section 5.3. This sets up the implementation of "Transition Phase
2 - Storage" (Section 6.2), since the dependency on returning the
authorization information in the info response will be removed.
This feature is the only one that is not an optional change to the
registrar, and this change could potentially break the client, so
it's recommended that the registry provide notice of the change.
<Info> Command and Transfer Request: Change the <info> command and
the transfer request to ensure that a registrar cannot get an
indication that the authorization information is set or not set by
returning the EPP error result code of 2202 when comparing a
passed authorization to a non-matching set authorization
information value or an unset value.
6.2. Transition Phase 2 - Storage
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:
Hash New Authorization Information Values: Change the <create>
command and the <update> command to hash rather than encrypt the
authorization information.
Support Comparison against Encrypted or Hashed Authorization
Information: Change the <info> command and the <transfer> request
command to be able to compare a passed authorization information
value with either a hashed or encrypted authorization information
value. This requires that the stored values be self-identifying
as being in hashed or encrypted form.
Hash Existing Encrypted Authorization Information Values: Convert
the encrypted authorization information values stored in the
registry database to hashed values. This update will not be
visible to the registrar. The conversion can be done over a
period of time, depending on registry policy.
6.3. Transition Phase 3 - Enforcement
The goal of "Transition Phase 3 - Enforcement" is to complete the
implementation of the Secure Authorization Information Model, by
enforcing the following:
Disallow Authorization Information on <Create> Command: Change the
<create> command to not allow the passing of a non-empty
authorization information value. This behavior could potentially
break the client, so it's recommended that the registry provide
notice of this change.
Validate the Strong Random Authorization Information: Change the
validation of the authorization information in the <update>
command to ensure at least 128 bits of entropy.
7. IANA Considerations
7.1. XML Namespace
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:
URI: urn:ietf:params:xml:ns:epp:secure-authinfo-transfer-1.0
Registrant Contact: IESG
XML: None. Namespace URIs do not represent an XML specification.
7.2. EPP Extension Registry
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:
Name of Extension: "Extensible Provisioning Protocol (EPP) Secure
Authorization Information for Transfer"
Document status: Standards Track
Reference: RFC 9154
Registrant Name and Email Address: IESG (iesg@ietf.org)
TLDs: Any
IPR Disclosure: None
Status: Active
Notes: None
8. Security Considerations
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.
9. References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>.
[RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker,
"Randomness Requirements for Security", BCP 106, RFC 4086,
DOI 10.17487/RFC4086, June 2005,
<https://www.rfc-editor.org/info/rfc4086>.
[RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
STD 69, RFC 5730, DOI 10.17487/RFC5730, August 2009,
<https://www.rfc-editor.org/info/rfc5730>.
[RFC5731] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
Domain Name Mapping", STD 69, RFC 5731,
DOI 10.17487/RFC5731, August 2009,
<https://www.rfc-editor.org/info/rfc5731>.
[RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
Contact Mapping", STD 69, RFC 5733, DOI 10.17487/RFC5733,
August 2009, <https://www.rfc-editor.org/info/rfc5733>.
[RFC5734] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
Transport over TCP", STD 69, RFC 5734,
DOI 10.17487/RFC5734, August 2009,
<https://www.rfc-editor.org/info/rfc5734>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS
Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499,
January 2019, <https://www.rfc-editor.org/info/rfc8499>.
[W3C.REC-xml-20081126]
Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
Edition)", World Wide Web Consortium Recommendation REC-
xml-20081126, November 2008,
<https://www.w3.org/TR/2008/REC-xml-20081126>.
9.2. Informative References
[FIPS-140-2]
National Institute of Standards and Technology, U.S.
Department of Commerce, "NIST Federal Information
Processing Standards (FIPS) Publication 140-2",
DOI 10.6028/NIST.FIPS.140-2, May 2001,
<https://csrc.nist.gov/publications/detail/fips/140/2/
final>.
[FIPS-180-4]
National Institute of Standards and Technology, U.S.
Department of Commerce, "Secure Hash Standard, NIST
Federal Information Processing Standards (FIPS)
Publication 180-4", DOI 10.6028/NIST.FIPS.180-4, August
2015,
<https://csrc.nist.gov/publications/detail/fips/180/4/
final>.
[RFC7451] Hollenbeck, S., "Extension Registry for the Extensible
Provisioning Protocol", RFC 7451, DOI 10.17487/RFC7451,
February 2015, <https://www.rfc-editor.org/info/rfc7451>.
Acknowledgements
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.
Authors' Addresses
James Gould
Verisign, Inc.
12061 Bluemont Way
Reston, VA 20190
United States of America
Email: jgould@verisign.com
URI: https://www.verisign.com
Richard Wilhelm
Verisign, Inc.
12061 Bluemont Way
Reston, VA 20190
United States of America
Email: 4rickwilhelm@gmail.com
URI: https://www.verisign.com