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 AND IS A WORK IN PROGRESS

The Ganymedia OpenMAIP v1.0 Specification

Specification Revision 0.1 alpha

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.


Introduction

Ganymedia OpenMAIP v1.0 (the Ganymedia Open Metaverse Application Internetworking Protocol) provides a common standard handshaking datagram exchange 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. In addition, at its higher implementation levels, it 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.)

OpenMAIP is byte-oriented (it consists of hexadecimal bytestream 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 and service query 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.

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.

Level 0: Transport Layer

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 Desc Validity rule
*	2	ident	FRAME_START_TOKEN	Magic identifier string 	ident = FRAME_START_TOKEN
*	1	version	<uns_int>	Protocol version identifier	0 < version <= 0xFF
*	8	dest	<openmaip_ipv6>	Destination object pseudo-IPv6	0 < dest <= 0xFF….
*	8	src	<openmaip_ipv6>	Source object pseudo-IPv6 	0 < src <= 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	1	terminator	FRAME_END_TOKEN	End-of-transmission (EOT) characters	terminator = FRAME_END_TOKEN