Capabilities

From libopenmetaverse - libomv - Developer Wiki

Capabilities is a concept in the design of secure computing systems. A capability (known in some systems as a key) is a communicable, unforgeable token of authority. It refers to a value that references an object along with an associated set of access rights.

In Second Life capabilities or Caps for short refers to a REST based system of access to certain parts of the Second Life world through HTTPS.

Technical details

The initial capability URL appears to be provided in the login response:

<?xml version="1.0" encoding="utf-16"?>
<methodResponse>
    <params>
        <param>
            <value>
                <struct>
...
                    <member>
                        <name>seed_capability</name>
                        <value>
                            <string>https://sim2.aditi.lindenlab.com:12043/cap/00000000-0000-0000-0000-000000000000</string>
                        </value>
                    </member>
...

(On sim crossings and teleports, a new URL is provided in the SeedCapability field of the relevant packets.) The client then performs a POST to that URL:

<llsd>
     <array>
         <string>MapLayer</string>
         <string>MapLayerGod</string>
         <string>NewAgentInventory</string>
         <string>EventQueueGet</string>
     </array>
</llsd>

and gets a response mapping the requested capabilities to new URLs:

<llsd>
     <map>
          <key>EventQueueGet</key><string>https://sim2.aditi.lindenlab.com:12043/cap/eb34cda6-0000-0000-0000-000000000000</string>
          <key>MapLayer</key><string>https://sim2.aditi.lindenlab.com:12043/cap/e05f9307-0000-0000-0000-000000000000</string>
          <key>MapLayerGod</key><string>https://sim2.aditi.lindenlab.com:12043/cap/899e2f11-0000-0000-0000-000000000000</string>
          <key>NewAgentInventory</key><string>https://sim2.aditi.lindenlab.com:12043/cap/469933ae-0000-0000-0000-000000000000</string>
     </map>
</llsd>

The messages use the LLSD serialization format. Data types that don't have an equivalent (such as IPADDR, U64 - but not IPPORT, which is an integer) seem to be sent as binary e.g.

<key>RegionHandle</key><binary encoding="base64">AAPmAAAD6AA=</binary>
<key>SimIP</key><binary encoding="base64">yA8FSA==</binary>

EventQueueGet is used to send messages from the simulator to the client (only TeleportFinish and SimulatorCrossing seen so far). The client keeps a request to it open at all times - if no packet arrives within a few seconds, the simulator terminates the request with a 502 Upstream error (I suspect this could change) and a new one is started by the client.

Links