Network Working Group J. Gould Internet-Draft VeriSign, Inc. Intended status: Standards Track March 30, 2017 Expires: October 1, 2017 Data Set File Format draft-gould-regext-dataset-01 Abstract This document defines a Data Set File (DSF) format that can be used to define and pass bulk data between a client and a server. This format is extensible to pass any set of simple data types in a set of records contained in the body of the file. The file format also supports storing the result of processing the data set that MAY be generated by the server and returned to the client. The file format consists of an XML definition header and a Comma-Separated Values (CSV) data section delimited by "-----BEGIN DATA SET-----" and "----- END DATA SET-----" lines. The XML definition header defines the format of the CSV data section, contains additional meta-data, and optionally includes a digital signature to identify the source and ensure that the data has not been tampered with between the parties (source, client, and server). The interface (manual or automated) that is used to submit the file and receive the result file is not defined within this document. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on October 1, 2017. Gould Expires October 1, 2017 [Page 1] Internet-Draft Data Set File Format March 2017 Copyright Notice Copyright (c) 2017 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 (http://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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Conventions Used in This Document . . . . . . . . . . . . 4 2. General Conventions . . . . . . . . . . . . . . . . . . . . . 5 2.1. Date and Time . . . . . . . . . . . . . . . . . . . . . . 5 2.2. Checksum . . . . . . . . . . . . . . . . . . . . . . . . 5 2.3. Type and Subtype . . . . . . . . . . . . . . . . . . . . 5 2.4. Fields . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.4.1. Base Field Types . . . . . . . . . . . . . . . . . . 6 2.4.2. Data Set Field Elements . . . . . . . . . . . . . . . 8 2.4.2.1. Field Element Extensibility . . . . . . . . . . . 8 2.5. Routing . . . . . . . . . . . . . . . . . . . . . . . . . 10 3. Data Set File (DSF) Format . . . . . . . . . . . . . . . . . 11 3.1. Header Format . . . . . . . . . . . . . . . . . . . . . . 12 3.1.1. element . . . . . . . . . . . . . . 12 3.1.2. element . . . . . . . 13 3.1.2.1. Signed Definition Data . . . . . . . . . . . . . 13 3.1.3. element . . . . . . . . . . . . 15 3.2. Body Format . . . . . . . . . . . . . . . . . . . . . . . 18 4. Object Description . . . . . . . . . . . . . . . . . . . . . 18 4.1. Domain Name Object . . . . . . . . . . . . . . . . . . . 18 4.2. Host Object . . . . . . . . . . . . . . . . . . . . . . . 25 4.3. Contact Object . . . . . . . . . . . . . . . . . . . . . 31 4.4. Verification Code Object . . . . . . . . . . . . . . . . 39 5. Result Codes . . . . . . . . . . . . . . . . . . . . . . . . 41 6. Example Data Set File (DSF) Result Files . . . . . . . . . . 44 6.1. Example Data Set File (DSF) with Result Data . . . . . . 44 7. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 47 7.1. Data Set Schema . . . . . . . . . . . . . . . . . . . . . 47 7.2. Domain Name Schema . . . . . . . . . . . . . . . . . . . 56 7.3. Host Schema . . . . . . . . . . . . . . . . . . . . . . . 60 7.4. Contact Schema . . . . . . . . . . . . . . . . . . . . . 62 Gould Expires October 1, 2017 [Page 2] Internet-Draft Data Set File Format March 2017 7.5. Verification Code Schema . . . . . . . . . . . . . . . . 67 7.6. Routing Schema . . . . . . . . . . . . . . . . . . . . . 69 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 8.1. XML Namespace . . . . . . . . . . . . . . . . . . . . . . 69 9. Security Considerations . . . . . . . . . . . . . . . . . . . 71 10. Normative References . . . . . . . . . . . . . . . . . . . . 72 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 73 Appendix B. Change History . . . . . . . . . . . . . . . . . . . 74 B.1. Change from 00 to 01 . . . . . . . . . . . . . . . . . . 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 74 1. Introduction This document defines a Data Set File (DSF) format that can be used to define and pass bulk data between a client and a server. The client and server MAY leverage a provisioning protocol like EPP, as defined in [RFC5730], to provision individual objects, but the provisioning protocol MAY NOT handle all provisioning use cases. This document defines a format for bulk provisioning requests that can be generated by authorized third parties, can be generated by clients that choose not to leverage the provisioning protocol, and can be supported by servers to process bulk requests in a controlled manner that throttles the processing against the provisioning database. Bulk requests can include court orders, out-of-band client requests to fix data, the backfill of data like contact or verification code data, and a large set of ad-hoc needs. This format is extensible to pass any set of simple data types in a set of records contained in the body of the file. The file format also supports storing the result of processing the data set that MAY be generated by the server and returned to the client. The file format consists of an XML definition header and a Comma-Separated Values (CSV) data section delimited by "-----BEGIN DATA SET-----" and "-----END DATA SET-----" lines. The XML definition header defines the format of the CSV data section, contains additional meta-data, and optionally includes a digital signature to identify the source and ensure that the data has not been tampered with between the parties (source, client, and server) using XML Signature [W3C.CR-xmldsig-core2-20120124]. All XML Signature [W3C.CR-xmldsig-core2-20120124] data is "base64" encoded, in conformance with [RFC2045], by default to mitigate any validation errors due to whitespace formatting. The interface (manual or automated) that is used to submit the file and receive the result file is not defined within this document and must be documented independently. Please see Section 9 for a description of the issues associated with transport security. Gould Expires October 1, 2017 [Page 3] Internet-Draft Data Set File Format March 2017 1.1. Conventions Used in This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. XML 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. The following XML abbreviations are used: "eppcom" XML namespace prefix refers to "urn:ietf:params:xml:ns:eppcom-1.0" XML namespace in [RFC5730]. "domain" XML namespace prefix refers to "urn:ietf:params:xml:ns:domain-1.0" XML namespace in [RFC5731]. "host" XML namespace prefix refers to "urn:ietf:params:xml:ns:host-1.0" XML namespace in [RFC5732]. "contact" XML namespace prefix refers to "urn:ietf:params:xml:ns:contact-1.0" XML namespace in [RFC5733]. "dataSet-1.0" is used as an abbreviation for "urn:ietf:params:xml:ns:dataSet-1.0". "dataSet" XML namespace prefix refers to "urn:ietf:params:xml:ns:dataSet-1.0" XML namespace. "dsfDomain-1.0" is used as an abbreviation for "urn:ietf:params:xml:ns:dsfDomain-1.0". "dsfDomain" XML namespace prefix refers to "urn:ietf:params:xml:ns:dsfDomain-1.0" XML namespace. "dsfHost-1.0" is used as an abbreviation for "urn:ietf:params:xml:ns:dsfHost-1.0". "dsfHost" XML namespace prefix refers to "urn:ietf:params:xml:ns:dsfHost-1.0" XML namespace. "dsfContact-1.0" is used as an abbreviation for "urn:ietf:params:xml:ns:dsfContact-1.0". "dsfContact" XML namespace prefix refers to "urn:ietf:params:xml:ns:dsfContact-1.0" XML namespace. "dsfVerificationCode-1.0" is used as an abbreviation for "urn:ietf:params:xml:ns:dsfVerificationCode-1.0". "dsfVerificationCode" XML namespace prefix refers to "urn:ietf:params:xml:ns:dsfVerificationCode-1.0" XML namespace. "dsfRouting-1.0" is used as an abbreviation for "urn:ietf:params:xml:ns:dsfRouting-1.0". Implementations MUST NOT depend on the XML namespace prefix used in this document and instead MUST employ a proper namespace-aware XML parser and serializer to interpret and output the XML. Gould Expires October 1, 2017 [Page 4] Internet-Draft Data Set File Format March 2017 2. General Conventions This document includes a general set of attributes and terms that are described here. 2.1. Date and Time Numerous fields indicate "dates", such as the creation date of the DSF. These fields SHALL contain timestamps indicating the date and time in UTC as specified in [RFC3339], with no offset from the zero meridian. 2.2. Checksum The checksum of the body of the file, as defined by the body rule of the Data Set File (DSF) ABNF (Section 3), MUST use CRC32, that is the algorithm used in the ISO 13239 standard [iso13239] and in section 8.1.1.6.2 of ITU-T recommendation V.42 [itu-t-V.42]. 2.3. Type and Subtype There can be many different Data Set File (DSF) types supported based on the objects, operations, and the specific scenarios. To make it easier to negotiate the client's intent of the DSF with the server's set of supported DSF files, the DSF supports the definition of a type and an optional sub-type. The supported list of types and sub-types is up to server policy. The server SHOULD provide the possible set of supported DSF type and sub-type values to the parties generating the DSF. The mechanism for providing the supported DSF type and sub- type values is not defined in this document but MAY require registration within an IANA registry. The element formally defines the DSF type, which indicates the expected set of fields defined under the element and the expected operation to be taken. An OPTIONAL "subType" attribute defines the sub-type that is used to further refine the purpose of the DSF. It is recommended that the server follows a consistent naming scheme for the values. One option is to delimit the value with a '.' and to include the object ("domain", "host", "contact, "verificationCode", etc.), the operation ("create", "renew, "transfer", "delete", "update", etc.), and the scoped name of the DSF. For example, to support the bulk update of encoded signed verification codes, the value can be set to "verificationCode.update.encodedSignedCode". To further sub-divide the "verificationCode.update.encodedSignedCode" type by locality, the "subType" attribute can be set to the locality name. For example, Gould Expires October 1, 2017 [Page 5] Internet-Draft Data Set File Format March 2017 the "china" verification profile supports two verification codes of type "domain" and "real-name", so the "verificationCode.update.encodedSignedCode" DSF type can include "china" for the "subType" attribute, as in verificationCode.update.encodedSignedCode. 2.4. Fields The element, an element in the header (Section 3.1), contains an ordered list of CSV fields used in the body of the file delimited by the character defined by the OPTIONAL "sep" attribute, with a default value of ",". A field child element substitutes for the abstract element. Each element defines the format of the CSV field contained in the body. The elements support the "type" attribute that defines the XML schema simple type of the field element. The abstract element does not directly define any attributes, but there are a couple attributes that a data set processor SHOULD support including: isRequired When the "isRequired" attribute is "true", it indicates that the field MUST be non-empty in the body and when set to "false", it indicates that the field MAY be empty in the body. The "isRequired" attribute MAY be specifically set for the field elements in the XML schema and MAY be overriden by specifying the attribute in the fields under the element. If no "isRequired" attribute is defined, the default value is "false". isPrimaryKey When the "isPrimaryKey" attribute is "true", it indicates that the field is part of the primary key of the records. The combination of the primary key fields MUST be unique across the set of records in the file. The "isPrimaryKey" attribute MAY be specifically set for the field elements in the XML schema and MAY be overridden by specifying the attribute in the fields under the element. If no "isPrimaryKey" attribute is defined, the default value is "false". 2.4.1. Base Field Types New field types can be defined that reside in the CSV records. To make the definition of new field types easier, a set of base field types are defined in the dataSet-1.0 XML schema that include: dataSet:fieldOptionalType The "dataSet:fieldOptionalType" type can be extended by a field that can be empty ("isRequired" = "false") Gould Expires October 1, 2017 [Page 6] Internet-Draft Data Set File Format March 2017 and is not a member of the primary key ("isPrimaryKey" = "false"). dataSet:fieldRequiredType The "dataSet:fieldRequiredType" type can be extended by a field that cannot be empty ("isRequired" = "true") and is not a member of the primary key ("isPrimaryKey" = "false"). dataSet:fieldPrimaryKeyType The "dataSet:fieldPrimaryKeyType" type can be extended by a field that cannot be empty ("isRequired" = "true") and is a member of the primary key ("isPrimaryKey" = "true"). dataSet:fListItemType The "dataSet:fListItemType" type is an extension of the "dataSet:fieldOptionalType" type that adds an OPTIONAL "op" attribute that reflects the operation to apply for the list item. The default "op" value is "replace". The list of possible "op" values is include below. A "dataSet:fListItemType" field with "op" set to "replace" MUST NOT be mixed with a matching "dataSet:fListItemType" field with "op" set to either "add" or "remove". "replace" Specifies that the list item will replace was is currently set for the object. The list of list items provided will replace the existing list of items set on the object. The concrete "dataSet:fListItemType" field along with the DSF type can determine what is the possible set of list item values. "add" Specifies that the list item should be added to the object if it is not already set. "rem" Specifies that the list item should be removed from the object and expects it to already be set. Example definition of the field element that extends the "dataSet:fieldPrimaryKeyType" base field type with the XML type dataSet:labelType and with the required "class" attribute: Gould Expires October 1, 2017 [Page 7] Internet-Draft Data Set File Format March 2017 2.4.2. Data Set Field Elements The dataSet-1.0 XML schema predefines a set of field elements that can be used as child elements of the element of the header to define the CSV record fields. The dataSet-1.0 field elements with the XML schema type value and the base type include: Field that represents the name of an object. This field extends a "dataSet:fieldPrimaryKeyType", as defined in Section 2.4.1, with the type="token". The required "class" attribute defines the class of the object, like the use of "domain" for a domain name. It is recommended to use an object specific name field if available, like . Object authorization information with type="eppcom:pwAuthInfoType". Field that represents the result of processing an individual record using the codes defined in Section 5. The field extends a "dataSet:fieldRequiredType", as defined in Section 2.4.1, with the type="dataSet:resultCodeType". Field containing the human-readable description of the result code. The field extends a "dataSet:fieldOptionalType", as defined in Section 2.4.1, with the type="normalizedString". The field includes the OPTIONAL "lang" attribute with the default value of "en" (English). Field containing the human-readable message that describes the reason for the error processing the record. The field extends the "dataSet:fieldOptionalType", as defined in Section 2.4.1, with the type="normalizedString". The language of the reason is identified the OPTIONAL "lang" attribute. If not specified, the default attribute value is "en" (English). Example definition for a result file generated by a server that includes a domain name with a result code, with an OPTIONAL result message, and an OPTIONAL result reason: 2.4.2.1. Field Element Extensibility New field elements MAY be defined in separate XML schemas and referenced as child elements of the element. The convention is to prefix all field elements with a lowercase "f", as in for the object name or for Gould Expires October 1, 2017 [Page 8] Internet-Draft Data Set File Format March 2017 the result code. The following are the steps to define a new field element: 1. Define a new XML schema or extend an existing XML schema to include the definition of the field element. The XML schema will have it's own XML namespace that will be referenced in the header of the Data Set File (DSF). 2. Define a new XML schema complexType that is a direct or indirect extension of the "dataSet:fieldType" complexType. The new complexType MUST directly, or indirectly define through extension, the following attibutes: "type" Defines the XML schema data type of the CSV field. The "default" value of the attribute is used to define the default CSV field type using an XML schema simple data type. Any XML namespaces MUST be escaped ("\:" instead of ":") so the XML parser of the header can ignore the reference during XML validation. The "type" attribute is used during CSV validation leveraging the XML schema simple data type to define the format. The "type" attribute can be overridden when referencing the field element in the header. The "type" attribute for the "dataSet:fResultCodeType" complexType is defined as . When using the default XML namespace, no escaping is necessary. For example for the "dataSet:fResultMsg" complexType, the "type" attribute is defined as . A validator of the Data Set File (DSF) will apply the XML schema type to the CSV fields. "isRequired" See the definition of the "isRequired" attribute in Section 2.4. A required field can extend the "dataSet:fieldRequiredType" complexType, as defined in Section 2.4.1, or can explicitly specify the attribute. For example, the "isRequired" attribute is set in the "dataSet:fieldRequiredType" complexType as . "isPrimaryKey" See the definition of the "isPrimaryKey" attribute in Section 2.4. A primary key field can extend the "dataSet:primaryKeyType" complexType, as defined in Section 2.4.1, or can explicitly specify the attribute. For example, the "isPrimaryKey" attribute is set in the "dataSet:fieldPrimaryKeyType" complexType as . 3. Define the field element that uses the new complexType defined above and that substitutes for the "dataSet:field" abstract element. An example of defining the "dataSet:fResultCode" field element is . Gould Expires October 1, 2017 [Page 9] Internet-Draft Data Set File Format March 2017 An example of defining the "dataSet:fResultReason" field element is . Example definition of the field element that is required to be non-empty and with the CSV field type "dataSet:resultCodeType": Example definition of the field element that may be empty (optional), with the CSV field type "normalizedString", and with the additional optional "lang" attribute: 2.5. Routing A Data Set File (DSF) MAY include data that targets multiple independent backend services, but the object alone cannot be used to determine the appropropriate backend service. An example is creating a Contact Object (Section 4.3) in the .EXAMPLE1 domain registry Gould Expires October 1, 2017 [Page 10] Internet-Draft Data Set File Format March 2017 service and creating another Contact Object (Section 4.3) in the .EXAMPLE2 domain registry service within a single DSF, where .EXAMPLE1 and .EXAMPLE2 are independent domain registry services. The Data Set File (DSF) processor MAY coordinate with the backend services to process each of the DSF records, but it is dependent on the client to specify the target backend service with each record. The Data Set File (DSF) field element used for routing a record to a specific backend service includes: Contains the unique sub-product name of a backend service with type="token". It is up to server policy on the valid list of sub-product values. An example of a sub- product value is the Top Level Domain (TLD) of a domain registry service. Routing is most applicable to objects like a Contact Object (Section 4.3) and a Host Object (Section 4.2), where the keys ( for the Contact Object and for the Host Object) MAY NOT be enough to uniqually identify a target domain registry service. An example of using the field for routing is provided with the "contact.create.routing" DSF in Section 4.3. 3. Data Set File (DSF) Format The Data Set File (DSF) format supports multiple types of requests and response files. All of these types of files support a general file format that includes a header that provides meta-data about the data including the what, who, when, and optionally the digital signature of the information, and the body containing the data. The Data Set File (DSF) syntax is specified using Augmented Backus-Naur Form (ABNF) grammar [RFC5234] as follows: Data Set File (DSF) ABNF file = header body header = dataSet-1-0 LF dataSet-1-0 = 1*(1*VCHAR LF) ; compliant to dataSet-1.0 body = start [data] end start = "-----BEGIN DATA SET-----" LF data = 1*VCHAR LF ; CSV compliant end = "-----END DATA SET-----" *1LF Gould Expires October 1, 2017 [Page 11] Internet-Draft Data Set File Format March 2017 3.1. Header Format The header of the Data Set File (DSF) is an XML document that complies with the dataSet-1.0 XML schema. The purpose of the header is to provide the meta-data about the data contained in the body. The element is the root XML element of the header and contains the following child element: ; or or Provides meta-data about the body of the file that is not digitally signed, as described in Section 3.1.1. Contains the encoded form of the digitally signed element, as described in in Section 3.1.2. Provides the high level result data with the processing of a request Data Set File (DSF) by the server, as described in Section 3.1.3. 3.1.1. element The element contains the meta-data of the body of the file that is not digitally signed. The element contains the following child elements: The type value and OPTIONAL "subType" attribute value of the Data Set File (DSF), as defined in Section 2.3. Ordered list of CSV fields as defined in Section 2.4. OPTIONAL unique identifier of the Data Set File (DSF). The client SHOULD assign a unique identifer when generating the Data Set File (DSF) and set it in the element. Contains the date and time of the Data Set File (DSF) creation. Gould Expires October 1, 2017 [Page 12] Internet-Draft Data Set File Format March 2017 Example element for setting verification codes on a domain name: verificationCode.update.encodedSignedCode abc-123 2016-04-03T22:00:00.0Z 3.1.2. element The element contains the encoded form of the digitally signed element, described in Section 3.1.2.1, with the encoding defined by the "encoding" attribute with the default "encoding" value of "base64". The "base64" encoded text of the element MUST conform to [RFC2045]. Example element, where "..." represents continuation of data for brevity: ICAgICAgPHZlcmlmaWNhdGlvbkNvZGU6c2lnbmVkQ29kZQogICAgICAgIHhtbG5z ... b25Db2RlOnNpZ25lZENvZGU+Cg== 3.1.2.1. Signed Definition Data The Signed Definition Data, represented by the element, is a signed extension of the element, defined in Section 3.1.1. The provides the meta-data about the body of the file, that is a fragment of XML that is digitally signed using XML Signature [W3C.CR-xmldsig-core2-20120124]. The element includes a required "id" attribute of type XSD ID for use with the IDREF URI from the Signature element. Setting the "id" attribute value to "signedData" is recommended. The certificate of the issuer MUST be included with the Signature so it can be chained with the issuer's certificate by the validating client. A checksum, as defined by the Section 2.2, of the body of Gould Expires October 1, 2017 [Page 13] Internet-Draft Data Set File Format March 2017 the file, as defined by the body rule of the Data Set File (DSF) ABNF, is included in the digitally signed data to ensure that it's covered by the Signature. The element contains the following child elements: The type value and OPTIONAL "subType" attribute value of the Data Set File (DSF), as defined in Section 2.3. Ordered list of CSV fields as defined in Section 2.4. OPTIONAL unique identifier of the data set. The source SHOULD assign a unique identifer when generating the data set and set it in the element. Contains the date and time of the data set creation. Checksum of the body of the file, as defined by the body rule of the Data Set File (DSF) ABNF, using the mechanism defined by the Section 2.2. XML Signature [W3C.CR-xmldsig-core2-20120124] for the . Use of a namespace prefix, like "dsig", is recommended for the XML Signature [W3C.CR-xmldsig-core2-20120124] elements. Example element, where "..." represents continuation of data for brevity: verificationCode.update.encodedSignedCode abc-123 2016-04-03T22:00:00.0Z 6F2B988F Gould Expires October 1, 2017 [Page 14] Internet-Draft Data Set File Format March 2017 wgyW3nZPoEfpptlhRILKnOQnbdtU6ArM7ShrAfHgDFg= jMu4PfyQGiJBF0GWSEPFCJjmywCEqR2h4LD+ge6XQ+JnmKFFCuCZS/3SLKAx0L1w ... ipJsXNa6osTUw1CzA7jfwA== MIIESTCCAzGgAwIBAgIBAjANBgkqhkiG9w0BAQsFADBiMQswCQYDVQQGEwJVUzEL ... AdXitTWFipaIGea9lEGFM0L9+Bg7XzNn4nVLXokyEB3bgS4scG6QznX23FGk 3.1.3. element The element contains the high level result data with the processing of a request Data Set File (DSF) by the server. the "code" attribute describes the success or failure of the processing using the code values defined in Section 5. The element contains the following child elements: OPTIONAL type value and OPTIONAL "subType" attribute value associaed with the request Data Set File (DSF), as defined in Section 2.3. The element MUST be returned if the request header is successfully parsed. OPTIONAL ordered list of CSV fields as defined in Section 2.4. If the element is not defined, then the data as defined by the data rule of the Data Set File (DSF) ABNF MUST be empty. OPTIONAL identifier of the Data Set File (DSF) formed using the element associated with the Gould Expires October 1, 2017 [Page 15] Internet-Draft Data Set File Format March 2017 request if supplied by the client and the request header is successfully parsed. Human-readable description of the result code. The language of the result is identified via an OPTIONAL "lang" attribute. If not specified, the default attribute value is "en" (English). OPTIONAL human-readable message that describes the reason for the error. The language of the reason is identified via an OPTIONAL "lang" attribute. If not specified, the default attribute value is "en" (English). OPTIONAL summary record result data. The summary data is associated with the count of the records (lines in request data). The element contains the following child elements: Total count of the records (lines in request data) processed by the server. Total count of the records (lines in request data) successfully processed by the server. Total count of the records (lines in request data) that failed processing by the server. Example successful element: verificationCode.update.encodedSignedCode abc-123 54322-XYZ Code Set processed successfully. 2 2 0 Gould Expires October 1, 2017 [Page 16] Internet-Draft Data Set File Format March 2017 Example element with some failures: verificationCode.update.encodedSignedCode abc-123 54322-XYZ Success with failures 4 1 3 Example failed element based on malformed request file: 54322-XYZ File syntax error Malformed request file Example failed element based on header syntax error: 54322-XYZ Header syntax error Header XML syntax error Gould Expires October 1, 2017 [Page 17] Internet-Draft Data Set File Format March 2017 Example failed element based on body syntax error: verificationCode.update.encodedSignedCode abc-123 54322-XYZ Body syntax error Invalid with fields definition 3.2. Body Format The body of the Data Set File (DSF) is a set of Comma-Separated Values (CSV) data that includes a leading "-----BEGIN CODE SET-----" line and a trailing "-----END CODE SET-----" line. The format of the CSV data is defined by the element in the header (Section 3.1), that includes the delimiter and the ordered set of fields (Section 2.4) with their XML simple type and descriptor attributes like "isRequired", "isPrimaryKey", "class", and "codeType". Example body for a result file generated by a server that includes a success and a set of failed records with a mix of messages and reasons.: -----BEGIN DATA SET----- domain1.example,1000,Success, domain2.example,2303,Object does not exist, domain3.example,2201,Authorization error, domain4.example,2302,Object exists,domain code already -----END DATA SET----- 4. Object Description This section describes the base objects supported by this specification: 4.1. Domain Name Object The domain name object is based on the EPP domain name mapping specified in [RFC5731]. The Data Set File (DSF) field elements specific to the domain name object include: Gould Expires October 1, 2017 [Page 18] Internet-Draft Data Set File Format March 2017 Domain name field with type="eppcom:labelType" and isRequired="true". Domain name initial or extension period of the expiration date with type="domain:pLimitType". Domain name initial or extension period unit of the expiration date with type="domain:pUnitType". Domain name server is an extension of the "dataSet:fListItemType" field, described in Section 2.4.1, with type="eppcom:labelType". Domain contact identifer with type="eppcom:clIDType" and with required "role" attribute. The possible values of the "role" attribute include "registrant", "admin", "tech", and "billing". The status of the domain name is an extension of the "dataSet:fListItemType" field, described in Section 2.4.1, with type="domain:statusValueType". Contains the DS key tag value per [RFC5910] with type="unsignedShort". Contains the DS algorithm value per [RFC5910] with type="unsignedByte". Contains the DS digest type value per [RFC5910] with type="unsignedByte". Contains the DS digest value per [RFC5910] with type="hexBinary". Contains the flags field value per [RFC5910] with type="unsignedShort". Contains the Key protocol value per [RFC5910] with type="unsignedByte". Contains the Key algorithm value per [RFC5910] with type="unsignedByte". Contains the public key value per [RFC5910] with type="secDNS:keyType". Indicates a child's preference for the number of seconds after signature generation when the parent's signature on the DS information provided by the child will expire with type="secDNS:maxSigLifeType" defined in [RFC5910]. The following are example DSF files using the domain object fields. The different forms of domain object DSF files is up to server policy. Gould Expires October 1, 2017 [Page 19] Internet-Draft Data Set File Format March 2017 Example of a "domain.update.replaceClientStatuses" DSF that will set the client statuses of a domain name to those specified in the DSF record. The client statuses set will be replaced by the set of client statuses specified. Empty statuses will result in the removal of those statuses if previously set. Non-empty statuses will be added if not previously set. Non-empty statuses will result in no change if previously set. All five client statuses defined in [RFC5731] are defined in the DSF in fixed order. domain.update.replaceClientStatuses abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- domain1.example,clientDeleteProhibited,,,,clientUpdateProhibited domain2.example,,clientHold,,, domain3.example,,,clientRenewProhibited,clientTransferProhibited, domain4.example,,,,, -----END DATA SET----- Gould Expires October 1, 2017 [Page 20] Internet-Draft Data Set File Format March 2017 Example of a "domain.update.addRemoveStatus" DSF that will add a status and remove a status for each domain name. Any status can be empty to indicate no action for that domain name. domain.update.addRemoveNs abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- domain1.example,ns1.domain1.example,n2.domain1.example domain2.example,ns1.domain1.example, domain3.example,,ns2.domain1.example -----END DATA SET----- Gould Expires October 1, 2017 [Page 21] Internet-Draft Data Set File Format March 2017 Example of a "domain.update.replaceNs" DSF that will set the name servers of a domain name to those specified in the DSF record. The server supports setting up to 13 name servers to a domain name, so there are 13 defined. All existing name servers set will be replaced with the name servers specified. domain.update.replaceNs abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- domain1.example,ns1.domain1.example,n2.domain1.example,,,,,,,,,,, domain2.example,ns1.domain1.example,,,,,,,,,,,, domain3.example,,,,,,,,,,,,, -----END DATA SET----- Gould Expires October 1, 2017 [Page 22] Internet-Draft Data Set File Format March 2017 Example of a "domain.update.addRemoveNs" DSF that will add a name server and remove a name server for each domain name. Any name server can be empty to indicate no action for that domain name. domain.update.addRemoveNs abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- domain1.example,ns1.domain1.example,n2.domain1.example domain2.example,ns1.domain1.example, domain3.example,,ns2.domain1.example -----END DATA SET----- Gould Expires October 1, 2017 [Page 23] Internet-Draft Data Set File Format March 2017 Example of a "domain.update.contacts" DSF that supports updating the contacts (registrant, admin, tech, and billing) for each domain name. All four contacts fields are set as required using the "isRequired" attribute and any existing contacts set for each domain name are replaced. domain.update.contacts abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- domain1.example,jd1234,sh813,sh813,sh813 domain2.example,jd1234,sh813,sh813, -----END DATA SET----- Gould Expires October 1, 2017 [Page 24] Internet-Draft Data Set File Format March 2017 Example of a "domain.create.standard" DSF that supports creating each domain name record with a standard set of fields / attributes for a thick domain name. domain.create.standard abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- domain1.example,1,ns1.dom.example,,jd1234,sh813,sh813,sh813,2fooBAR domain2.example,1,,,jd1234,sh813,sh813,sh813,2fooBAR -----END DATA SET----- 4.2. Host Object The host object is based on the EPP host mapping specified in [RFC5732]. The Data Set File (DSF) field elements specific to the host object include: Host name field with type="eppcom:labelType" and isRequired="true". Host new name field used to rename the host with type="eppcom:labelType". The address version ("v4" or "v6") is an extension of the "dataSet:fListItemType" field, described in Gould Expires October 1, 2017 [Page 25] Internet-Draft Data Set File Format March 2017 Section 2.4.1, with type="eppcom:addrStringType". The "dsfHost.fAddrVersion" field usually corresponds with a following "dsfHost:fAddr" field. The "dsfHost:fAddrVersion" and "dsfHost.fAddr" fields are included in pairs. The address is an extension of the "dataSet:fListItemType" field, described in Section 2.4.1, with type="eppcom:addrStringType". The "dsfHost.fAddr" field usually corresponds with a previous "dsfHost:fAddrVersion" field that defines the type of address. The "dsfHost:fAddrVersion" and "dsfHost.fAddr" fields are included in pairs. The status of the host is an extension of the "dataSet:fListItemType" field, described in Section 2.4.1, with type="host:statusValueType". The following are example DSF files using the host object fields. The different forms of host object DSF files is up to server policy. Gould Expires October 1, 2017 [Page 26] Internet-Draft Data Set File Format March 2017 Example of a "host.update.replaceClientStatuses" DSF that will set the client statuses of a host to those specified in the DSF record. The client statuses set will be replaced by the set of client statuses specified. Empty statuses will result in the removal of those statuses if previously set. Non-empty statuses will be added if not previously set. Non-empty statuses will result in no change if previously set. All two client statuses defined in [RFC5732] are defined in the DSF in fixed order. host.update.replaceClientStatuses abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- ns1.domain.example,clientDeleteProhibited,clientUpdateProhibited ns2.domain.example,,clientUpdateProhibited ns3.domain.example,clientDeleteProhibited, ns4.domain.example,, -----END DATA SET----- Gould Expires October 1, 2017 [Page 27] Internet-Draft Data Set File Format March 2017 Example of a "host.update.addRemoveStatus" DSF that will add a status and remove a status for each host. Any status can be empty to indicate no action for that host. host.update.addRemoveClientStatuses abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- ns1.domain.example,clientDeleteProhibited,clientUpdateProhibited ns2.domain.example,,clientUpdateProhibited ns3.domain.example,clientUpdateProhibited, -----END DATA SET----- Gould Expires October 1, 2017 [Page 28] Internet-Draft Data Set File Format March 2017 Example of a "host.update.replaceAddr" DSF that will set the addresses of a host to those specified in the DSF record. The server supports setting up to 6 addresses to a host, so there are 6 and field pairs defined. All existing addresses set will be replaced with the addresses specified. host.update.replaceAddr abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- ns1.domain.example,v4,192.0.2.2,v4,192.0.2.29,,,,,,,, ns2.domain.example,v6,1080:0:0:0:8:800:200C:417A,,,,,,,,,, ns3.domain.example,,,,,,,,,,,, -----END DATA SET----- Gould Expires October 1, 2017 [Page 29] Internet-Draft Data Set File Format March 2017 Example of a "host.update.addRemoveAddr" DSF that will add an address and remove an address for each host. Any address can be empty to indicate no action for that host. The and field pairs are provided with matching list operations. host.update.addRemoveAddr abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- ns1.domain.example,v4,192.0.2.2,v4,192.0.2.29 ns2.domain.example,v6,1080:0:0:0:8:800:200C:417A,, ns3.domain.example,,v4,192.0.2.29 -----END DATA SET----- Gould Expires October 1, 2017 [Page 30] Internet-Draft Data Set File Format March 2017 Example of a "host.create.standard" DSF that supports creating each host record with a standard set of fields / attributes for a host. There is an example of creating an internal host (ns1.domain.example and ns2.domain.example) with up to two addresses and an external host (ns1.domain.external) without addresses. host.create.standard abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- ns1.domain.example,v4,192.0.2.2,v4,192.0.2.29 ns2.domain.example,v6,1080:0:0:0:8:800:200C:417A, ns1.domain.external,,,, -----END DATA SET----- 4.3. Contact Object The contact object is based on the EPP host mapping specified in [RFC5733]. Some elements MAY be provided in either internationalized form ("int") or provided in localized form ("loc"). Those elements use a field value or "isLoc" attribute to specify the form used. If an "isLoc" attribute is used, a value of "true" indicates the use of the localized form and a value of "false" indicates the use of the internationalized form. This MAY override the form specified for a parent element. A value of "int" is used to indicate the internationalized form and a value of "loc" is used to indicate the localized form. When the internalized form ("int") is provided, the field value MUST be represented in a subset of UTF-8 that can be Gould Expires October 1, 2017 [Page 31] Internet-Draft Data Set File Format March 2017 represented in the 7-bit US-ASCII character set. When the localized form ("loc") is provided, the field value MAY be represented in unrestricted UTF-8. Some of the contact field elements specify the internationalized form with the isLoc="false" attribute. The Data Set File (DSF) field elements specific to the contact object include: Contains the server-unique contact identifier with type="eppcom:clIDType" and isRequired="true". Contains the contact's email address with type="eppcom:minTokenType" and isRequired="true". Contains the contact's voice telephone number with type="contact:e164StringType". Contains the contact's voice telephone number extension with type="token". Contains the contact's facsimile telephone number with type="contact:e164StringType". Contains the contact's facsimile telephone number extension with type="token". Contains the contact's name of the individual or role represented by the contact with type="contact:postalLineType" and isRequired="true". An OPTIONAL "isLoc" attribute to used to indicate the localized or internationalized form. Contains the contact's contact's street address line with type="contact:fPostalLineType". An index attribute is required to indicate which street address line the field represents with index "0" for the first line and index "2" for the last line. An OPTIONAL "isLoc" attribute to used to indicate the localized or internationalized form. Contains the contact's city with type="contact:postalLineType" and isRequired="true". An OPTIONAL "isLoc" attribute to used to indicate the localized or internationalized form. Contains the contact's country code with type="contact:ccType" and isRequired="true". An OPTIONAL "isLoc" attribute to used to indicate the localized or internationalized form. Contains the form of the postal-address information with type="contact:postalLineType". This field specifies the form ("int" or "loc") of the , , , , , , fields. Contains the name of the organization with which the contact is affiliated with type="contact:optPostalLineType". An OPTIONAL "isLoc" attribute to used to indicate the localized or internationalized form. Gould Expires October 1, 2017 [Page 32] Internet-Draft Data Set File Format March 2017 Contains the contact's state or province with type="contact:optPostalLineType". An OPTIONAL "isLoc" attribute to used to indicate the localized or internationalized form. Contains the contact's postal code with type="contact:pcType". An OPTIONAL "isLoc" attribute to used to indicate the localized or internationalized form. Contains flag with a value of "true" or "1" (one) notes the preference to allow disclosure of the specified elements as an exception to the stated data-collection policy. A value of "false" or "0" (zero) notes a client preference to not allow disclosure of the specified elements as an exception to the stated data-collection policy with type="boolean". The additional fields define specific exceptional disclosure preferences based on the field. Exceptional disclosure preference flag for the localized form of the contact name with type="boolean". Exceptional disclosure preference flag for the internationalized form of the contact name with type="boolean". Exceptional disclosure preference flag for the localized form of the contact organization with type="boolean". with type="boolean". Exceptional disclosure preference flag for the internationalized form of the contact organization with type="boolean". with type="boolean". Exceptional disclosure preference flag for the localized form of the contact address with type="boolean". Exceptional disclosure preference flag for the internationalized form of the contact address with type="boolean". Exceptional disclosure preference flag of the contact voice telephone number with type="boolean". Exceptional disclosure preference flag of the contact facsimile telephone number with type="boolean". Exceptional disclosure preference flag of the contact email address with type="boolean". Exceptional disclosure preference flag of all of the supported disclose fields with type="boolean". This single field represents the field value for all of the disclose fields, that include , , , , , , , , and . Gould Expires October 1, 2017 [Page 33] Internet-Draft Data Set File Format March 2017 The following are example DSF files using the contact object fields. The different forms of contact object DSF files is up to server policy. Example of a "contact.update.replaceClientStatuses" DSF that will set the client statuses of a contact to those specified in the DSF record. The client statuses set will be replaced by the set of client statuses specified. Empty statuses will result in the removal of those statuses if previously set. Non-empty statuses will be added if not previously set. Non-empty statuses will result in no change if previously set. All three client statuses defined in [RFC5733] are defined in the DSF in fixed order. contact.update.replaceClientStatuses abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- sh1111,clientDeleteProhibited,,clientUpdateProhibited sh2222,,clientUpdateProhibited sh3333,,clientTransferProhibited, sh4444,,, -----END DATA SET----- Gould Expires October 1, 2017 [Page 34] Internet-Draft Data Set File Format March 2017 Example of a "contact.update.addRemoveStatus" DSF that will add a status and remove a status for each contact. Any status can be empty to indicate no action for that contact. contact.update.addRemoveClientStatuses abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- sh1111,clientDeleteProhibited,clientUpdateProhibited sh2222,,clientUpdateProhibited sh3333,clientUpdateProhibited, sh4444,clientTransferProhibited, -----END DATA SET----- Example of a "contact.create.standard" DSF that supports creating each contact record with a standard set of fields / attributes for a contact. A "|" character is used as a separator to minimize conflicting with the contact data. This is an example of creating two contacts, where indented data set lines are a continuation from the prior line. Gould Expires October 1, 2017 [Page 35] Internet-Draft Data Set File Format March 2017 contact.create.standard abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- sh1111|int|John Doe|Example Inc.| 123 Example Dr.|||Dulles|VA|20166-6503|US| +1.7035555555|1234|+1.7035555556|| johndoe@example.com|2fooBAR sh2222|int|Jane Doe|Example Inc.| 123 Example Dr.|Suite 2222||Dulles|VA|20166-6503|US| +1.7035555555|||| janedoe@example.com|2fooBAR -----END DATA SET----- Example of a "contact.create.routing" DSF that extends the "contact.create.standard" DSF with the field (Section 2.5) to route the create to the appropriate Top Level Domain (TLD) or group of TLDs. A "|" character is used as a separator to Gould Expires October 1, 2017 [Page 36] Internet-Draft Data Set File Format March 2017 minimize conflicting with the contact data. This is an example of creating two contacts, where indented data set lines are a continuation from the prior line. Gould Expires October 1, 2017 [Page 37] Internet-Draft Data Set File Format March 2017 contact.create.routing abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- EXAMPLE|sh1111|int|John Doe|Example Inc.| 123 Example Dr.|||Dulles|VA|20166-6503|US| +1.7035555555|1234|+1.7035555556|| johndoe@example.com|2fooBAR EXAMPLE|sh2222|int|Jane Doe|Example Inc.| 123 Example Dr.|Suite 2222||Dulles|VA|20166-6503|US| +1.7035555555|||| janedoe@example.com|2fooBAR -----END DATA SET----- Gould Expires October 1, 2017 [Page 38] Internet-Draft Data Set File Format March 2017 4.4. Verification Code Object The Verification Code Object is defined in the Verification Code Extension for the Extensible Provisioning Protocol [I-D.gould-eppext-verificationcode]. This section defines the Verification Code specific Data Set File (DSF) field elements and sample DSF files used to set verification codes with a bulk update. The Verification Service Provider (VSP) is a certified party to verify that data is in compliance with the policies of a locality. A locality MAY require the client to have data verified in accordance with local regulations or laws utilizing data sources not available to the server. The VSP has access to the local data sources and is authorized to verify the data. Examples include verifying that the domain name is not prohibited and verifying that the domain name registrant is a valid individual, organization, or business in the locality. The data verified, and the objects and operations that require the verification code to be passed to the server is up to the policies of the locality. The verification code represents a marker that the verification was completed. The data verified by the VSP MUST be stored by the VSP along with the generated verification codes in order to address any compliance issues. The signer certificate and the digital signature of the verification code MUST be verified by the server. The Data Set File (DSF) field elements specific to the Verification Code Object include: dsfVerificationCode:fCode Field that represents a Verification Code Token value. The field extends a "dataSet:fieldOptionalType", as defined in Section 2.4.1, with the type="dataSet:verificationCodeValueType". The field includes the required "codeType" attribute that represents the type of verification code, as defined by the "type" attribute of the element in [I-D.gould-eppext-verificationcode]. The verification code field can be empty since it is a "dataSet:fieldOptionalType". dsfVerificationCode:fEncodedSignedCode Field that represents a Encoded Signed Code. The field extends a "dataSet:fieldOptionalType", as defined in Section 2.4.1, with the type="token". The field includes the OPTIONAL "encoding" attribute with the default value of "base64". The line breaks, defined in [RFC2045], MUST NOT be used with the "base64" Encoded Signed Code. The Data Set File (DSF) used for setting of the verification codes MAY include fields from other objects and the fields specific to the Verification Code Object. There are two scenarios in passing the Gould Expires October 1, 2017 [Page 39] Internet-Draft Data Set File Format March 2017 verification codes based on who generates the DSF file, which includes: VSP Generated DSF The VSP generates the Verification Code Token values, represented with the field, and digitally signs the DSF file by referencing the element in the DSF header. Client Generated DSF The client generates the DSF file with a set of encoded signed codes, represented with the field, collected from the VSP to bulk submit them to the server. The element, described in Section 3.1.1, is referenced in the DSF header. The following examples reference verification codes supported by the China Locality, which includes the Domain Name Verification Code (DNVC) and the Real Name Verification Code (RNVC). Both China Locality verification codes are set on a domain name with the verification code type of "domain" used for the DNVC and the verification code type of "real-name" used for the RNVC. Other localities MAY include a different set of verification codes. Example VSP Generated DSF that includes a domain name primary key field, a "domain" code token value field, and a "real-name" token value field. The "base64" value includes "..." representing continuation of data for brevity: ICAgICAgPHZlcmlmaWNhdGlvbkNvZGU6c2lnbmVkQ29kZQogICAgICAgIHhtbG5z ... b25Db2RlOnNpZ25lZENvZGU+Cg== -----BEGIN DATA SET----- domain1.example,0-abc111,0-abc222 domain2.example,0-abc333,0-abc444 domain3.example,0-abc555, domain3.example,,0-abc666 -----END DATA SET----- Gould Expires October 1, 2017 [Page 40] Internet-Draft Data Set File Format March 2017 Example Client Generated Data Set File (DSF) that includes a domain name primary key field, a "domain" encoded signed code field, and a "real-name" encoded signed code field. The "base64" values include no line breaks and include "..." representing continuation of data for brevity: verificationCode.update.encodedSignedCode abc-123 2016-04-03T22:00:00.0Z -----BEGIN DATA SET----- domain1.example,ICAg...GlvbkN,CAgICA...uOmlldG domain2.example,YW1zOb2R...GlvbkNvZGU6c2ln, domain3.example,,CAgICAnZ...htbDpZmljYXMCIKI -----END DATA SET----- 5. Result Codes The result codes are based on and not equal to the reply codes defined in the EPP result codes of [RFC5730]. Four decimal digits are used to describe the success or failure of the processing of the Data Set File (DSF) or the processing of an individual record. Each digit of the result code has specific significance. The first digit denotes success or failure. The second digit denotes the result category, such as request syntax or security. The third and fourth digits provide explicit response detail within each result category. There are two values for the first digit of the result code: Gould Expires October 1, 2017 [Page 41] Internet-Draft Data Set File Format March 2017 1yzz Positive result. The file or record was processed by the system successfully. Partial successful results MAY be included. 2yzz Negative result. The file or record was not processed successfully. Partial successful results MAY NOT be included. The second digit groups responses into one of five specific categories: x0zz File or record syntax x1zz Implementation-specific rules x2zz Security x3zz Data Management x4zz Server System Successful result codes: 1000 "Success" This is the result for a successfully processed file when all records are processed successfully or the result for an individual record that is successfully processed. 1001 "Success with failures" This is the result for a successfully processed file when some records are processed successfully and some records failed. 1002 "Success with all failures" This is the result for a successfully processed file when all of the records failed. Error result codes: 2000 "File syntax error" This result code occurs when the overall file is syntactically incorrect. 2001 "Header syntax error" This result code occurs when the header is syntactically incorrect. 2002 "Body syntax error" This result code occurs when the body is syntactically incorrect. 2003 "Required parameter missing" This result code occurs when a server receives a request for which a required parameter has not been provided. Gould Expires October 1, 2017 [Page 42] Internet-Draft Data Set File Format March 2017 2004 "Parameter value range error" This result code occurs when a server receives a request whose value is outside the range of values specified in the protocol. 2005 "Parameter value syntax error" This result code occurs when a server receives a request whose value is improperly formed. 2100 "Unimplemented protocol version" This result code occurs when a server receives a request version, as defined by the XML namespace of the header, that is not implemented by the server. 2102 "Unimplemented option" This result code occurs when a server receives a request that contains a protocol option that is not implemented by the server. 2103 "Unimplemented extension" This result code occurs when a server receives a request that contains an extension, as defined by the XML namespace used by a field element extension, that is not implemented by the server. 2104 "Billing failure" This result code occurs when a server receives a request that cannot be completed due to a client-billing failure. 2201 "Authorization error" This result code occurs when a server receives a request cannot be execute due to a client-authorization error. 2202 "Invalid authorization information" This result code occurs when a server receives invalid authorization information to execute a request. 2302 "Object exists" This result code occurs when a server receives a request to create an object that already exists in the repository. 2303 "Object does not exist" This result code occurs when a server receives a request to transform an object that does not exist in the repository. 2304 "Object status prohibits operation" This result code occurs when a server receives a request to transform an object that cannot be completed due to server policy or business practices. Gould Expires October 1, 2017 [Page 43] Internet-Draft Data Set File Format March 2017 2305 "Object association prohibits operation" This result code occurs when a server receives a request to transform an object that cannot be completed due to dependencies to other objects that are associated with the target object. 2306 "Parameter value policy error" This result code occurs when a server receives a request that contains a parameter value that is syntactically valid but semantically invalid due to local policy. 2307 "Unimplemented object service" This result code occurs when a server receives a request to operate on an object that is not supported by the server. 2308 "Data management policy violation" This result code occurs when a server receives a request whose execution results in a violation of server data management policies. 2400 "Request failed" This result code occurs when a server receives a request that cannot be executed due to an internal server error that is not related to the protocol. The error result codes include some overlap that will require the server to decide which one to return based on server policy. For example, a "Header syntax error", represented by the error result code 2001, may have occured for multiple reasons including a 2003 "Required parameter missing", a 2004 "Parameter value range error", or a 2005 "Parameter value syntax error". The overlapping reasons also apply at the record level, where an object may be syntactically incorrect with a 2005 "Parameter value syntax error", and also be against server policy with a 2306 "Parameter value policy error". The server SHOULD attempt to provide the most accurate error result code to match the error. For example, a syntax error defined by the protocol SHOULD take precedence over a server policy error. 6. Example Data Set File (DSF) Result Files This section includes a set of Data Set File (DSF) result examples. 6.1. Example Data Set File (DSF) with Result Data This section includes example Data Set File (DSF) files that reference the element, described in Section 3.1.3, for providing the meta-data about the result file, Gould Expires October 1, 2017 [Page 44] Internet-Draft Data Set File Format March 2017 along with a set of fields that reference the field element, described in Section 2.4.2, for including the result code in processing the domain name record in the request. Example Data Set File (DSF) for a succesful result by the server: abc-123 54322-XYZ Code Set processed successfully. 2 2 0 -----BEGIN DATA SET----- domain1.example,1000,, domain2.example,1000,, -----END DATA SET----- Gould Expires October 1, 2017 [Page 45] Internet-Draft Data Set File Format March 2017 Example Data Set File (DSF) for a partially successful result by the server: abc-123 54322-XYZ Success with failures 4 1 3 -----BEGIN DATA SET----- domain1.example,1000,Success, domain2.example,2303,Object does not exist, domain3.example,2201,Authorization error, domain4.example,2302,Object exists,domain code already set -----END DATA SET----- Gould Expires October 1, 2017 [Page 46] Internet-Draft Data Set File Format March 2017 Example Data Set File (DSF) for a failure result by the server: abc-123 54322-XYZ File syntax error Malformed request file -----BEGIN DATA SET----- -----END DATA SET----- 7. Formal Syntax Each schema is included in a sub-section, starting with the Data Set schema and followed by each object schema. The formal syntax presented here is a complete schema representation of the object mapping suitable for automated validation of EPP XML instances. The BEGIN and END tags are not part of the schema; they are used to note the beginning and ending of the schema for URI registration purposes. 7.1. Data Set Schema Data Set schema that represents the base XML schema for the Data Set File (DSF). BEGIN Data Set XML Schema Gould Expires October 1, 2017 [Page 47] Internet-Draft Data Set File Format March 2017 Gould Expires October 1, 2017 [Page 48] Internet-Draft Data Set File Format March 2017 Gould Expires October 1, 2017 [Page 49] Internet-Draft Data Set File Format March 2017 Gould Expires October 1, 2017 [Page 50] Internet-Draft Data Set File Format March 2017 Gould Expires October 1, 2017 [Page 51] Internet-Draft Data Set File Format March 2017 Gould Expires October 1, 2017 [Page 52] Internet-Draft Data Set File Format March 2017 Gould Expires October 1, 2017 [Page 53] Internet-Draft Data Set File Format March 2017 Gould Expires October 1, 2017 [Page 54] Internet-Draft Data Set File Format March 2017 END 7.2. Domain Name Schema Domain Name Object XML schema that defines the fields specific to the Domain Name Object. BEGIN Gould Expires October 1, 2017 [Page 56] Internet-Draft Data Set File Format March 2017 Domain Name Data Set File (DSF) Object Gould Expires October 1, 2017 [Page 57] Internet-Draft Data Set File Format March 2017 Gould Expires October 1, 2017 [Page 58] Internet-Draft Data Set File Format March 2017 Gould Expires October 1, 2017 [Page 59] Internet-Draft Data Set File Format March 2017 END 7.3. Host Schema Host Object XML schema that defines the fields specific to the Host Object. BEGIN Host Name Data Set File (DSF) Object Gould Expires October 1, 2017 [Page 61] Internet-Draft Data Set File Format March 2017 END 7.4. Contact Schema Contact Object XML schema that defines the fields specific to the Contact Object. BEGIN Contact Data Set File (DSF) Object Gould Expires October 1, 2017 [Page 62] Internet-Draft Data Set File Format March 2017 Gould Expires October 1, 2017 [Page 63] Internet-Draft Data Set File Format March 2017 Gould Expires October 1, 2017 [Page 64] Internet-Draft Data Set File Format March 2017 Gould Expires October 1, 2017 [Page 65] Internet-Draft Data Set File Format March 2017 Gould Expires October 1, 2017 [Page 66] Internet-Draft Data Set File Format March 2017 END 7.5. Verification Code Schema Verification Code Object XML schema that defines the fields specific to the Verification Code Object. BEGIN Gould Expires October 1, 2017 [Page 67] Internet-Draft Data Set File Format March 2017 Verification Code Data Set File (DSF) Object END Gould Expires October 1, 2017 [Page 68] Internet-Draft Data Set File Format March 2017 7.6. Routing Schema Routing XML schema that defines the fields specific to routing. BEGIN Routing Data Set File (DSF) Fields END 8. IANA Considerations 8.1. XML Namespace This document uses URNs to describe XML namespaces and XML schemas conforming to a registry mechanism described in [RFC3688]. Registration request for the dataSet namespace: Gould Expires October 1, 2017 [Page 69] Internet-Draft Data Set File Format March 2017 URI: ietf:params:xml:ns:dataSet-1.0 Registrant Contact: See the "Author's Address" section of this document. XML: None. Namespace URIs do not represent an XML specification. Registration request for the dataSet XML schema: URI: ietf:params:xml:ns:dataSet-1.0 Registrant Contact: See the "Author's Address" section of this document. XML: See the "Formal Syntax" section of this document. Registration request for the dsfDomain namespace: URI: ietf:params:xml:ns:dsfDomain-1.0 Registrant Contact: See the "Author's Address" section of this document. XML: None. Namespace URIs do not represent an XML specification. Registration request for the dsfDomain XML schema: URI: ietf:params:xml:ns:dsfDomain-1.0 Registrant Contact: See the "Author's Address" section of this document. XML: See the "Formal Syntax" section of this document. Registration request for the dsfHost namespace: URI: ietf:params:xml:ns:dsfHost-1.0 Registrant Contact: See the "Author's Address" section of this document. XML: None. Namespace URIs do not represent an XML specification. Registration request for the dsfHost XML schema: URI: ietf:params:xml:ns:dsfHost-1.0 Registrant Contact: See the "Author's Address" section of this document. XML: See the "Formal Syntax" section of this document. Registration request for the dsfContact namespace: URI: ietf:params:xml:ns:dsfContact-1.0 Registrant Contact: See the "Author's Address" section of this document. XML: None. Namespace URIs do not represent an XML specification. Registration request for the dsfContact XML schema: Gould Expires October 1, 2017 [Page 70] Internet-Draft Data Set File Format March 2017 URI: ietf:params:xml:ns:dsfContact-1.0 Registrant Contact: See the "Author's Address" section of this document. XML: See the "Formal Syntax" section of this document. Registration request for the dsfVerificationCode namespace: URI: ietf:params:xml:ns:dsfVerificationCode-1.0 Registrant Contact: See the "Author's Address" section of this document. XML: None. Namespace URIs do not represent an XML specification. Registration request for the dsfVerificationCode XML schema: URI: ietf:params:xml:ns:dsfVerificationCode-1.0 Registrant Contact: See the "Author's Address" section of this document. XML: See the "Formal Syntax" section of this document. Registration request for the dsfRouting namespace: URI: ietf:params:xml:ns:dsfRouting-1.0 Registrant Contact: See the "Author's Address" section of this document. XML: None. Namespace URIs do not represent an XML specification. Registration request for the dsfRouting XML schema: URI: ietf:params:xml:ns:dsfRouting-1.0 Registrant Contact: See the "Author's Address" section of this document. XML: See the "Formal Syntax" section of this document. 9. Security Considerations The data supported by the Data Set File (DSF) format MAY include information that needs to be protected with the use of a secure transport. For example, the field provides object authorization information, and as described in [RFC5731], both the client and the server MUST ensure that it is stored and exchanged with high-grade encryption mechanisms. The transport leveraged to exchange the DSF containing sensitive or secure data MUST protect it from inadvertent disclosure. XML Signature [W3C.CR-xmldsig-core2-20120124] is used in this document to verify that the Data Set originated from a trusted source and that it wasn't tampered with in transit from the source to the client to the server. To support multiple source keys, the source Gould Expires October 1, 2017 [Page 71] Internet-Draft Data Set File Format March 2017 certificate chain MUST be included in the elements of the Signed Def Data (Section 3.1.2.1) and MUST chain up and be verified by the server against a set of trusted certificates. It is RECOMMENDED that signed definition data does not include white- spaces between the XML elements in order to mitigate risks of invalidating the digital signature when transferring of signed codes between applications takes place. Use of XML canonicalization SHOULD be used when generating the signed code. SHA256/RSA-SHA256 SHOULD be used for digesting and signing. The size of the RSA key SHOULD be at least 2048 bits. 10. Normative References [I-D.gould-eppext-verificationcode] Gould, J., "Verification Code Extension for the Extensible Provisioning Protocol (EPP)", draft-gould-eppext- verificationcode-04 (work in progress), September 2016. [iso13239] the International Organization for Standardization, "ISO 13239", December 2007, . [itu-t-V.42] International Telecommunication Union, "ITU-T V.42 Series V: Data Communication Over the Telephone Network", March 2002, . [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, . [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, . Gould Expires October 1, 2017 [Page 72] Internet-Draft Data Set File Format March 2017 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", STD 69, RFC 5730, DOI 10.17487/RFC5730, August 2009, . [RFC5731] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) Domain Name Mapping", STD 69, RFC 5731, DOI 10.17487/RFC5731, August 2009, . [RFC5732] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) Host Mapping", STD 69, RFC 5732, DOI 10.17487/RFC5732, August 2009, . [RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) Contact Mapping", STD 69, RFC 5733, DOI 10.17487/RFC5733, August 2009, . [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS) Security Extensions Mapping for the Extensible Provisioning Protocol (EPP)", RFC 5910, DOI 10.17487/RFC5910, May 2010, . [W3C.CR-xmldsig-core2-20120124] Cantor, S., Roessler, T., Eastlake, D., Yiu, K., Reagle, J., Solo, D., Datta, P., and F. Hirsch, "XML Signature Syntax and Processing Version 2.0", World Wide Web Consortium CR CR-xmldsig-core2-20120124, January 2012, . Appendix A. Acknowledgements The author wishes to acknowledge the work done by Scott Hollenbeck in the EPP RFC 5730 for providing some of the concepts and text used in this document. Special suggestions that have been incorporated into this document were provided by John Colosi, Deepak Deshpande, Scott Hollenbeck, Suzy Strier, and Srikanth Veeramachaneni. Gould Expires October 1, 2017 [Page 73] Internet-Draft Data Set File Format March 2017 Appendix B. Change History B.1. Change from 00 to 01 1. Fixed the ABNF. 2. Added support for the 1002 "Success with all failures" result code to indicate that the file was successfully processed but that all of the records failed. 3. Updated the description for the 1000 "Success" and the 1001 "Success with failures" result codes. Author's Address James Gould VeriSign, Inc. 12061 Bluemont Way Reston, VA 20190 US Email: jgould@verisign.com URI: http://www.verisign.com Gould Expires October 1, 2017 [Page 74]