LSL Protocol/Restrained Love Open Relay Group/email/006 draft

!x-email

STATUS: draft

VERSION: 006

MANDATORY DEPENDENCIES: forward, key

RECOMMENDED: sensor

005 implemented in Satomi's Multi-Relay HUD 0.93, and Satomi's Witchy Remote 1.1beta2

005 Implemented in Dahlia's multirelay >=0.39 and anythingRLV >=2.97

Initiate an email-encapsulated RLVR session.

On reception of !x-email, the relay should start checking emails periodically and execute their content as RLVR commands.

Commands:

• !x-email, which is secondarily restricting.
• !x-email/clear, which is releasing.

Presentation of e-mails

The topic: ORG encapsulated RLVR protocol,<protocol version>, <session_key>

ex:  ORG encapsulated RLVR protocol,006,45afb982-d02c-35e1-d492-a948b92c92f3

The session key is a secret shared by both relay and controlling device, and will be created during the protocol initiation. It is the same variable as the session key defined in key (understand: !x-key can be used to change the key of current email session).

The message: consists of several submessages, each on a different line.

A submessage is:

• either a RLVR standard message (only without the recipient key): <identifier>,<RLVR command> for a controlling object message, and <identifier>,<RLVR command>,<ack> for a relay message.
• either a RL viewer answer as described in forward (for instance an answer to a @getstatus or @version): <channel>,<viewer answer>

Protocol scenarii

Conventions: messages are symbolized by different types of arrows. We suppose the controller (C) is on the left and the relay (R) on the right. An arrow with a c (-c>) is a chat message on RLVR channel (or whatever channel the controller and the relay negotiated before). An arrow with a e (-e>), is a submessage (like defined before) in an email with the requirements stated before.

C(ontroller)<->R(elay)

-c> is a message by chat channel: authentified, but may not be private
-R> is a llRegionSayTo message by chat channel: authentified and private
-e> is a message by email: private but not authentified

Email session initiation

1 -c>     blah,k(R),!x-email
2 <c-     blah,k(C),!x-email,ok

After this, the relay starts polling for emails and execute them as RLVR commands. Thus later on, we can see:

...
3 -e>     blah,anything
4 <e-     blah,anything,ack

Where emails have some session key randomly generated by C (or another controller, it does not matter, since this is the example with no session transfer).

The relay can stop polling when no session has !x-email as active secondary restriction and no session uses email anymore.

Chat session can be transfered over to email by using key x-tension.

1 -R>     blah,k(R),!x-key/k(S)/!x-email        where k(S) is some randomly generated UUID
2 <c-     blah,k(C),!x-key/k(S),ok
3 <R-     blah,k(C),!x-email,ok
4 -e>     blah,anything
5 <e-     blah,anything,ack

where email messages use the previously generated k(S) in their topics. Note that !x-takeover is not needed (but can still be sent). By using the session key, the controller sending email is implicitly taking over.

k(S) being a shared secret thanks to llRegionSayTo, and included in the topic of every subsequent email, R is certain that it is really C sending emails (or another device C sent the session key to), and thus can interpret any further command as belonging to the same session (in particular keeping previous restrictions).

Provided polling is active, at any time, this exchange can happen:

1 -e>     bleh,<anything>
2 <e-     bleh,<anything>,<ack>
...

Coming from any email, even from a new unknown device (or even from a non-secondlife email!). If the session key is unknown, this must be handled like any RLVR command from a new source.

Relaying viewer chat messages:

Viewer replies are forwarded back to the controller by the relay, according to the lines of forward.

Example 1:

-e>  bloh,@getxxxx=1234
<e-  bloh,@getxxx=1234,ok
<e-  1234,<viewer_chat_message>

Example 2:

-e>  bloh,!x-fwd/getxxxx
<e-  bloh,!x-fwd/getxxx,<viewer_chat_message>

Transfering a session from e-mail back to chat

-R>     bleh,!x-takeover/k(S)
<R-     bleh,!x-takeover/k(S),ok

Note: the same would be used for transfering to http:

-h>     bleh,!x-takeover/k(S)
<h-     bleh,!x-takeover/k(S),ok

or for any other private communication channel (k(S) must not be heard by 3rd parties).

Testing controller's presence

For garbage collection purposes, be it on relog, or on regular basis, R might want to check if C is still active. The ping mechanism can be used here.

<e-    ping,ping,ping
-e>    ping,!pong

The important thing is that the relay remembers it was an email session after relog.

C can check R's presence by sending any valid message, as acknowledgement by R is required for every RLVR message from C. If the only purpose of the message is presience verification, the following scenario is recommended:

-e>    blah,!x-email
<e-    blah,!x-email,ok

Handover

!x-handover/K/n should work like in chat sessions (with the semantics that the session is transfered to the object of key K, chatting on standard RLVR channel).

Handing over to another object while remaining in e-mail mode, doesn't however require any special step. The following scenario can be used:

1 - assume C has a session with R, using key k(S)
2 - C gives k(S) to another object C' via any preferred medium
3 - now  C' can continue e-mailing with S, using key k(S) (and can use the "C has a new key" scenario)

Handing over to oneself can also be used to switch back to chat mode.

Requirements

• On !x-email acknowledgement, the relay should start listening to e-mails and handle them like RLVR messages. The relay confirms that the RLVR session with the controller is transfered to e-mail, which means e-mails with the negotiated session key should be handled as if coming from the controller.
• Whenever the relay accepts a RLV command with calls for a viewer answer (@blah=1234), the relay must listen to the viewer answer, and forward it via email to the controller, behaving exactly as if !x-forward had been issued.
• !x-forward/clear must never be acted upon within an email session (an appropriate answer is !x-forward/clean,ko).
• same for !x-email/clear