CORE Shared Registry System Protocol (SRSP)
Version 1.1
Klaus Malorny,
Knipp Medien und Kommunikation
September 13th, 2000
1. History......... 5
2. Protocol Structure............ 5
2.1. Transmission
Layer.............. 5
2.1.1. Digital
Signatures... 5
2.1.2. Transmission by
E-Mail.. 6
2.1.3. Transmission by
TCP...... 6
2.1.4. Payload
Encoding.... 7
2.2. Payload.. 7
2.2.1. Registry Data
Model........ 7
2.2.1.1. The Domain
Object.... 8
2.2.1.2. The Contact
Object.... 8
2.2.1.3. The Host
Object.... 9
2.2.1.4. The Registrar
Object.... 9
2.2.2. Syntax 9
2.2.3. Transaction
Mechanism 10
2.2.4. Common Request
Keys................. 11
2.2.5. Common Response
Keys........ 11
2.2.6. Acknowledge
Responses 11
2.2.7. Replies................. 11
2.2.8. Requests and
their Replies................. 12
2.2.8.1. Complete
Transfer Request 12
2.2.8.2. Create
Contact Request 13
2.2.8.3. Create Domain
Request 14
2.2.8.4. Create Host
Request 15
2.2.8.5. Delete
Contact Request 15
2.2.8.6. Delete Domain
Request 15
2.2.8.7. Delete Host
Request 16
2.2.8.8. Inquire
Contact Request 16
2.2.8.9. Inquire
Domain Request 17
2.2.8.10. Inquire Host
Request 19
2.2.8.11. Inquire
Registrar Request 20
2.2.8.12. Modify
Contact Request 21
2.2.8.13. Modify
Domain Request 22
2.2.8.14. Modify Host
Request 22
2.2.8.15. Modify
Registrar Request 23
2.2.8.16. Query
Request 24
2.2.8.17. Renew Domain
Request 24
2.2.8.18. Status
Request 25
2.2.8.19. Transfer
Domain Request 25
2.2.9. Notifications................. 26
2.2.9.1. Init-Transfer
Notification............. 26
2.2.9.2.
Transfer-Acknowledge Notification............. 26
2.2.9.3.
Transfer-Finish Notification............. 26
2.2.10. Common Data
Types...... 27
2.2.10.1. Handles 27
2.2.10.2. Domain Names.. 27
2.2.10.3. IP Addresses............. 27
2.2.10.4. Dates/Times........... 27
2.2.10.5. Phone and
Fax Numbers 27
2.2.10.6. E-Mail
Addresses............. 27
2.2.10.7. Billing
Units.... 27
2.2.11. Description of
the Keys.. 28
2.2.11.1. Action Key............. 28
2.2.11.2. Address Keys.... 28
2.2.11.3.
Admin-Contact Key...... 28
2.2.11.4.
Approved-Owner-Change Key............. 28
2.2.11.5. City Key 28
2.2.11.6.
Completed-Before Key............. 28
2.2.11.7.
Completed-Since Key............. 29
2.2.11.8. Contact Key...... 29
2.2.11.9. Costs Key............. 29
2.2.11.10. Count Key............. 29
2.2.11.11. Country Key...... 29
2.2.11.12. Created Key...... 30
2.2.11.13. Created-By
Key...... 30
2.2.11.14. Domain-Name
Key............. 30
2.2.11.15.
Domain-State Key 30
2.2.11.16. EMail Key............. 30
2.2.11.17. Error-Code
Key...... 30
2.2.11.18. Error-Text
Key...... 31
2.2.11.19.
Expiration-Date Key 31
2.2.11.20. Fax Key 31
2.2.11.21. FName Key............. 31
2.2.11.22.
Gaining-Registrar Key...... 31
2.2.11.23. Handle Key............. 31
2.2.11.24. Individual
Key...... 32
2.2.11.25. IP-Address
Key...... 32
2.2.11.26.
Last-Modified Key...... 32
2.2.11.27.
Last-Modified-By Key 32
2.2.11.28. List Key 32
2.2.11.29. LName Key............. 32
2.2.11.30.
Managing-Registrar-ID Key...... 32
2.2.11.31.
Notification-Type Key............. 33
2.2.11.32. NS-Host
Keys.... 33
2.2.11.33.
Organization Key... 33
2.2.11.34.
Owner-Contact Key...... 33
2.2.11.35.
Owner-Contact-Origin Key............. 33
2.2.11.36.
Payload-Version Key...... 34
2.2.11.37. Period Key............. 34
2.2.11.38. Phone Key............. 34
2.2.11.39. Postal-Code
Key...... 34
2.2.11.40.
Reg-Admin-Auth-Key Key...... 34
2.2.11.41.
Reg-Admin-Auth-Key-Info Key 34
2.2.11.42.
Reg-Admin-Auth-Type Key...... 34
2.2.11.43.
Reg-Admin-Contact Key...... 34
2.2.11.44.
Reg-Admin-Permissions Key...... 34
2.2.11.45.
Reg-Agent-Auth-Key Keys.... 34
2.2.11.46.
Reg-Agent-Auth-Key-Info Key 34
2.2.11.47.
Reg-Agent-Auth-Type Keys.... 36
2.2.11.48.
Reg-Agent-Contact Keys.... 36
2.2.11.49.
Reg-Agent-Permissions Key...... 36
2.2.11.50. Reg-State
Key...... 36
2.2.11.51.
Reg-Super-Auth-Key Key...... 36
2.2.11.52.
Reg-Super-Auth-Key-Info Key 36
2.2.11.53.
Reg-Super-Auth-Type Key...... 37
2.2.11.54.
Reg-Super-Contact Key...... 37
2.2.11.55.
Reg-Super-Permissions Key...... 37
2.2.11.56.
Registrar-ID Key...... 37
2.2.11.57.
Request-Transaction-ID Key 37
2.2.11.58.
Request-Type Key............. 38
2.2.11.59.
Request-State Key 38
2.2.11.60.
Response-Type Key............. 38
2.2.11.61. State Key 38
2.2.11.62.
Submitted-Before Key............. 38
2.2.11.63.
Submitted-Since Key............. 39
2.2.11.64. Success Key...... 39
2.2.11.65.
Tech-Contact Key...... 39
2.2.11.66.
Time-Out-Date Key 39
2.2.11.67. Title Key 39
2.2.11.68.
Transaction-Credit Key............. 39
2.2.11.69.
Transaction-ID Key 40
2.2.11.70.
Transfer-Approved Key...... 40
2.2.11.71.
Transfer-Performed Key...... 40
2.2.11.72.
Zone-Contact Key...... 40
2.2.12. Error Codes....... 40
2.3. Domain Transfer
Process..................... 41
A. References... 44
B. Glossary...... 44
The original Shared Registry System Protocol (version 0.9) was developed by CORE together with Emergent, Inc. in the context of the creation of a registry system suitable for the registration of the anticipated seven new top level domains. Due to the political change, CORE was unable to start the registration of those domains. Instead, CORE got the opportunity to register COM, NET and ORG (CNO) domains via the registry spin-off of Network Solution Inc. As the infrastructure had already been set up and was working, CORE decided to extend the registry system instead of the development of a new system specific to CNO domains. The server system was extended to synchronize its database with NSIRegistry’s via the Registry Registrar Protocol (RRP). The payload of the SRSP was modified to conform to the new needs. The development was performed by Computer Service Langenbach GmbH, and the SRSP got the version number 1.0.
This document describes the version 1.1 of the protocol, which is mostly a cosmetic update of the payload and does not introduce much new functionality.
The protocol defines the communication between a client (operated by the registrar) and the server (operated by the registry). It is message-based, i.e. one side (either the server or the client), compiles a packet with its data (called payload) and sends it to the opposite side. The receive and transmit channels are not synchronized: The client does not need to wait for the server’s answer to send additional requests; the server does not need to send the responses immediately or in the order in which the client sent the requests. But it is guaranteed that the server does not send responses not related to the particular client, i.e. the client does not receive unexpected responses. Due to the transaction management, situations where the communication fails can be handled (see below for details).
The protocol consists of two layers. The transport layer defines the communication between the client and the server. It is also responsible for the client/server authentication and for the secure transmission of the payload data.
The payload represents the application layer. It defines the requests from the clients and the responses from the server. A built-in transaction management allows the processing of asynchronous, interleaved requests.
For the purpose of domain transfers, it is required that the registry can notify the registrar about certain events. This does not fit in mentioned request-reply schema. Therefore, the notification is handled separately, but by using the same technologies: The server uses the e-mail transmission variant for the notification. The destination e-mail address is a fixed address specified by the registrar. The format of the payload is the same, although different keys are used.
The transmission layer is responsible for the transfer of the payload to the server and back to the client. The SRSP defines two different variants for this transfer: by e-mail and by a TCP connection. In both cases, the authentication and the secure transmission is done by digital signatures[1]. The format of the signatures conforms to the standard defined by [PGP5].
For the attachment of the signature to the payload, the PGP specific variant of the S/MIME standards is used, as described in [RFC1847] and [RFC2015]. The following content-type specific attributes must be used in the context of this protocol:
micalg pgp-sha1
protocol application/pgp-signature
The keys must use the DSS/Diffie-Hellman algorithms. Keys of other types are not accepted. Depending on whether the message is sent to the server or to the client, it is signed by different keys.
On the server side, a registry specific key is used to sign the messages to the clients. On the client side, multiple keys can be used. There is a super contact with a corresponding key, which is maintained by the registry. An administrative contact and additional agents with their keys can be added by registrar at will (see modify registrar below).
The PGP-signed payload is sent to a specific address at the registry. The registry uses the contents of the reply-to field or, if it does not exist, the contents of the from field specifies the e-mail address, to which the server’s response is sent back. The e-mail address is not used to authenticate the user — the registrar-id field together with the key used for the signature identifies and authenticates the user.
Due to the mechanisms behind the e-mail transport, there is a risk of wrongly delivered e-mails and eavesdropping. Although protocol does not transport very sensitive data, it is recommended not to use this transmission method.
In this variant, the messages are transported between client and server via a TCP connection. Port number 362/service name srssend has been assigned for that service [IANA-PORTS].
For transmission, the payload is signed according to the rules above. A message is constructed according to the syntactic rules specified in [RFC822] and [RFC1521], with the difference that the header consists only of MIME related fields, i.e., in relation to this application, exactly of the content-type field.
The message is sent through the TCP connection without additional information (length or termination mark). Since the outermost content-type is always a multipart type (multipart/signed), the body of the message always contains MIME boundaries. The reader can easily detect the end of the message by watching the input stream for the closing boundary (it differs from intermediate boundaries by two additional hyphens).
A typical message looks like this:
Content-Type: multipart/signed; micalg=pgp-sha1;
protocol="application/pgp-signature";
PGPFormat="PGPMIME-signed";
boundary="12027960_39A4DF56751968_1"
--12027960_39A4DF56751968_1
Content-Type: text/x-srs-data
payload-version: 1.1
transaction-id: 4084.968850757
registrar-id: CORE-326
request-type: inquire registrar
handle: CORE-326
--12027960_39A4DF56751968_1
Content-Type: application/pgp-signature
-----BEGIN PGP SIGNATURE-----
Version: PGP 5.0i
MessageID: gA7PE4txVcbglLFpY14pt9BreT3zhESX
iQA/AwUBOaTfVibmObpCSbN4EQIN5wCg7cU9iCZyeGaXBqRkjFJyD550PpoAn3Mx
X/ur+CMmG+WfaeYQNOL73KgN
=sPqi
-----END PGP SIGNATURE-----
--12027960_39A4DF56751968_1--
The payload has the content-type text/x-srs-data. No MIME content transfer encoding or compression may be applied to the payload.
Before describing the requests of the client and the responses of the server, it is important to understand the model on which the registry operates.
The registry stores objects. An object is, in this context, a collection of related data. Four different object types exist: domains, contacts, hosts and registrars (explained later). Each object has a unique identifier. This identifier is either a certain part of the data (in case of the domain object, it is the domain name), or it is a unrelated text label, usually called handle.
|
object type |
unique identifier |
|
domain |
the domain name, case insensitive |
|
contact |
text label COCO-N (where N is a positive number) |
|
Host |
text label COHO-N (where N is a positive number) |
|
registrar |
text label CORE-N (where N is a positive number) |
Objects can reference each other, e.g. domains reference hosts for the purpose of specifying the name servers which manage the corresponding zones. Referenced objects cannot be deleted, as the referencing objects would become invalid. A change to a referenced object indirectly modifies all referencing objects[2], e.g., changing a host’s IP address results in a change of all domains referencing it: The next build of the registry’s master zone file would contain the new IP address for those domains.
The objects are shared among the registrars, i.e., any registrar can view or use any object. Domain, contact and host objects have a property of the managing registrar. Each of those objects is managed by the registrar who created it. The property restricts the right to modify a certain object: only the managing registrar may change it. The managing registrar of domains is changed during the transfer domain process. The managing registrar of contacts and hosts cannot be changed. Even in the case of a domain transfer between registrars, the contacts and hosts referenced in the domain stay at the loosing registrar. The gaining registrar can continue to use these contacts and hosts or it can create new ones and update the domain accordingly.
The domain object stores the domain related data, which is
- the domain name itself, fully qualified
- the owner of the domain
- the administrative, technical and zone contact of the domain (the tasks of these contacts is out of the scope of this document)
- up to twelve hosts
- the registration period in years
- the state of the domain
The contacts (excluding the owner) and hosts are stored as references to the corresponding objects. The owner is directly stored in the domain object. It contains the data of a given contact object at the point of time of the creation or modification of the domain object. Later changes to the contact object do not modify the contents of the domain object. Although the domain object stores a reference to the owner contact object, the reference has only informational character: It just informs the registrar about the origin of the owner data.
The registration period determines how long the domain will operate without further interaction and how much is deducted from the registrar’s account.
The state has one of the four possible values:
|
reserved |
the domain is registered but no entry is generated in the registry’s master zone file. |
|
production |
the domain is registered and fully functional |
|
expired |
the registration period has expired (the exact consequences are out of the scope of this document, limited modification rights may apply) |
|
hold |
the domain is currently matter of a dispute (the exact consequences are out of the scope of this document, limited modification rights may apply) |
The contact object stores the identity and various types of addresses of an individual or of an organization. It contains the following data:
- a flag which identifies whether the contact is an individual or an organization
- the first name, the last name and the title of the individual
- the name of the organization
- The "real world" address: two free form address lines (typically used for specification of the street, but may contain a more specific or different inner-city address), the city (including the postal code), the state and the country.
- the phone number (with international area code)
- the fax number (with international area code)
- the e-mail address
Although it should be avoided by the registrar, it is possible to create multiple contact objects for exactly the same person or organization.
The host object describes a name server, which is able to respond to DNS requests ([RFC1035]) for those domains which reference this object. The following data is stored in the object:
- the domain name of the name server
- the IP address of the name server (optional)
- a reference to a contact object (identifying a person or organization, who/which is responsible for the name server; optional)
Although it should be avoided by the registrar, it is possible to create multiple host objects with the same domain name or IP address. Please note that the host object does not contain a reference to a domain object, so a domain object may be deleted even if a host exists that is located inside (in the sense of the domain name system) that domain.
The registrar object is maintained by the registry. Some parts of the data are exposed to the registrars, and a registrar is able to modify some aspects of his own data. The data which is exposed is:
- the name and the handle of the registrar
- the status (active, suspended or defunct)
- the account balance
- the super, administrative and agent contacts, along with PGP related information and permissions.
The payload consists of readable text, encoded by the 7-Bit ASCII encoding. It represents a set of key-value pairs. A single key may appear multiple times. In this case, each appearance of the key represents an independent record and is not the continuation of a previous key-value pair. The order of differing keys is irrelevant. In the case of multiple identical keys, the order is important.
Two representations exist for a key-value pair. They differ only syntactically: the first variant is more suitable for single line entries. If it starts with a quote, that quote must be doubled to make the entry different to the second variant. The value may continue on the next line, but the newline must be prefixed by a backslash (the backslash/newline combination does not become part of the value). Whitespace that appears at the start or at the end of the value is ignored.
The second form is a multi-line form which is used for lengthy data, e.g. an ASCII encoded PGP public key. It starts and ends with a double quote. Any non double-quote character between them is allowed, even a newline. The quotes are not part of the value.
The key is case-insensitive.
The formal grammer of the payload is:
payload
::= kv-pair*
kv-pair
::= key whitespace* : value
newline | newline
value
::= value1 | value2 | whitespace*
value1
::= value1start value1other*
value1start
::= value-char | ""
| \ newline
value1other
::= value-char | " | \ newline
value2
::= " value2char+ "
value2char
::= value-char | newline | \
value-char[3]
::= whitespace | ! | [0x23 .. 0x5B] | [0x5D .. 0x7E]
key
::= key-char+
key-char[4]
::= [0x21 .. 0x39] | [0x3B .. 0x7E]
newline
::= 0x0D | 0x0D 0x0A | 0x0A
whitespace
::= 0x20 | 0x09
(name denotes a non-terminal symbol, | separates alternatives, x denotes a literal character or character sequence, 0xNN the hexadecimal code of a character, [ from .. to ] a sub-range of the ASCII character set, ? zero or one occurrences, + one or more occurrences, * zero or more occurrences)
The protocol uses transaction identifiers to enable the tracking of requests. The transaction identifier is specified by the client via the transaction-id key. The server uses that identifier in every response, so the client can associate these responses to the corresponding requests.
The server reacts to a normal request by sending two responses. The first is an acknowledge (response-type: ack) and is sent immediately after the reception at the server. After the processing of the request, the server sends the results back to the client (response-type: reply).
In both transmission variants (e-mail and TCP), it may happen that the communication fails — either the e-mail is lost or the TCP connection is interrupted, maybe just in the moment of sending a request or receiving a response. In the case of requests which do not modify the state of the registry, the client has to repeat the request, since the server does not back up the results of such requests.
For requests that modify the state of the registry, the server saves the results of processed requests for a certain time, at least for a day. Two special request exist to help the client on its recovery: With the status request, the client is able to retrieve the status of a specific request. The server responses either with the result of the request, with the current processing state or with the information that no request with the given transaction identifier exist (either the request has not yet been received or it is lost).
The other special request is the query request. By this request, the client can ask the server to send back a list of transaction identifiers of requests, whose submission or completion time falls in a specified period and that have the specified processing state.
Each registrar has its own name space for the transaction identifiers. Therefore it is not possible to request information about transactions of different registrars.
All requests sent to the server must contain at least the following four key: registrar-id, payload-version, transaction-id and request-type.
The registrar-id key identifies the registrar. It is also used for authentication in combination with the signature of the transmission layer.
the payload-version key enables the server to identify the version of the payload and to react differently to different client software versions.
The