I've received a few requests for this off the list, so I'm posting it
here. This was written based on the then-current pre2.0-1.9.7 client
release, and I haven't checked recently to see if it's accurate.
You can download this protocol and my PHP client (currently not compatible
with OpenSRS's choice of CBC implementation, I believe. Again, I haven't
played with this for a while) here:
http://devel.duluoz.net/OpenSRS-PHP/OpenSRS-PHP-0.2.tar.gz
-mike
Introduction
============
OpenSRS consists of two completely seperate subsystems: the lookup
system, and the registration system.
Version
=======
This document defines version 3.0 of the OpenSRS protocol.
Status messages
=================
Both the lookup and registration subsystems use the following
format to return the status of a request. The format is:
<code> <text>
where <code> is a three-digit, machine-readable status code, and
<text> is a human-readable description of the code. Successful
requests will result in a 2** status being returned. Unsuccessfull
requests will result in a 4** status. More specific codes are defined
for certain commands.
Lookup System
=============
Messages
--------
Messages are plain ASCII text.
Client messages consist of a single line in the format:
<command> [<parameters> ... ]
Client messages are terminated with a linefeed character ("\n").
Server messages are multi-line. The first line is a status message
in the format above. The status line is followed by zero or more
lines of data. The message is terminated by a line containing a
single period. Each line of a server message is terminated with a
carriage return - linefeed combination ("\r\n");
QUESTIONS: Why are client messages and server messages terminated
differently? The perl source uses this line to send the lookup
command:
print $fh "check_domain $domain $username $affiliate_id\n";
I suspect that this is an implementation bug in the perl library.
Connection State
----------------
The only state of a lookup connection is the command state,
described below.
Commands
--------
The only valid client command is "check_domain". The format for this command is:
check_domain <domain> [<user_id> [<affiliate_id>] ]
where:
<domain> is the domain name to be looked up
<user_id> is the reseller's OpenSRS ID
<affiliate_id> is ??????
The following status codes are returned by the server:
210 Domain name available
211 Domain name not available
505 Invalid attribute value syntax
5000 Invalid command name.
NOTE: I suspect that the 5000 code above is an implementation bug in the
current server implementation (should be 500).
Registration System
===================
Messages
--------
Both client and server messages are sent in the same format. The
first to bytes of a message are interpreted as a 16-bit, big endian
integer representing the length of the message. This two-byte header
is not included in the length calculation. The rest of the message is
plain ASCII text. Specific message formats in the different
connection states are described below.
Encryption
----------
The registration system requires that the client and server have
previously agreed upon a private key for the client. This key serves
to identify the client and is also used to create a session key for
encrypting the session.
Connection State
----------------
When a client connects to the OpenSRS server, it is in the
Authentication state. By providing appropriate credentials, the
client may move into the Command state.
Authentication
..............
The Authentication state begins when the client makes a connection
to the OpenSRS server. The server sends a message containing the string:
OpenSRS SERVER <version>
to the client. The client responds with:
OpenSRS CLIENT <version>
then sends the login command:
login -<cipher> <username>
where <cipher> is the encryption method to use, and <username> is the
client's OpenSRS ID. Currently, the only valid cipher is "des", to
use the DES cipher in CBC mode.
The server sends a message containing a random string to the
client, and the client encrypts this string using it's private key.
This encrypted string is then used as the session key in the Command
state. The server sends a second challenge to the client, encrypted
with the session key. The client decrypts the challenge, computes
it's MD5 checksum, and sends a message containing the encrypted
checksum to the server. The server compares the checksum to see if it
matches it's copy of the session key. All messages after this point
are encrypted with the session key.
The server sends a status message to the client, in the format
described above. A status code beginning with a "2" indicates
successfull authentication, and the connection moves into the Command
state. Any other status code indicates failure and the connection is
terminated.
NOTE: my testing indicates that the server terminates the
connection without sending a status message in the event of failed
authentication. This is a) bad behavior on the part of the server,
and b) not the documented behavior.
Command
.......
Commands are sent as a single line terminated by a linefeed
character. A command consists of a series of key/value pairs, in
query string format. That is, values are first URL-encoded as per RFC
xxxx, then the pairs are combined in the format:
key1=value1[&key2=value2...&keyN=valueN]
If a given key is to hold more than one value, each additional values
is appended to the existing value string, separated by a null
character ("\0"). The following keys are required to be present in
the command:
'action' is the command to be executed;
'_registrant_ip' is the IP address of the end user. Note that
this is not necessarily the IP address of the client. Most
likely, it is the address of web browser being used.
other valid keys depend on the command being executed.
Responses are sent as one or two lines, each terminated by (?) a
linefeed character. The first line is a status message as described
above. The second (optional) line consists of key/value pairs as
described in the previous paragraph.
QUESTIONS: why aren't keys also encoded? For currently valid keys
this would make no difference, but there doesn't seem to be any good
reason to send them raw.
Examples
========
<Later>
--"Modern electronic-rock music, inaugurated in the early 1960s, is, and always has been, a joint enterprise of British military intelligence and Satanic cults." -- "The Satanic Roots of Rock" http://www.av1611.org/othpubls/roots.html
GnuPG key available at http://devel.duluoz.net/pubkey.asc Key ID = 1024D/9A256AE5 1999-11-13 Mike Glover <mpg4@duluoz.net> Key fingerprint = EF6E 8BCB 4810 E98C F0FD 4596 367A 32B7 9A25 6AE5
This archive was generated by hypermail 2.1.3 : Tue Oct 19 2004 - 23:35:27 EDT