connection setup
----------------
entirely string based (for backwards compatiblity)
1.Host A opens TCP connection to host B
2.Host B responds with header specifying server name and protocol version (human readable), example:
OpenSim 0.1-r503, running OGS protocol 1.0
3.Host B responds with machine-readable PROTO message:
PROTO 1 0
syntax is PROTO <majorversion> <minorversion>
4.Host A sends PROTO message
PROTO 1 0
5.If both hosts match, authentication mechanism is negotiated:
AUTH statickeys ssl
syntax is AUTH <authentication methods supported>
methods can be:
authkeys - must be implemented to be compliant, standard send/receive static keys
ssl - causes the binary exchange to take place over a new encrypted (via SSL) channel), need to discuss how to implement this properly (need certificates with the grid server as root authority).
The most secure one (as configured by preference list) is chosen and the response sent:
AUTHOK statickeys
syntax is AUTH <chosen authentication method>
If none are allowed, AUTHBAD is sent:
NOAUTH statickeys I don't support that method
syntax is:
NOAUTH <method>
If the protocols do not match, the host with the newer protocol will evaluate if it is backwards compatible enough. If not, the FAIL response is sent:
FAIL PROTO you are running too old a protocol, please update
syntax is:
FAIL <command> <message>
FAIL may also be sent at any other point for any command
6.Authentication with statickeys takes place, or whatever other method
Host A sends:
AUTHKEY blabla
Host B responds:
AUTHKEY blabla
both hosts check the keys against their receive_key config and send the appropiate response:
READY
or
FAIL AUTHKEY sorry, that key is wrong
CLOSE
guess what CLOSE does ;)
7.Once a READY is received by host A, host A sends a READY to host B
8.Once both ends have sent a READY, we go from text mode into binary mode and can exchange messages as below. Though rare, a host may also send FAIL READY, thus closing the connection.
note, PROTOXML may be used in place of PROTO above and will cause the XML-serialised form of all these messages to be sent.
messages
--------
header (prepended to all messages)
uint8 protocol_version_major
uint8 protocol_version_minor
uint16 message_type
uint32 message_size
byte flags (right to left)
final message (close connection after this)
request ack (sent with an empty message_size and message_type=0 to act as a ping)
reserved
reserved
reserved
reserved
reserved
reserved
each of the messages below will be assigned a type based on an enum or some such:
user control
UUID AgentID
UUID SessionID
UUID SecureSessionID
double startpos_x
double startpos_y
int8 firstname_length
char[x] firstname
int8 lastname_length
char[x] lastname
byte flags (right to left)
create/update child agent
upgrade child agent to adult
downgrade adult agent to child
destroy agent
reserved
reserved
reserved
reserved
neighbour control
UUID NeighbourID
uint16 sendkey_length
char[x] sendkey
uint16 recvkey_length
char[x] recvkey
uint32 regionlocX
uint32 regionlocy
uint32 sim_ip
uint16 sim_port
byte flags (right to left)
create/update neighbour
delete neighbour
reserved
reserved
reserved
reserved
reserved
reserved