LSL Protocol/Ganymedia OpenMAIP v1.0 Specification

From Second Life Wiki
Jump to navigation Jump to search

Preamble

NOTE: THIS IS AN ALPHA DRAFT SPECIFICATION. IT IS A WORK IN PROGRESS AND SUBJECT TO CHANGE WITHOUT NOTICE.

This document reflects the current Beta testing version of Ganymedia OpenMAIP Engine: 0.7.5

The Ganymedia OpenMAIP v1.0 Specification ALPHA FIRST DRAFT

Copyright (C) 2010 Ganymede Ceriaptrix <ganymedia@gmail.com>

This work is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA.

Ganymede Ceriaptrix <ganymedia@gmail.com> is responsible for maintenance and specification of this protocol. It is used extensively in Ganymedia Engineering's in-world applications and server-side PHP solutions, and interoperability with those applications may be achieved by conformance to this specification.

Introduction

Ganymedia OpenMAIP v1.0 (the Ganymedia Open Metaverse Application Internetworking Protocol) provides a common standard datagram communications protocol for Second Life script applications, each fulfilling their own respective functionality contracts to exchange interoperable messages by exposing query-discoverable command services and command syntax to external objects.

However, OpenMAIP's scope goes beyond chat messaging; it supports a series of communications methods, ranging from direct chat transmission to HTTP relay and e-mail, allowing potential communication between scripts running on Linden Labs' servers and third-party OpenSim grids, and even other virtual worlds systems on which an OpenMAIP implementation has been created (or is simulated via an HTTP server). Therefore, it is useful for a whole range of applications, from simple attachment-to-attachment communications, to object-to-attachment interaction, to cross-simulator and cross-grid object communications.

OpenMAIP is byte-oriented -- it consists of ASCII-armoured hex string messages rather than Unicode character representations of data and list delimiters, breaking from the SL norm; therefore it is better suited to script-to-viewer communications than traditional "loose" multi-type LSL protcols or delimited lists and, indeed, could potentially be encapsulated directly within UDP and other TCP/IP network services in the future. It has been designed with this ultimate goal in mind, for future integration of server-side networking services directly with in-world application scripts.

OpenMAIP supercedes the functionality provided by the Ganymedia Open Cryptographic Exchange Protocol, and is backwards-compatible with it. The basic notion of OpenMAIP is that it provides a common network discovery, service query and message communication framework; therefore, applications such as attachments may query for other OpenMAIP-supporting devices in their vicinity that support common functionality protocols, and also query those devices for acceptable command formats. The provision of challenge/response RC4 authentication allows conformance with closed protocols to be verified as well; it is expected that the RC4 challenge/response authentication keys will be published by architects of open protocols.

At its higher implementation levels, OpenMAIP provides industry-standard cryptographic message exchange for secure script-script, script-viewer and viewer-viewer communications across the Second Life chat messaging system. (By secure, in the sense of scripts "talking" to one another, this is meant "secure" as in "with high immunity to interception by other residents"; any individual with access to the LSL script engine would, of course, be capable of eavesdropping.)

Multimodal Transmission Layer (MTL): OSI Layer 0/1 (Physical)

Chat Channel Transport (CCT)

  • Chat Channel Transport (CCT) is the preferred method of communication, consisting of the encapsulated frame being transmitted over the current simulator's chat channel system. This is possible when both the frame sender and recipient are present within the same simulator, and MUST be used if possible. It is also the method by which OpenMAIP messages are relayed to an OpenMAIP-capable Second Life viewer application, the method by which script-to-viewer communications MUST occur.

External Relay Transport (ERT)

  • If the recipient is not present on the same simulator as the sender, and an HTTP-based route to a relay server is possible (the nature of which is implementation-dependent), the message SHALL be relayed via that HTTP relay to the destination simulator for retransmission over CCT.

Object E-mail Transport (OET)

  • Failing the above two preferred transport methods (if a route via ERT is not known in the host routing table to a distant sender), the encapsulated frame SHALL transmitted via the simulator's local e-mail functionality to the destination object's key. In the case of the Linden Lab servers, this behaviour results in an e-mail message being sent to <key>@lsl.lindenlab.com. Implementations forwarding to other providers' virtual world grids MAY be specific to e-mail transport behaviour on that simulator or simulator-like environment. In this case, the recipient_domain field present within the frame SHALL be used to determine the domain suffix.

Datagram Routing Layer (DRL): OSI Layer 2 (Network)

Constants

Constant Value Hex Value Dec Description

Static routing subnets

Domain Allocated CIDR Range Description Host Numbering Scheme
*.agni.lindenlab.com 10.1.0.0/16 Host prefix for OpenMAIP clients running within Linden Lab main grid simulators (LSL scripts that implement OpenMAIP). number packed into two octets, where number is sim[number].agni.lindenlab.com from the simulator's hostname. This can be obtained in LSL implementations using llGetSimulatorHostname().
*.phrygia.ganymede-labs.com 10.2.0.0/16 Host prefix for Ganymedia Engineering's servers. To be published.
MULTICAST_ALL_HOSTS 224.0.0.1 If frames are addressed to MULTICAST_ALL_HOSTS, they MUST be processed by all receiving hosts in the current subnet. Single-address.

Datagram Transport Layer (DTL): OSI Layer 3 (Transport)

Constants

Constant Value Hex Value Dec Description
FRAME_START_TOKEN 0x6A24 6A 24 - Magic number to signify start of frame
FRAME_END_TOKEN 0x0404 04 04 - Magic number to signify end of frame (EOT EOT)
FRAME_COUNT_MAX 0x00FF 255 Max 255 frames per message
FRAME_SIZE_MAX 0x0200 512 Max 512 bytes of payload per frame
CURRENT_VERSION 0x0100 Protocol version: xx00 - major revision; 00xx - minor revision

Frame format

Byte Index Byte Len Field Name Field Type Desc Validity rule
* 2 ident FRAME_START_TOKEN Magic identifier string ident = FRAME_START_TOKEN
* 16 dest <openmaip_ipv6> Destination object pseudo-IPv6 (128-bit) 0 < dest <= 0xFF….
* 16 src <openmaip_ipv6> Source object pseudo-IPv6 (128-bit) 0 < src <= 0xFF….
* 1 version <uns_int> Protocol version identifier 0 < version <= 0xFF
* 1 frame_count <uns_int> Total length, in frames, of the entire datagram 0 < n <= 255
* 1 frame_index <uns_int> Index of this frame within the datagram 0 < frame_index <= frame_count <= 255
* 2 frame_size <uns_int> Length, in bytes of data, that this frame contains 0 <= frame_size <= 512
* 1 encap_format <enum> Encapsulated data format
* n data <bin> Payload byte_length(data) <= 512 = frame_size
* + n 2 terminator FRAME_END_TOKEN End-of-transmission (EOT) characters terminator = FRAME_END_TOKEN
Retrieved from "https://wiki.secondlife.com/w/index.php?title=LSL_Protocol/Ganymedia_OpenMAIP_v1.0_Specification&oldid=878552"