Network Working Group K. Crispin INTERNET-DRAFT D. Crocker R. Gaetano Expires in six months S. Langenbach November, 1998 Shared Registry System Protocol (SRSP) STATUS OF THIS MEMO This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. 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." To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). ABSTRACT This specification describes a protocol for a Shared Registry System (SRS) that allows multiple registrars to register domain names within a single Top Level Domain (TLD). The protocol is high-level, text-based, and can be used over many underlying transport mechanisms, including email. The semantic content of the protocol is expressed as a set of keyword-value pairs; the semantics and structure of this content is, in this document, loosely described as the "payload". The protocol described herein is essentially identical to the SRS version 1.5 protocol, specified by the CORE SRS RFP and developed by Curt Meyer of Emergent Corporation. TABLE OF CONTENTS 1. ARCHITECTURE FOR A SRS 1.1. Communications 1.1.1. Failure model 1.1.2. Transaction State 1.1.3. Trust 1.1.4. SRS multiplexing of email and wire protocol 1.1.5. Encapsulation 1.2. Disaster recovery 1.3. Administration 1.4. Database Publishing 1.4.1. Whois 1.4.2. Zone Files 1.4.3. Fielded data 2. SRS PROTOCOL 2.1. Generic Syntax 2.1.1. Character Set 2.1.2. Keyword-value Pairs 2.1.3. Overall Composition 2.2. Requests 2.2.1. Generic Fields 2.2.2. Operations-Specific Fields 2.3. Responses 2.3.1. Generic Fields 2.3.2. Response-specific fields 2.4. Error Conditions 2.4.1. Error categories 2.4.2. Specific errors 2.5. Notes 2.5.1. Field checking 2.5.2. Remove Contact 2.5.3. Policy Decisions 2.5.4. More sophisticated syntax 2.5.5. Host leaks 2.5.6. Handle namespace 3. SRS TRANSPORT 3.1. SRS over Email 3.1.1. Encapsulation and Exchange 3.1.2. Errors 3.1.3. Notes 3.2. SRS over TCP Encapsulation and Exchange 3.2.1. Connection 3.2.2. Errors 4. SECURITY CONSIDERATIONS 4.1. Definitions 4.1.1. Contact 4.1.2. Key 4.1.3. Owner 4.1.4. PGP 4.1.5. Crypt 4.2. Key Management 4.2.1. Registrar Keys 4.2.2. Registry and Dispute Resolution Agency Keys 4.2.3. Master Key Compromise 4.2.4. Agent Key Compromise 4.3. Authentication Schemes 4.3.1. PGP Signatures 4.3.2. Crypt Authentication 4.4. Notes 5. ACKNOWLEDGEMENTS 6. AUTHORS' ADDRESSES 7. REFERENCES 8. FULL COPYRIGHT STATEMENT 1. ARCHITECTURE FOR A SRS This section describes a reference architecture for a shared domain name registry system. Explicit goals of this system include having mutually distrustful registrars, simple transfer by a domain holder between registrars, extensive use of public key signatures for authentication and nonrepudiation, robustness in the face of failure of any component, and ease of implementation. Note that this reference model is based on the actual CORE implementation, and is therefore more specific than is necessary to describe the protocol. Three entities is party to most SRS operations: * Domain holders (the customers), * Registrars (hereafter referred to as the client), and * Shared Registry System (hereafter referred to as the SRS). This reference architecture is mostly concerned with the interaction between the registrar and the SRS. Communications, billing, authentication, etc., between the domain holder and the registrar are beyond the scope of this document, and are expected to vary widely, given the variation in registrar business models. 1.1. Communications A Shared Registry is assumed to be composed of three tiers of machines: client machines, operated by the registrars, and fronted and database machines, operated by the registry. The split between fronted and database machines is motivated by two factors -- performance and security/integrity of the database. The fronted and the database could be the same machine, especially with a small registry. The front-end/database machine(s) are collectively referred to as the SRS. In a large installation both the fronted machines and the database machines may be replicated for performance and robustness, as well, with the front ends specialized for secure network communications, and the database machines specialized database engines. The client machines interact only with the fronted machines, and the database machines interact only with the front-ends as well. The client <-> fronted protocol is the focus of this document, and it is what we refer to as the "SRS protocol". 1.1.1. Failure model An end-to-end acknowledgement is generated by both the SRS and the client when requests or replies are received. This ack allows fault recovery to be very straightforward. All operations that modify state can be reissued benignly given appropriate duplicate detection logic in the database machines. Given this characteristic, a communications failure at any point can be recovered by the client retrying the operation in question. 1.1.2. Transaction State All changes to the SRS initiated by a registrar are uniquely identified by a transaction identifier generated by the client. This transaction id will consist of a registrar key, a date, and a serial number. We assume that no state is maintained on the fronted machines. All state is distributed between the database servers, and the client machines. A recovery protocol is used to synchronize the client and database server's idea of a request's state. Digital signatures are used to detect forged state changes. 1.1.3. Trust All requests are signed by the issuing registrar. A transfer request is optionally signed by the domain holder. The registrar's public key was signed by the registry, and this certificate was communicated to the SRS when the registrar was entered into the system. Each database object has a registrar of record; only that registrar may issue changes to that object. A transfer operation is the operation of changing the registrar of record. A backend process notifies, via email, the previous registrar of a transfer of an object to another registrar. Each domain and host also has a set of contacts, each of which may have an associated key. A transfer request must be signed by one of these contacts. All replies sent to a client contain the associated request body. This reply body is itself signed by the database server. This reply is a nonrepudiatable certificate that the operation actually completed. The SRS database logs all of these certificates. A wise client would keep records of all signed reply bodies indefinitely, as they are nonrepudiatable proof of a completed transaction. The SRS private key is stored on each of the database servers, and is used to sign all replies, and sign the zone files for each TLD. The database servers also verify the signature on all requests. The fronted machines simply route traffic to client machines, send and receive email, and distribute signed zone files. At all times, it is assumed that the fronted machines have been compromised, and thus, all successful attacks on the front-ends result in at most a denial of service. Since the front-ends have little state, they can be reloaded from a known-good root disk image, and restarted. As the front-ends are likely to be replicated, these restarts will probably not even be noticed by clients. 1.1.4. SRS multiplexing of email and wire protocol The SRS protocol is designed to support both interactive and email-based clients. The fronted machines all may receive email, and generate acknowledgement email messages when the requests have been accepted by the database server. In the CORE implementation the fronted encapsulates the email request into a wrapper identifying the reply to address, and sends the request to the database. When the database replies to the request, it then copies the wrapper from the request, and sends the reply to the fronted. The fronted strips the wrapper, and generates and sends an email message from the reply. Likewise in the CORE implementation, an interactive request has a wrapper identifying which connection the reply should be sent on. As the client will automatically retrieve any undelivered replies if the connected front-end fails, this wrapper is a hint, allowing prompt notification in most cases. 1.1.5. Encapsulation All messaging is human-readable, ASCII, using MIME multipart message encapsulation and format. All messages that do not have the exact expected number of parts are discarded, as are all messages that do not verify signatures. 1.1.5.1. Signatures PGP signatures use SHA1/DSS signatures as generated by pgp5.0 international. The signature is packaged as the second part of a two part multipart signed message. The signed message is the first part. The mime parameters for the message must include micalg=pgp-sha1 and protocol=application/pgp-signature. Multiple signatures, which are used to countersign transfer requests, are simply implemented as nested signed messages. 1.1.5.2. Replies Replies, as distinct from acks, are formed as an SRS signed message, consisting of a two part, multipart/mixed MIME message. The first part is the reply body, and the second is the request that this reply responds to. All signatures in the request are intact, and thus replies are a certificate, nonrepudiatable in both directions. 1.2. Disaster recovery Several failure modes are not recovered from automatically; indeed, a gross accident could destroy both fronted machines and database servers. Replicated state offsite is important to recover from this class of disaster. Frequent backups of the database servers set an upper bound to the amount of lost state in the SRS. Daily delivery of backup media to offsite storage will safeguard against data center destruction, and allow a rebuild up to the point of the backup. As clients have been sent nonrepudiatable certificates of request completion, when a client connects to a resurrected SRS, the SRS may request a replay of these certificates. These will then be used to resync up to the instant of failure. Any unacknowledged requests are re-sent by the client as in the communications failure case. Geographically colocated clients could be affected by the same disaster, and in this case, data will be lost. A future, related approach, has all these certificates being sent to a set of geographically well-distributed sites. On resurrection, these sites are queried for up-to-the-crash certificates, which are replayed. The advantage of this is that no certificates need be kept on the clients. A final, expensive approach has the database itself replicated, with automatic failover. Oracle has several different mechanisms to support this option. 1.3. Administration The SRS has an administrative interface, allowing full database control from on-site only. Backups are online, not interrupting database access, and zone file generation is automatic, placing the zone files on the fronted machines for distribution via BIND. A TLD name server is refreshed frequently from a signed zone file; if a signature does not verify, the zone file is not loaded, and an alarm triggered, causing an expert to be automatically paged. 1.4. Database Publishing A periodic extract of all data is performed. This single extract is used to generate whois information, new zone files, and fielded data files. 1.4.1. Whois As whois is a primitive interface, a read-only database optimized for text searching is loaded onto the fronted machine designated as the whois server. 1.4.2. Zone Files A total count of rows is calculated at extract time for each TLD. A generated zone file must have this many rows contained within it. If this comparison fails, the zone file is not signed or distributed. DNSSEC is expected to be deployed during 1998, so complex signing will need to be phased in. 1.4.3. Fielded data Interested parties may download the entire database, or changes since the last download, in a well-defined form, to be documented. 2. SRS PROTOCOL This section specifies the SRS Protocol "payload", or request/reply semantic content, for each of the operations the SRS will support. The transport and authentication related "wrapper" portions of the protocol are described in later sections. 2.1. Generic Syntax One of the design goals of the SRS protocol and payload is to allow the use of unauthenticated[DHC1] communications paths, placing all responsibility for security on a well-controlled database backend server. A variety of communications layers can be used as transport for the identical payload, including email. Thus, the payload is in a form suitable for manual composition of this email by a human operator. The general form of the payload is thus similar to any number of other textual field-based protocols. 2.1.1. Character Set The payload will be expressed in the 7-bit ASCII character set. ASCII double-quotes ('"'), newlines, and backslashes ('\') have special meaning as described in 2.2, and lack special meaning except in the specific contexts described. 2.1.2. Keyword-value Pairs A payload consists of successive keyword-value pairs, expressed either as in 2.2.1 or 2.2.2. 2.1.2.1. Unquoted A keyword-value pair may be expressed as follows: KEYWORD lwsp ':' lwsp VALUE lwsp newline Where KEYWORD consists of a sequence of printable, non-whitespace ASCII characters excluding colon (':'). VALUE consists of a sequence of printable ASCII characters, including whitespace. VALUE will be terminated by an ASCII newline, except that a newline immediately preceded by a backslash will not terminate VALUE, but will instead cause the backslash-newline sequence to be ignored. Thus, backslash-newline will cause the concatenation of textual lines of payload into a single value (not including the backslash-newlines themselves). Whitespace ("lwsp") between the delimiting colon and the first subsequent non-whitespace character will not be considered a part of VALUE, nor will the terminating newline, nor will whitespace immediately preceding the terminating newline. Note that a VALUE whose last character is backslash may be expressed by the inclusion of one or more whitespace characters between the backslash and the terminating newline. 2.1.2.2. Quoted Alternatively, if the first non-whitespace character after the colon is an ASCII double-quote, the keyword-value pair is taken to be expressed in quoted form: KEYWORD lwsp ":" lwsp "VALUE" lwsp newline KEYWORD consists of a sequence of printable, non-whitespace ASCII characters excluding colon. VALUE is taken to be every character between the initial double-quote and the next double-quote in the payload, including whitespace and newlines, excluding the double-quotes themselves. However, if the initial double-quote is immediately followed by another double-quote, VALUE is considered to be unquoted as described in 2.2.1, except that the two leading double-quotes will be taken as a single double-quote character. Note that the quoted form does not allow for the expression of double quotes anywhere in VALUE. This form is intended to permit the simple inclusion of multi-line base-64 PGP signatures in payloads; as base-64 encoding does not use the ASCII double-quote character, this simple alternative will suffice. 2.1.3. Overall Composition The term "field" shall be used hereinafter to refer to a keyword-value pair, and a specific field may be referred to by its keyword. No two fields in the same request may contain the same keyword. Unless otherwise specified, field values may be up to 255 bytes in length. The entirety of a payload, with attached signatures and encapsulations may not exceed 65536 bytes. Any ill-formed payload in a request will result in the failure of the request, resulting in the SRS sending an appropriate error message. 2.1.3.1. Case Sensitivity Keywords are not case-sensitive. Unless otherwise specified, field values are case-sensitive -- case information will be stored in the database as supplied, and matching operations will be case-sensitive. 2.1.3.2. Dates All dates communicated to and from the SRS will be UTC dates in the format YYYYMMDD [HH:MM:SS] where HH represents the hours on a 24-hour clock. Dates without the HH:MM:SS portion shall be considered to be midnight at the beginning of the specified day. 2.1.3.3. Localization It is expected that the Keywords specified herein will eventually be translated to multiple human languages, with appropriate changes in encapsulation. However, character set will still be restricted as in 2.1 above. 2.2. Requests This section documents the contents of the payload associated with an SRS request. 2.2.1. Generic Fields The following fields must appear IN ORDER as the first fields in a payload. 2.2.1.1. Payload-Version This field specifies the version of the SRS protocol the remainder of the payload uses. The remainder of the payload must be compliant with the corresponding version of this document, and the client is expected to be able to appropriately process any reply message generated according to the same version of this document. The only currently defined value for this field is the literal "1.0". This field is mandatory. 2.2.1.2. Registrar-Id The previously assigned identifier for this registrar in the SRS. Among other things, this value will be used to determine the type and key for cryptographic verification of the request. This field is generally the fully qualified domain name of the registrar. This field is mandatory. 2.2.1.3. Transaction-ID This is a single printable word (no whitespace). This field specifies the identifier to be used to denote this transaction. This identifier must be unique across all transactions submitted by a particular registrar. The registrar may use any policy to generate a transaction-ID. It is strongly recommended that transaction-IDs begin with the registrar-ID as defined in 3.1.2. In the case of a transaction status inquiry, this field should be the Transaction-ID submitted with the request for which status is desired. This field is mandatory for all operations. While the initial implementation of the SRS will respond to status and query requests synchronously, this allows future implementations to respond asynchronously without changes to the protocol. 2.2.1.4. Request-Type This field specifies the request type. All values of this field will be stored and treated as lower-case. Currently defined values for this field are: "create" lwsp "contact" "create" lwsp "host" "create" lwsp "domain" "modify" lwsp "contact" "modify" lwsp "host" "modify" lwsp "domain" "remove" lwsp "host" "remove" lwsp "domain" "transfer" lwsp "host" "transfer" lwsp "domain" "inquire" lwsp "domain" "inquire" lwsp "contact" "inquire" lwsp "host" "renew" lwsp "domain" "status" "query" Note that we do not currently specify a "remove contact" operation. This is to ease the tracking of events associated with a domain; we don't potentially have to go through history attempting to recreate contact information as well as domain information. This field is mandatory. 2.2.1.5. Signer-Handle The handle of a pre-existing contact whose authentication information is used to authenticate the request. This field must exist if and only if the request is doubly signed (the other signature being that of the registrar) as described in the SRS Architecture Specification, or if the request is authenticated using a stored secret. A request will fail if one of the following occurs: (1) It is required to be doubly signed by the SRS Security Policies document, and is not. (2) The value of this field is not a valid contact who is authorized to authenticate this transaction according to the SRS Security Policies document. This check is made before the application of this request. (3) Authentication, performed according to the information in the contact record associated with this field, fails. Note that if a request is doubly signed and one of 2 or 3 above fail, the request will fail even if it is not required by the SRS Security Policies document to be doubly signed. 2.2.1.6. Authenticating-Key The secret key used to authenticate a request. This field must only exist if the contact specified in the mandatory Signer-Handle value uses Crypt authentication. 2.2.2. Operations-Specific Fields This section documents fields that are specific to each possible value of the Request-Type field. Unless otherwise specified, these fields may appear in any order (after those specified in 3.1) 2.2.2.1. Create Contact The create contact operation results in the creation of a contact record in the SRS. In order to support the potential exchange of TLD databases, functionality to support user-specified handles is included. No checking is performed to prevent the creation of duplicate contacts (with different handles). Handle A single printable word (no whitespace), not beginning with '=', case-insensitive. All values of this field will be stored and treated as upper case. This field is optional; if specified, an attempt is made to create the contact with the specified handle. If the specified handle already exists in the database, the operation fails and no contact information is created. Name A printable string (may include whitespace). The name of the contact. This field is mandatory. Title A printable string (may include whitespace). The contact's title. This field is optional. Organization A printable string (may include whitespace). The organization to which the contact belongs. This field is optional. (In particular, it is clearly inapplicable to the nominative domain.) Address-1, Address-2, City, State, Postal-Code, Country All of these fields are printable strings (may include whitespace). These contain the contact's postal address information. No checking is performed to ensure correctness or completeness of the address; specification of an accurate address is strongly encouraged, for obvious reasons. In particular, unspecified country fields may not be assumed to be the United States. All of these fields are optional. Email A printable string (may include whitespace). The contact's email address. No checking will be performed to ensure its validity. This field is mandatory. Phone A printable string (may include whitespace). The contact's international telephone number. No checking will be performed to ensure its validity. Specification of a complete telephone number, including country code, is strongly encouraged; telephone numbers may not be assumed to be in the United States. This field is optional. Auth-Type This field specifies the type of authentication to be performed in order to verify this contact's digital signature. All values of this field will be stored and treated as lower case. Currently defined values are: pgp5 crypt none This field is mandatory. Auth-Key A printable string of up to 1,023 characters (may include whitespace). Specifies the key to be used to verify the validity of a request to change this contact. Its contents are dependent on the value of the Auth-Type field. This field is mandatory, unless the value of the Auth-Type field is "none", in which case it must not be specified. Fax A printable string (may include whitespace). The contact's international fax telephone number. No checking will be performed to ensure its validity. Specification of a complete telephone number, including country code, is strongly encouraged; telephone numbers may not be assumed to be in the United States. This field is optional. 2.2.2.2. Create Host The create host operation results in the creation of a new host record in the SRS. This operation may implicitly create contact records and other information in the SRS. If these operations fail for any reason, the entire operation fails and no change is made to the SRS. Handle A single printable word (no whitespace), not beginning with '=', case-insensitive. All values of this field will be stored and treated as upper case. This field is optional; if specified, an attempt is made to create the host with the specified handle. If the specified handle already exists in the database, the operation fails and no host information is created. IP-Address This field is a list of 4-octet IP addresses for the nameserver. IP addresses are expressed in decimal-"dot" format; each of the four octets is represented as decimal ASCII text, separated by '.' (e.g., "140.174.2.181"). No verification is performed on this field beyond syntactic correctness. In particular, no duplicate checking is performed, so multiple host records can exist for the same IP address. This enables a user to administer several different "sets" of domains on one nameserver if so desired. This field is mandatory. Domain-Name This field is a valid fully-qualified domain name as specified in RFC 1034 et seq. It is taken to be the domain name of this host. All values of this field will be stored and treated as lower case. Contact Information Each host must have contact information associated with it. This contact may either be supplied as the handle of a pre-existing contact, or it may be created "implicitly" from information supplied as part of the Create Host operation. The presence of valid contact information supplied by one of these two methods is mandatory; if an error occurs, the entire create host operation fails and no changes are made to the SRS. Contact-Handle The handle of a pre-existing contact generated by the SRS. All values of this field will be stored and treated as upper case. This contact is associated with the host. If this contact handle does not exist, the entire create host operation fails and no changes are made to the SRS. Implicit Contact Creation Contacts may be created implicitly by specifying contact information in fields named by prepending the string "Contact-" to the field names specified in 3.2.1.2 -- 3.2.1.9. Fields are mandatory and subject to validity checking as specified in 3.2.1.2 -- 3.2.1.9. If an error occurs during implicit contact creation, the operation fails and no changes are made to the SRS. 2.2.2.3. Create Domain The create domain operation results in the creation of a domain record in the SRS. This operation may also implicitly create contact records and other information in the SRS. If any of these operations fail for any reason, the entire operation fails and no change is made to the SRS. TLD This field specifies the top-level domain in which the domain should be created. All values of this field will be stored and treated as lower case. This field must match one of the top-level domains being managed by this SRS; otherwise, the operation fails. This field is mandatory. SLD A valid second-level domain name, as defined in RFC-1034 et seq. This field is not case-sensitive, and will be mapped to lower case for storage in the database. If both the TLD and SLD fields match those attributes of a preexisting domain record, the operation will fail. This field is mandatory. Nameservers Each domain has no fewer than two and no more than twelve host records associated with it. These hosts are expected to act as the domain's nameservers. This protocol supports both the use of pre-existing hosts by handle and the implicit creation of hosts by the specification of host creation information in a domain creation operation. The nameservers for a domain are numbered sequentially, starting from 1. Each of the nameservers for the domain may be a pre-existing host, referenced by handle, or an implicitly-created host. Each nameserver is handled identically. For the purposes of the remainder of 3.2.3.3 and for 3.2.3.7, "" may be replaced with the concatenation of "NS" (case-insensitive) and the decimal ASCII representation of the sequential number of the nameserver. -Handle The handle of a pre-existing host. If a host with this handle does not already exist in the SRS, the entire domain creation operation fails and no changes are made to the SRS. If this field is specified for a nameserver number, implicit host creation may not be specified for that nameserver. This field is case-insensitive. Implicit Host Creation Hosts may be created implicitly by prepending the string "-" to the fields specified in 3.2.2.2 -- 3.2.2.4. Implicit contact creation as part of implicit host creation, as described in 3.2.2.4.2, is supported by prepending "-Contact-" to the field names described in 3.2.1.2 -- 3.2.1.9. A linked contact specification is supported for the host contact handle ("-Contact-Handle") as specified in 3.2.3.7. If an error occurs during this process, the entire domain creation operation fails and no changes are made to the SRS. If implicit creation is used for a nameserver, -Handle may not be specified for that nameserver. Implicit host creation with a user-supplied handle is not supported. Contact Information Each domain has exactly three contacts associated with it: a technical contact, an administrative contact, and a billing contact. Any two or more of these may be the same contact. Each of the three contact types is handled identically, so for the purposes of the remainder of 3.2.3.4, the string "" may be replaced by one of "Admin", "Tech", or "Billing". As described below, contact information for each contact type must either be specified as the handle of a preexisting contact, or a contact record must be implicitly created. If any operation fails for any contact, the entire domain creation operation fails, and no changes are made to the SRS repository. -Contact-Handle A single printable word (no whitespace), case-insensitive. If the value of this field begins with '=', the value of the field is a linked contact specification as described in 3.2.3.7. If the value of this field does not begin with '=', the value must be a pre-existing contact handle, in which case the contact with that handle is associated with the domain. If the contact does not exist, the entire domain creation fails. If -Contact-Handle is specified, implicit contact creation may not be used for that contact type; specification of any other contact information fields for that contact type causes the operation to fail. This implies that a specific contact handle may not be requested as part of an implicit contact creation. Implicit Contact Creation Contacts may be created implicitly by specifying contact information in fields named by prepending the string "-Contact-" to the field names specified in 3.2.1.2 -- 3.2.1.9. If implicit contact creation is used for a contact type, -Contact-Handle may not be specified for that contact type. Fields are mandatory and subject to validity checking as specified in 3.2.1.2 -- 3.2.1.9. Status This field specifies the status of the domain. All values of this field will be stored and treated as lower case. Currently defined values are: reserved production expired hold This field is mandatory. The semantic meanings for these values are defined in the section describing the Dispute Resolution Agent (DRA) interface. Linked Contact Specification A domain creation operation can result in the implicit creation of a number of contact records, both as domain and host contacts. The SRS supports the use of multiple instances of the same implicitly created contact as part of a domain creation; e.g., "Implicitly create a contact as the domain technical contact, and also use that contact as the domain administrative contact and the host contact for nameserver five." This is accomplished by specifying contact handles beginning in '=', followed by one of "admin", "tech", "billing", "ns1", "ns2", "ns3", ... (case insensitive). When a contact handle field is specified as one of these equivalences, the contact whose type is the remainder of the field value after the '=' is also used for the specified contact. For example, if the line "Admin-Contact-Handle: =ns3" appears in a domain creation, whatever contact is used as the host contact for the third nameserver of the domain will also be used as the administrative contact. Note that the actual contact handle is stored in the SRS repository; if the host contact for the third nameserver is subsequently changed, the domain's administrative contact will not be. Circular references are, of course, not allowed. Also note that "-Handle" (3.2.3.3.1) and "-Contact-Handle" (3.2.3.3.2) are NOT equivalent; the former is the handle of a host, while the latter is the handle of the host's contact. Organization The name of the Entity or Organization registering the domain. This field is mandatory. 2.2.2.4. Modify Contact This operation is used to modify a contact record in the SRS. Handle The value of this field must be a pre-existing contact handle. This field is case-insensitive. There is no facility for modifying a contact's handle. All other information may be modified, but the handle is considered unique and invariant for the life of the contact. This field is mandatory. Contact Information Any of the fields specified in 3.2.1.2 -- 3.2.1.9 may be specified here. None of these fields are mandatory in the context of a modify operation, except that Auth-Key must be specified if Auth-Type is specified. If specified, the value of a field is subject to the same verification criteria as in 3.2.1, after which its value replaces the previous value for the specified attribute of the contact. If any errors occur, the entire operation fails, and no changes are made to the SRS repository. 2.2.2.5. Modify Host This operation is used to modify a host record in the SRS. It may also be used to implicitly create a new contact record for the host as specified in 3.2.2.4.2. Handle This is the handle of a pre-existing host in the SRS. This field is case insensitive. This field is mandatory, and specifies the host to be modified by this operation. Host Information Any of the fields described in 3.2.2.2 -- 3.2.2.4 may be specified here. Any or all of these fields may be specified independently, except that the specification of a contact handle and the implicit creation of a new contact are mutually exclusive as specified in 3.2.2.4. The modification of a contact is not allowed in the context of a host modification. Specification of any Contact field as in 3.2.2.4.2 will be considered to be an attempt to associate the host with a different, newly-created contact of the specified type. The problem of erroneous creation of new contacts due to this is expected to be minimal, as most requests that attempt to implicitly modify a contact as part of a host modification will likely be missing one or more of the fields required for contact creation (such as authentication information fields), causing the entire host modification request to fail. If any errors occur, the entire operation fails, and no changes are made to the SRS repository. 2.2.2.6. Modify Domain This operation is used to modify a domain record in the SRS. It may also be used to implicitly create new contacts or nameserver hosts for the domain, in the manner specified in 3.2.3. TLD, SLD Both of these fields must match a pre-existing domain in the SRS. These fields are case-insensitive. There is no facility for renaming a domain. All other information may be modified, but the domain name is considered unique and invariant for the life of the domain. It is expected that a "rename domain" be executed as a "create domain" followed by a "remove domain". These fields are mandatory. Domain Information Any of the fields specified in 3.2.3.3 -- 3.2.3.6 may be specified here. With the exceptions documented below, any or all of these fields may be specified independently. They will be subject to the same verification checks as in 3.2.3, and will then replace the old attributes of the domain that correspond to these fields. Implicit contact and host creation may be a part of the domain modification operation, as specified in 3.2.3.3.2 and 3.2.3.4.2, may be a part of the modify domain operation. If an error occurs, the entire domain modification operation will fail and no changes will be made to the SRS. Fields may be specified independently as described in 3.2.3.3 -- 3.2.3.6, according to the following additional rules: Nameservers Replaced as a List The nameservers associated with a domain must be replaced as a list. nameservers in a modify domain operation must be specified sequentially starting from 1, and the entire list of nameservers for a domain will be replaced with the list specified in the modify operation. No Implicit Modification The modification of a contact or host record cannot be specified as an implicit part of a domain modification request. Specification of any explicit creation fields from 3.2.3.3.2 or 3.2.3.4.2 will be considered to be an attempt to associate the domain with a different, newly-created object of the specified type. The problem of erroneous creation of new objects due to this is expected to be minimal, as most requests that attempt to implicitly modify an object as part of a domain modification will likely be missing one or more of the fields required for object creation, causing the entire domain modification request to fail. Linked Contact Specification The linked contact specification described in 3.2.3.7 is allowed. Changes are made in order of dependency, such that for a field entry of "-Contact-Handle: =", the contact would be updated before its transitive assignment to the contact. 2.2.2.7. Remove Host This operation removes a host from the SRS repository. Removal of disused host records is strongly encouraged. Handle A pre-existing host handle in the SRS, case insensitive. This host is removed from the repository. This field is mandatory. 2.2.2.8. Remove Domain This operation removes a domain record from the SRS repository. TLD, SLD Both of these fields must match a pre-existing domain in the SRS. These fields are case-insensitive. Naturally, these fields specify which domain to remove. These fields are mandatory. 2.2.2.9. Transfer Contact This operation transfers the registration function of a contact from its previous registrar to the requesting registrar. Handle A pre-existing contact handle in the SRS repository, case insensitive. This contact will be transferred to the requesting registrar. This field is mandatory. 2.2.2.10. Transfer Host This operation transfers the registration function of a host from its previous registrar to the requesting registrar. Handle A pre-existing host handle in the SRS repository, case insensitive. This host will be transferred to the requesting registrar. This field is mandatory. 2.2.2.11. Transfer Domain This operation transfers the registration function of a domain from its previous registrar to the requesting registrar. TLD, SLD Both of these fields must match a pre-existing domain in the SRS. These fields are case-insensitive. These fields specify which domain to transfer. These fields are mandatory. 2.2.2.12. Status This operation allows a registrar to query the database for the status of a transaction previously submitted by that registrar. It is a request to the SRS to resend the reply information of a transaction; if the request has been completed, it will cause another copy of the authenticated reply to the transaction to be returned to the user. Records of old transactions, and thus the information required to reconstruct replies, are not guaranteed to persist in the SRS database indefinitely. It is anticipated that a registrar can determine the completion of an old transaction by determining the status of a domain through a mechanism such as whois. This request is not valid for transaction IDs of query requests. The Transaction ID for which the reply is requested is conveyed in the Transaction-ID field (3.1.3). Since this operation is a solicitation for a resend of a transaction reply, it does not have a transaction ID of its own. Thus, the status operation does not have any fields other than those documented in 3.1. 2.2.2.13. Query This operation allows a registrar to request a list of its past requests that satisfy a Boolean predicate. A list of all transaction ID's of requests submitted by the querying registrar in the SRS database's stored history that satisfy all of the specified clauses is returned. History records will not be preserved online in the SRS database indefinitely. It is expected that a registrar can deduce the results of a sufficiently old transaction by a mechanism such as whois. All of the fields documented in below are optional. To be included in the returned list of transaction ID's, a request must satisfy all predicates specified. Request-State This field is a set of one or more case-insensitive keywords separated by whitespace. Requests whose state matches one of the keywords as of the execution of the query satisfy this clause. Valid keywords are the request states listed in 4.2.2.1. Submitted-Since This field is a UTC date and time, as specified in 2.3.2. Requests queued for processing after the specified time satisfy this clause. Submitted-Before This field is a UTC date and time, as specified in 2.3.2. Requests queued for processing before the specified time satisfy this clause. Completed-Since This field is a UTC date and time, as specified in 2.3.2. Requests whose processing completed after the specified time satisfy this clause. Completed-Before This field is a UTC date and time, as specified in 2.3.2. Requests whose processing completed before the specified time satisfy this clause. 2.2.2.14. Domain Inquiry Registrars may inquire all the SRS database state of a domain. This is accomplished via the Inquire Domain Request. This is a synchronous request. TLD, SLD Both of these fields must match a pre-existing domain in the SRS. These fields are case-insensitive and mandatory. 2.2.2.15. Contact Inquiry Related to domain inquiry, registrars have the ability to resolve contact handles to keyword-value pairs defining that contact. This is a synchronous request. Handle The value of this field must be a pre-existing contact handle. This field is case-insensitive and mandatory. 2.2.2.16. Host Inquiry Related to the domain inquiry, registrars have the ability to resolve host handles to keyword-value pairs defining that host. A Contact-Handle keyword is supplied by the registrar and the SRS replies accordingly. This is a synchronous request. Handle This is the handle of a pre-existing host in the SRS. This field is case-insensitive and mandatory. 2.2.2.17. Renew Domain This operation adds a system-defined interval to the domain's expiration date in the SRS repository. TLD, SLD Both of these fields must match a pre-existing domain in the SRS. These fields are case-insensitive. Naturally, these fields specify which domain to renew. These fields are mandatory. Any attempt to renew a domain outside of the registries policy-defined threshold for renewal will cause the request to fail. 2.3. Responses This section documents the various fields that may appear in the server's responses to an operation. 2.3.1. Generic Fields The following fields appear in order in all responses. 2.3.1.1. Registrar-ID This is the registrar ID supplied in the request that elicited this response. This field will not be supplied in the event of a request parse error occurring before the registrar ID could be determined. However, if the wireline protocol is used to communicate with the SRS, such a "short" reply will be synchronous as defined by the wireline protocol. 2.3.1.2. Transaction-ID This is the transaction ID supplied in the request that elicited this response. This field will not be supplied in the event of a request parse error occurring before the transaction ID could be determined. However, if the wireline protocol is used to communicate with the SRS, such a "short" reply will be synchronous as defined by the wireline protocol. 2.3.1.3. Response-Type This field designates the type of response. Currently defined values are: ack reply 2.3.1.4. Resolver-Sequence The sequence number of the resolution of this request. Fully explained in the FAIRNESS DESCRIPTION document. 2.3.2. Response-specific fields This section documents fields that appear in specific response types. 2.3.2.1. Ack This is an acknowledgement of a request and a confirmation that it has been queued for processing. Estimated-Completion This is a UTC date and time, as specified in 2.3.2. It represents an estimate by the SRS as to the completion time of the request. It is by no means a commitment. This field may or may not be returned. 2.3.2.2. Reply This is the reply to a request, returned by the SRS either on completion of a request or in response to a status request by the client. Request-State This describes the current state of the request in the SRS server. Currently defined values are: pending in-process succeeded failed The success or failure of the operation is authoritatively described by the content of this field, regardless of the content of any other field in the reply (including the Error-Code field). This field will be returned for all replies. Error-Code This is the decimal ASCII representation of a number between -2^31 and 2^31, exclusive, that specifically describes any errors or exceptions that occurred during request processing. Defined values for this field are described in section 5 of this document. Note that an error code may be returned with any value of the Request-State field. This field will only be returned in the event of an error or exception. Error-Text This is a single line of ASCII text that more specifically describes any errors that occurred. This field will only be returned if there is an error or exception for which the SRS can supply meaningful additional information. Contact-Handle This field is a single printable word (no whitespace). It specifies the handle of a contact that was created with a Create Contact (3.2.1) request, or the new contact of a host, either implicitly created or explicitly referenced as part of a Create or Modify Host operation (3.2.2 or 3.2.5). This field is only returned for a successful Create Contact or Create or Modify Host request. Host-Handle This field is a single printable word (no whitespace). It specifies the handle of a host that was created with a Create Host request (3.2.2). This field is only returned for a successful Create Host request. -Contact-Handle These fields are single printable words (no whitespace). can be one of: admin tech billing ns1 ns2 ns3 etc These fields specify the handles of all contacts newly associated with a domain, whether implicitly created or explicitly referenced, as part of a Create or Modify Domain request (3.2.3 or 3.2.6). Each of these fields is returned in the event of the successful association of a contact with a domain for the corresponding contact type. -Handle These fields are single printable words (no whitespace). is "NS" concatenated with the ASCII representation of a nameserver's ordinal number in a domain creation or modification. They specify the handles of any hosts that are newly associated with a domain, whether implicitly created or explicitly referenced, as part of a Create or Modify Domain request. Each of these fields is returned in the event of the successful association of the specified host with the domain. Transaction-IDs This field is a list of zero or more Transaction ID's for requests that satisfy the predicate of a Query request (3.2.13), separated by whitespace. The length of the value of this field will exceed neither 1,024 transaction ID's nor 30,000 octets. To discourage the submission of large query requests, query requests whose result set violates the size restriction will fail without returning any ID's. This field will only be returned for a successful query request. Expiration-Date This field is returned by a successful renew domain request and denotes the new expiration date. 2.4. Error Conditions This section enumerates the error conditions that can be returned in the Error-Code field. An error is expressed as the ASCII representation of a positive decimal number less than 2^31. The return of an error may not indicate the failure of a request; the request-status field is the authoritative indicator of a request's success or failure. 2.4.1. Error categories SRS-generated error codes are six-digit positive decimal numbers. They are divided into broad categories by their leading two digits. The first digit describes the severity of the error, while the second describes its general category: First digit (10^5): 1 - Informationals 2 - Warnings 3 - Transient errors 4 - Errors (typically causing operation failure) Second digit (10^4): 1 - Transport errors 2 - Request syntax errors 3 - Request semantic errors 4 - Authentication errors 9 - SRS internal errors 2.4.2. Specific errors [TBD] 2.5. Notes 2.5.1. Field checking Arguably, statements of the form "the following checking will not be performed" should not be a part of the protocol specification, as they might be taken as a guarantee that an incorrect field value will not cause an operation to fail. Rather, they are intended as a warning to the SRS client developer that the SRS server will not necessarily perform these checks; no _guarantee_ is made that more extensive validity checking will not be performed. 2.5.2. Remove Contact Do we want to implement a "remove contact" operation? Right now, we don't, in order to ease tracking of history -- to reconstruct the sequence of events associated with a domain, we don't have to reconstruct possibly defunct contact information as well. Yes, this does mean the contact table is growing monotonically... 2.5.3. Policy Decisions Several items in this document reflect policy decisions that must be made by the registry, and are specified for discussion purposes only. Specifically: Limits and defaults on domain expiration date are registry policy decisions Limits on the number of nameservers in a domain Do we want to only allow one handle per nameserver IP address? It'd be easy to do... 2.5.4. More sophisticated syntax A slightly more sophisticated grammar that expresses the relationships between objects might be cleaner. For example, this syntax doesn't express the nesting of implicit host and contact creation very well. 2.5.5. Host leaks When domains are deleted or hosts modified, it is not clear that disused host records will be cleaned up in any more than a small minority of cases. 2.5.6. Handle namespace In order to ensure transferability of information between SRS's, steps should be taken to ensure that the namespaces each SRS uses for generated names are disjoint. 3. SRS TRANSPORT 3.1. SRS over Email This section of the document describes the details of the transport of SRS payloads over email. It is assumed that the reader is familiar with MIME messages and the use of PGP within the MIME context. The SRS Payload Specification defines what is contained within the email message itself. All SRS communications are encapsulated within multipart MIME messages. Each part of a multipart may in turn contain another multi-part, as needed. The outermost layer is signed by the originator of the message using PGP. 3.1.1. Encapsulation and Exchange A single SRS request is contained within a single email message. 3.1.1.1. Reply-To Acks and Replies are sent to the Reply-To: RFC822 Header of the email request. If there is no Reply-To:, From: is used. 3.1.1.2. Selecting a server A destination email address is formed by taking the TLD, appending .nic.info, and prepending reg@fe. Thus, to register a name in .web, send email to reg@fe.web.nic.info. 3.1.2. Errors Three interesting failure modes exist: lost requests, lost acks, and lost replies. Most of the error recovery hinges on the idempotence of operations. 3.1.2.1. Lost Requests [TBD] 3.1.2.2. Lost Acks [TBD] 3.1.2.3. Lost Replies [TBD] 3.1.3. Notes Content-Encoding is currently totally ignored; eventually, some localization may be possible. 3.2. SRS over TCP A registrar may communicate with the SRS over a persistent TCP connection. Encapsulation and Exchange A registrar sends a stream of MIME-encapsulated independent requests over the connection, and reads replies and acks on the reverse channel. These requests differ from email-based MIME in that nothing may follow the trailing delimiter of a message; more specifically, the next thing immediately following a ending boundary is the Content-Type of the next message. This is because MIME encapsulation is used to detect the boundaries of requests. A request is outstanding while it has not been acked by the SRS. If there is an outstanding request, another may not be sent. 3.2.1. Connection A connection is established on a well-known port on one of a collection of fronted machines that serve registrations for a TLD. These machines all have names of the form: feXX.TLD.nic.info, where XX is a two digit ASCII decimal number, and TLD is the appropriate Top Level Domain. It is guaranteed that XX starts at 00 and there are no unresolved names between that and the highest numbered host. This can be used to load balance as follows: look up the IP address of each host in turn, starting at 00. as soon as the first one fails, the total number of fronted machines has been determined. Select one at random, and attempt to connect to it. Repeat until a connection is accepted. The SRS operator can add fronted machines as needed, without notifying any registrar. The SRS operator need only update the TLD.nic.info zone when adding or deleting machines. 3.2.2. Errors Most server or client errors are handled by disconnection, establishing known correction state, querying the state of any pending request, reissuing lost requests, and soliciting undelivered replies. Disconnection A server-initiated disconnection is indicative of a fronted failure. Any unacked requests should be resent to a new fronted connection. All pending replies should be solicited by sending a query followed by a status command for each completed request. A client-initiated disconnection may result in a pending request being processed, with the ack being dropped. The unknown state of the request should be resolved by issuing a query operation against the transaction id. If the operation is pending or completed, the request should not be reissued. 4. SECURITY CONSIDERATIONS This specification provides for database access and modification. Affected data bases are an integral part of Internet infrastructure. Hence, misbehavior or compromise of the protocol or its operation can have considerable impact on Internet operations. Other discussions concerning trust and security occur elsewhere in the specification. This section provides mechanisms, to protect against these dangers. In particular, this section specifies the SRS security policies as they relate to authentication and object modification. 4.1. Definitions 4.1.1. Contact A contact is a person who is associated with one or more objects in the SRS. Each contact has a unique contact handle, assigned by the SRS; an authentication type, and an Authentication key. 4.1.2. Key A key is a pair of data objects, one kept secret by the signer, and one widely published, including to the SRS. Keys may be of several sizes, the larger keys more difficult to crack, and more expensive in time to use. It is suggested that default size (1024 DSS/2048 Diffie-Hellman) keys be used. 4.1.3. Owner Every object in the SRS has a set of associated contacts. Any of these contacts may initiate modification of the object. 4.1.4. PGP Pretty Good Privacy software, version 5.0i. This software is resident outside of the United States, and has no export issues. It is recommended that the SRS not use PGP to encrypt, nor should it use the IDEA block cypher. It is expected that each registrar would license PGP5.0 from PGP incorporated or it's agents for commercial use. When using PGP authentication, the entire PGP public key is sent to the SRS and is stored with the contact. 4.1.5. Crypt The US National Bureau of Standards has defined a Data Encryption Standard, DES. Unix systems have used a uniform method of scrambling plaintext passwords into a non-invertable hash using DES. This uniform method is available both inside and outside the US, and so has no export control issues. When using Crypt authentication, user plaintext is encrypted, as for unix crypt(3), using a salt of '00', and the cyphertext is sent to the SRS and stored with the contact. Crypt style authentication is only valid for non-registrar contacts. 4.2. Key Management PGP has no notion of key certifying authorities. Public keys are validated by a web of trust model. 4.2.1. Registrar Keys The SRS requires each registrar to have a master key and a set of agent keys. The master registrar key is communicated to the SRS by the registry, and agent keys are communicated to the SRS by the registrar using the master key. 4.2.2. Registry and Dispute Resolution Agency Keys Registries and Dispute Resolution Agencies have identical key infrastructure to registrars. Both entities may issue modify registrar requests to manipulate its set of associated agent contacts. Special handles are defined for these entities. 4.2.3. Master Key Compromise It may occur that a registrar loses its master key, or some person illicitly acquires the registrar's master key. These are different cases, and have different methods of recovery. 4.2.3.1. Lost Master Key Typically, this is a lost passphrase. Without this passphrase, the encrypted private key stored on the registrar's machine can never be decrypted for use. The registrar generates a new key, and communicates it to the registry. The registry validates the new key, to prevent human engineering, and sends A modify contact request to the SRS, using the master contact handle for that registrar. Operations proceed using the new key. No database recovery is needed. 4.2.3.2. Stolen Master Key A stolen key can be used to forge requests to the SRS. When a stolen key is detected, a registrar should immediately issue a modify contact request for the master contact handle, setting the authentication type to none. This will disable all further operations on that registrar object until the registrar is reactivated. The registrar notifies the registry, and the registry notifies the SRS that a registrar master key has been stolen. The SRS operator will generate a report showing activity that occurred using that key. All forged requests need to be manually identified by the registrar, and the requests need to be undone. 4.2.4. Agent Key Compromise A registrar agent key may be lost or stolen as well. 4.2.4.1. Agent Key Loss Agent contacts may be freely enabled and disabled by the registrar without the registry's involvement. The registrar should create a new contact, and set that contact as a valid agent using a modify registrar command. 4.2.4.2. Agent Key Theft Stolen Agent keys should be immediately disabled using a modify registrar command. The SRS operator must be notified, and any illicit requests issued using the stolen key must be rolled back, as for a stolen master key. 4.2.4.3. User Key Compromise If all user keys associated with a domain are lost, the domain must be manually reauthenticated. This can be achieved by using a variety of non-definitive credentials to establish domain identity. Possession of a registration certificate, a cancelled check to a registrar, a copy successfully responding to the email address in a contact, being located at the listed phone number, faxing a drivers license to the SRS, etc. When sufficiently authenticated, a domain holder provides a new PGP5 key to the SRS, and the SRS manually updates the relevant contact. 4.3. Authentication Schemes 4.3.1. PGP Signatures Mime supports message authentication via its multipart/signed data type. A cryptographic hash is made of a message, and that hash is encrypted with the signer's private key. The resulting signature is packaged with the message. The SRS can detect both message corruption and/or unauthorized requests using this signature. 4.3.2. Crypt Authentication A request using crypt authentication must have a valid Signer-Handle value, and a Authenticating-Key value that exactly matches the stored key. A registrar should not store either the cleartext or the cyphertext of the key, as this will allow the registrar to forge requests for any objects protected by that contact. Similarly, a third party listening to the communication between the user and the registrar can forge requests, so a secure communications channel, such as SSL, should be used if possible between the user and the registrar. 4.4. Notes Mail-from authentication is not supported. Many attacks on mail-from type authentication schemes are known, and offer no serious security. Crypt is basically registrar-based authentication. 5. ACKNOWLEDGEMENTS This draft is heavily dependent on documentation provided by Emergent Corporation as part of their contract with CORE. We thank Curt Meyer and his colleagues at Emergent for the clear and precise work they have done. ... 6. AUTHORS' ADDRESSES K. Crispin Songbird 6064 Skyfarm Drive Castro Valley, CA 94552 USA +1 510-886-7410 kent@songbird.com D. Crocker Brandenburg Consulting 675 Spruce Drive Sunnyvale, CA 94086 USA +1 408 246 8253 dcrocker@brandenburg.com R. Gaetano roberto.gaetano@etsi.fr S. Langenbach svl@nrw.net 7. REFERENCES ... 8. FULL COPYRIGHT STATEMENT Copyright (C) The Internet Society (1998). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. draft-crispin-srs-00-txt Shared Registry System Protocol November, 1998 Expires in six months