![interreality.org [VOS]](/wwwvos/banner5.jpg)
| Creating Interreality: The Virtual Object System: Version 0.23.0 | ||
|---|---|---|
| Prev | Chapter 6. VOP, a Virtual Object Protocol | Next |
6.7. Site Peering and Shutdown
All Vobject communication in VOS is routed though the site hosting that Vobject. Accordingly, in order to interact with some non-local Vobjects, a peer first needs to create a remote site Vobject. This Vobject acts as a stub for another peers local site. Note that both remote and local site have the same URL. To communicate with the local site, the stub initiates a new VOP session. To avoid confusion, the stub (remote site) will be called "client" in this section, while the local site of the contacted peer will be called "server".
During a VOP session, the client may operate in either peer mode or client only mode. If the client has its own local site it should operate in peer mode. In this case, it must use the canonical site URL as default for the from="url" attribute of outgoing messages. If the client does not have its own site, it must operate in client only mode. In this case, its default for the from="url" attribute is its local socket endpoint address, as seen by the server (see below).
In any case, the client first uses its Vobject URL to determine the host and port at which to contact the server. It establishes a network connection to the respective host and port, and starts the site peering process. The site peering process consists of a series of message exchanges. The messages used have the same encoding as regular VOP messages, but have different restrictions in respect to used attributes, parameters, etc. The following is a short overview of the site peering process:
client opens socket connection to server
client sends hello message. In peer mode, it also specifies its site aliases
server sends hello message, specifying its site aliases
client verifies server site aliases (optional)
client sends hello-reply message
server verifies client site aliases (optional)
normal messaging commences
The site peering process is different from regular VOS messaging. For once, there are different restrictions on attribute use. Also, the involved messages must appear exactly in the order described below, with no other messages in between. Any violation of these rules constitutes a fatal protocol error.
The initial hello message serves two purposes. For one, they establish the list of site aliases. The receiving peer must be capable of detecting these site aliases if they appear in subsequent messages, and resolve them to the correct target site. For that purpose, the peer should store the aliases in a lookup table, after validating them (by attempting to open a socket connection to them). Note that the order of the aliases is significant; the sending peer must sort them by descending preference. The first alias is considered to be the canonical site alias. The second purpose of the hello messages is to exchange antispoof tokens, which are used to validate site aliases. The two exchanged tokens form a unique anti-spoof pair, which both peers must pass to their local site for storage. The local site may need it to answer subsequent anti-spoof checks for the other peer. See below for details.
The client must begin the site peering process by sending the client hello message. This message must be of type <message>, and must not use any attributes except the following: The length attribute specifies the total message size as usual. The method attribute must have the value "core:hello". The to attribute must have the clients Vobject URL as value, as used to establish the connection. The further format of the message, and the subsequent message exchange, depend on the clients mode.
6.7.1. Client Only Mode
In client only mode, the client must send the client hello message with a header as specified above, and a body containing an <antispoof> parameter. The value of <antispoof> must be a unique identifier token in the scope of the client. A random 32 bit number is usually sufficient.
After receiving this message, the server must send its own server
hello
message of type <message>. The
length attribute must be used as usual,
the method attribute must have the value
"core:hello". The to
attribute must specify a VOP URL constructed from the IP address and
ephemeral port of the client, as seen by the accept()
system call. Note that it may deviate from the actual address and port used by the
client, as an intermediary NAT firewall may change them. Other attributes must
not be used in this message.
The first parameter of the message must be <antispoof>.
Its value must be a
unique identifier token in the scope of the server. The server must construct
the antispoof pair from the clients and its own antispoof token, and pass it
to its local site for storage.
All further parameters of the server hello message must be
<alias>. The
value of each must be one of the official site aliases of the server, in
full URL form. For compatibility with older VOS releases, the server should
also accept partial URLs here, and assume defaults for missing scheme and
port components.
On reception of the server hello message, the client should construct a VOP URL from the canonical site alias sent by the server, and use it as default base for the to attribute of this and any subsequent outgoing messages. Furthermore, the client must store the value of the to attribute sent by the server, and use this value as default from attribute in subsequent outgoing messages. This way, the client's from attribute will match the client socket address as seen by the server, even if an intermediary NAT firewall rewrote it. After the client received the server hello message, it may initiate anti-spoof checks of the servers site aliases, see below. Afterwards, client and server are ready for regular messaging. Note that the server must not attempt any anti-spoof checks on the client; they will most likely fail, either due to firewall issues, or because the client does not have a local site accepting connections.
Implementation note: As already stated above, the s3 version of VOS sometimes omits the length attribute on hello (and other) messages.
6.7.2. Peer Mode
The main difference in peer mode with respect to client only mode is the fact that the client communicates on behalf of its local site. Accordingly, it must use the local site URL as default from in all regular messages.
Otherwise, the first few messages exchanged during site-peering are the same as in client only mode, with one exception: The client hello message must contain a list of <alias> parameters, specifying the client site aliases of the clients local site. The format of these parameters must be the same as for the server hello message.
Since the client has its own site in peer mode, it must be able to answer anti-spoof checks for the site aliases it claimed in the client hello message. Accordingly, after receiving the server hello message the client must construct the antispoof pair from the servers and its own antispoof token, and pass it to its local site for storage.
The client may now initiate anti-spoof checks of the servers site aliases. On failure the client must abort the session at this time. Otherwise, it must confirm the reception of the servers antispoof token now. For this purpose, the client must send a hello reply message. This is a <message> with attribute method="core:hello-reply". The message must also have length and to attributes according to normal rules, and no additional attributes apart from these. The body of the hello reply message is empty.
After receiving the hello reply message, the server may initiate its own anti-spoof checks of the clients site aliases. Afterwards, client and server are ready for regular messaging.
6.7.3. Anti-Spoof Checks
Before storing the site aliases claimed by its communication partners, a peer should validate their authenticity by initiating an anti-spoof check for each of them. However, the peer may skip the checks if the authenticity is assured due to other circumstances, like within a trusted Virtual Private Network (VPN), etc. The following is a short overview of a single anti-spoof check:
peer opens connection to other site
peer sends client hello message, as in client only mode
site sends regular server hello message
peer sends anti-spoof challenge
site sends anti-spoof response
peer closes the connection
The peer initiates an anti-spoof check by extracting the host name and port number from the site alias in question, and contacts the site in client only mode. This means that it does not send any anti-spoof tokens or site aliases in its client hello message. Also, it discards any such information from the sites server hello message. After this handshake, the peer must send an anti-spoof challenge message of type <message> with method "core:anti-spoof-check" and a nonce value. The from attribute must be omitted. The message must have a single parameter <peek>, with its value the same antispoof token the peer sent in its original hello message on the session in question. Then the peer must wait for an appropriate response; this has INVOCATION semantics. Any other messages from the site must be discarded.
On reception of the anti-spoof challenge, the site must extract the challenge token from the <peek> parameter. It must then find a previously stored anti-spoof pair (partner's token, own token) where the "partner's token" matches the challenge token. The respective "own token" is the correct response. In case no such response token is found, the site should treat this as a fatal protocol error, and disconnect. Otherwise, the site must send an anti-spoof response message of type <message> and method "core:anti-spoof-reply", according to normal message exchange semantics. In particular, the response must have the same nonce value as the challenge. The body must contain a single parameter <poke> with the response token as its value.
Once the peer receives the anti-spoof response, it must close the validation connection. Furthermore, it must compare the received response token with the anti-spoof token it received in the original hello message. On a match, the peer should proceed to the next anti-spoof check. If this was the last check, it should continue the site peering process as appropriate. If the peer does not receive a reply to its checks during to a timeout, or the returned token does not match the expected value, the peer should ignore the site alias in question, i.e. should not store it for future site resolution. Such failures may occur due to aliases with restricted scope, such as local host or local network visibility only. Only if all anti-spoof checks fail, the peer should treat this as a fatal protocol error. In this case, the peer must also close the the original connection.
| Security Note |
The anti-spoof check only provides a low level of security. The rationale is to have a simple means to prevent peers from impersonating other sites. If the client would simply pretend to represent a different site, the server would contact this different site in the anti-spoof check; however, this site did not receive the original server hello message, so it will not know the correct antispoof token, and thus fail to send a correct response. In this case, the server will also refuse to talk to the pretending client. The security of this approach depends on the inability of an attacker to predict antispoof tokens, so care must be taken in generating them. |
6.7.4. Shutdown
Once a client is no longer interested in communicating with a peer server, the client must close the connection. Also, at any time during the VOP session, either client or server may encounter a fatal protocol error, and close the connection accordingly. On both normal and abortive connection closure, client and server should clear any stored data associated with this connection. This includes site aliases, anti-spoof token pairs, and template message blocks.