AusRegistry Chris Wright Anthony Harris AusRegistry Extensions Version 1.0 AusRegistry Pty Ltd Category: AusRegistry Service Extensions August 9th, 2007 AusRegistry Extensions to the Extensible Provisioning Protocol Status of This Document This document specifies an extension to the EPP protocol first implemented in AusRegistry's Domain Name Registry EPP service. Discussion and suggestions for improvements are welcome. Please refer to AusRegistry for more information on the status of this document. Distribution of this document and use of the protocol extensions defined within is unrestricted and unlimited. Copyright Notice Copyright (C) AusRegistry Pty Ltd (2007). Abstract This document describes application layer client-server protocol extensions for the Extensible Provisioning Protocol as needed for the management of objects stored in the AusRegistry Registry system. Specified in XML, the protocol defines general object management operations and an extensible framework that maps the protocol extensions to the relevant objects. This document includes a protocol extension specification, an object mapping template, and an XML media type registration. AusRegistry Registry Service Extensions [Page 1] AusRegistry Extensions 1.0 EPP August 9th, 2007 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Additional Services . . . . . . . . . . . . . . . . . . . 3 1.2. Enabling Extended Services . . . . . . . . . . . . . . . . 3 2. Protocol Extension Description . . . . . . . . . . . . . . . . 5 2.1. Command Format . . . . . . . . . . . . . . . . . . . . . . 5 2.2. Response Format . . . . . . . . . . . . . . . . . . . . . 6 2.3. Service Extensions . . . . . . . . . . . . . . . . . . . . 6 2.3.1. Extension Transform Commands . . . . . . . . . . . . . 6 2.3.1.1. EPP Command . . . . . . . . . . . . . . 7 2.3.1.2. EPP Command . . . . . . . . . . . . . . 8 2.3.1.3. EPP Command . . . . . . . . . . . . 9 2.3.1.4. EPP Command . . . . . . . . . . . 10 3. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 12 Appendix A. Object Mapping Template . . . . . . . . . . . . . . . 13 AusRegistry Registry Service Extensions [Page 2] AusRegistry Extensions 1.0 EPP August 9th, 2007 1. Introduction This document describes the AusRegistry extensions to the Extensible Provisioning Protocol (EPP) and the additional object management services supported by these extensions. The EPP core protocol specification provides a complete description of core EPP command and response structures. Those structures have been mimicked in the extension commands and responses defined within this document. A thorough understanding of the base protocol is necessary to understand the extensions defined in this document. 1.1. Additional Services The following additional commands [EPP RFC4930 2.7.1] are defined: - - - - 1.2. Enabling Extended Services In accordance with the service extension usage mechanism described in the Extensible Provisioning Protocol (EPP), server support for AusRegistry EPP extensions is published in a service element via the element. A server supporting the AusRegistry EPP extensions MUST inform the client of its capability via an child element whose value is the AusRegistry EPP extension URI (urn:X-ar:params:xml:ns:arext-1.0). A client wishing to use such services MUST present the AusRegistry EPP extension URI as the value of an element in the EPP command which initiates the session in which the services will be used. Example publishing support for AR extensions: S: S: S: epp-1.0.xsd"> S: S: AusRegistry EPP Server S: 2006-02-09T15:42:29.0Z S: S: 1.0 S: en S: urn:ietf:params:xml:ns:domain-1.0 S: urn:ietf:params:xml:ns:contact-1.0 AusRegistry Registry Service Extensions [Page 3] AusRegistry Extensions 1.0 EPP August 9th, 2007 S: urn:ietf:params:xml:ns:host-1.0 S: S: urn:X-ar:params:xml:ns:arext-1.0 S: S: S: S: S: S: S: S: S: S: S: S: Example requesting AusRegistry extensions services: C: C: C: C: C: REGISTRAR C: p4ssw0rd! C: C: 1.0 C: en C: C: C: urn:ietf:params:xml:ns:contact-1.0 C: urn:ietf:params:xml:ns:domain-1.0 C: urn:ietf:params:xml:ns:host-1.0 C: C: urn:X-ar:params:xml:ns:arext-1.0 C: C: C: C: C: AusRegistry Registry Service Extensions [Page 4] AusRegistry Extensions 1.0 EPP August 9th, 2007 2. Protocol Extension Description The AusRegistry Extension to EPP provides two basic service elements: commands and responses. These are layered on top of the protocol extension framework of EPP. The EPP server state machine is unaffected by these extension elements; they are equivalent in the state machine to core command and response elements. 2.1. Command Format An EPP client may interact with an EPP server by sending an extension command and receiving an EPP response as defined in this document, in the same manner as described in [EPPCORE]. In addition to the standard EPP elements, an extension command contains the following elements: - An element that contains the following child elements: - A element that contains the following child elements: - A command element whose tag corresponds to one of the valid extension commands described in this document. The command element contains object-specified child elements. - An OPTIONAL (client transaction identifier) element that MAY be used to uniquely identify the command to the client. Clients are responsible for maintaining their own transaction identifier space to ensure uniqueness. Example command with object-specified child elements: C: C: C: C: C: C: C: example C: C: C: ABC-12345 C: C: C: AusRegistry Registry Service Extensions [Page 5] AusRegistry Extensions 1.0 EPP August 9th, 2007 2.2. Response Format An EPP server responds to an EPP client extension command by returning an EPP response to the client as described in [EPPCORE]. Example response with : S: S: S: S: S: Command completed successfully S: S: S: S: example S: example S: S: S: S: ABC-12345 S: 54321-XYZ S: S: S: 2.3. Extension Protocol Commands The AusRegistry extension to EPP provides commands to perform transformation operations on objects. This describes each extension command, including examples with representative server responses. 2.3.1. Object Transform Commands The AusRegistry extensions to EPP provide four commands to transform objects: to retract the validity period of a provisioned object, to reinstate a previously deleted object not yet completely removed from the repository, to remove an instance of an object from the server due to server policy violation, and to reinstate an object which was previously deleted due to policy violation. AusRegistry Registry Service Extensions [Page 6] AusRegistry Extensions 1.0 EPP August 9th, 2007 2.3.1.1. Command The EPP command is used to cancel a previously requested object renewal. The elements needed to identify an object and ensure command idempotency are object-specific, so the child elements of the command are specified in an object-specific mapping using the EPP extension framework. In addition to the elements, the command contains the following child elements: - An object-specific element that identifies the object to be unrenewed and the elements that are required to ensure idempotency of the command. Example command: C: C: C: C: C: C: C: C: C: C: ABC-12345 C: C: C: When an command has been processed successfully, a server MAY respond with a element that MUST contain a child element that identifies the object namespace. The child elements of the element are object-specific. Example response with S: S: S: S: S: Command completed successfully S: S: S: S: S: AusRegistry Registry Service Extensions [Page 7] AusRegistry Extensions 1.0 EPP August 9th, 2007 S: S: S: ABC-12345 S: 2389742981742 S: S: S: 2.3.1.2. Command The EPP command is used to cancel a previously requested object deletion. The elements needed to identify an object are object-specific, so the child elements of the command are specified in an object-specific mapping using the EPP extension framework. In addition to the elements, the command contains the following child elements: - An object-specific element that identifies the object to be undeleted. Example command: C: C: C: C: C: C: C: C: C: C: UNDELETE-12345 C: C: C: When an command has been processed successfully, a server MAY respond with an EPP element that MUST contain a child element that identifies the object namespace. The child elements of the element are object-specific. Example response without : S: S: S: S: AusRegistry Registry Service Extensions [Page 8] AusRegistry Extensions 1.0 EPP August 9th, 2007 S: Command completed successfully S: S: S: UNDELETE-12345 S: 2389742981744 S: S: S: 2.3.1.3. Command The command is used to remove an instance of an existing object. This command differs from in that the removal is not registrant-initiated; it is initiated by a client when notified that the provisioning of the object violates server policy. The elements needed to identify an object are object-specific, so the child elements of the command are specified in an object-specific mapping using the EPP extension framework. In addition to the elements, the command contains the following child elements: - An object-specific element that identifies the object to be deleted. Example command: C: C: C: C: C: C: C: C: C: C: POLDEL-12345 C: C: C: When a command has been processed successfully, a server MAY respond with an EPP element that MUST contain a child element that identifies the object namespace. The child elements of the element are object-specific. AusRegistry Registry Service Extensions [Page 9] AusRegistry Extensions 1.0 EPP August 9th, 2007 Example response without : S: S: S: S: S: Command completed successfully S: S: S: POLDEL-12345 S: 2389742981745 S: S: S: 2.3.1.4. Command The command is used to cancel a previously requested object deletion via a policy delete operation such as is defined by the command described previously. The elements needed to identify an object are object-specific, so the child elements of the command are specified in an object-specific mapping using the EPP extension framework. In addition to the elements, the command contains the following child elements: - An object-specific element that identifies the object to be undeleted. Example command: C: C: C: C: C: C: C: C: C: C: POLUNDEL-12345 AusRegistry Registry Service Extensions [Page 10] AusRegistry Extensions 1.0 EPP August 9th, 2007 C: C: C: When a command has been processed successfully, a server MAY respond with a element that MUST contain a child element that identifies the object namespace. The child elements of the element are object-specific. Example response: S: S: S: S: S: Command completed successfully S: S: S: POLUNDEL-12345 S: 2389742981752 S: S: S: AusRegistry Registry Service Extensions [Page 11] AusRegistry Extensions 1.0 EPP August 9th, 2007 3. Formal Syntax Formal Syntax: BEGIN ar Extensions to the Extensible Provisioning Protocol v1.0 schema. END AusRegistry Registry Service Extensions [Page 12] AusRegistry Extensions 1.0 EPP August 9th, 2007 Appendix A. Object Mapping Template This appendix describes a recommended outline for documenting the EPP mapping of an object to the service extensions described within this document. Documents that describe object mappings SHOULD describe the mapping in a format similar to the one used here. 1. Introduction Provide an introduction that describes the object and an overview of the mapping to EPP. 2. Object Attributes Describe the attributes associated with the object, including references to syntax specifications as appropriate. Examples of object attributes include a name or identifier and dates associated with modification events. 3. EPP Command Mapping 3.1. EPP Transform Commands 3.1.1. EPP Command Describe the object-specific mappings required to implement the EPP command. Include both sample commands and sample responses. 3.1.2. EPP Command Describe the object-specific mappings required to implement the EPP command. Include both sample commands and sample responses. 3.1.3. EPP Command Describe the object-specific mappings required to implement the EPP command. Include both sample commands and sample responses. 3.1.4. EPP Command Describe the object-specific mappings required to implement the EPP command. Include both sample commands and sample responses. AusRegistry Registry Service Extensions [Page 13]