Current login protocols
 |
It has been proposed that this page or section be  merged with Authentication Flow. (Discuss) |
Introduction
This page documents the log-in protocol for Second life as it exists currently. It will eventually be replaced by the login portion of the Second Life Grid Open Grid Protocol (SLGOGP).
The purpose of this document and others like it is to give a detailed description of the Second Life protocols so that programmers can refer to it when implementing their own Second Life viewer without referring to or using the source code of either the Linden Lab viewer, or the libsecond life viewer. It also allows internal developers at Linden Lab to check their understanding of the current log-in protocol as they develop the new version described in the SLGOGP.
Working examples of this protocol are found on the links in the Example Protocol Code page
Conventions
On this page the following conventions are used:
- "in quotes is a literal string"
- [ represents a list of choices | separated by a vertical bar ]
- < represents a value which can be substituted by an appropriate string described inside >
- 'represents a string that must be quoted, but how will be implementation specific' for example in LSL "" denotes a string and " will be used in place of the single quote (').
- + means to concatenate the two parts, though how will be implementation specific, for example + can be used to concatenate strings.
Log-in
The current Second Life log-in requires the viewer to send an http/1.1 XML-RPC message with specific input parameters to a Second Life log-in URL and parse the response for further processing. The URL is specified by using "-loginuri" in the command line parameters, as described in the command line parameters page on the Second Life wiki.
Authentication Flow
This is a simplified version of the authentication flow, showing the major steps in the process.
Note: Step 6 and Step 7 are not strictly part of login and are documented in the Establishing_Avatar_Presence page.
- Step 1
- Viewer -----------> Login Server {XML-RPC)
- Step 2
- Login Server ------> Database
- Step 3
- Login Server------> SIM in the Grid
- Step 4
- SIM ----> Login server (response)
- Step 5
- Login server ------> Viewer (XML-RPC response)
- Step 6
- Viewer -------> Simulator (on Grid) Handshake
- Step 7
- Viewer -------> User server User server handshake
XML-RPC call
Note: This section details Step 1 and Step 5 of the #Authentication Flow.
Input parameters
Required parameters
The following explains the standard key value pairs, with an explanation of "options" at the end:
- • "first": <first>
- first name of the avatar.
- • "last": <last>
- last name of the avatar.
- • "passwd": '$1$' + <passwd_md5>
- the avatar password encrypted using MD5 encryption.
- • "start": ["first" | "last" | <specific location> ]
- attempt to log in to this sim, though if it is full or not available, or the agent is not allowed, another sim will be selected by the grid from its list of choices. "First" means home location. If home is filled then the grid will try last. If last is filled and home is set, the grid will try home. In either case the last choice will be from a list of telehubs. For a log in to a specific location the format is "uri:<existing region name>&<x>&<y>&<z>".
- • "channel": <channel name>
- the name of the client. Used to differentiate official viewers from third party clients.
- • "version": <version string>
- version number of the client.
- • "platform": ["Lin" | "Mac" | "Win"]
- the platform of the client.
- • "mac": <MAC Address>
- the MAC address associated with the client's computer.
- • "options": [optional_login]
- optional array of character strings. (See Optional Parameters below)
- • "id0": "00000000-0000-0000-0000-000000000000"
- hardware hash (based on the serial number of the first hard drive in Windows) used for uniquely identifying computers.
- • "agree_to_tos": ["true" | "false" | ""]
- whether or not the user has agreed to the Terms of Service.
- • "read_critical": ["true" | "false" | ""]
- whether or not the user has read important messages such as Terms of Service updates.
- • "viewer_digest": "00000000-0000-0000-0000-000000000000"
- MD5 hash of the viewer executable, only relevant when the channel is set to an official Second Life viewer.
Optional Parameters
Zero or more of the following character strings may appear in any order in the options array:
- [ "inventory-root" | "inventory-skeleton" | "inventory-lib-root" |
- "inventory-lib-owner" | "inventory-skel-lib" | "gestures" | "event_categories" |
- "event_notifications" | "classified_categories" | "buddy_list" | "ui-config" |
- "login-flags" | "global-textures" ]
See Optional Response for descriptions of information returned from these options
Response
The valid (non-error) value returned by the login call is in standard xmlrpc name, value format. The most important of these is the "Login Seed-Capability" discussed below (not to be confused with the new "seed capability" for the new login procedure):
- Note: all return values are in "name: value" format as used in Python 2.5 dictionaries unless otherwise noted.
- Note: A complete dump of return values was moved to another page for clarity.
Required Response
- last_name
- last name of avatar--identical to name given in input parameters
- { 'last_name':<last_name>}
- sim_ip
- ip address of starting sim
- { 'sim_ip':<ip_num> }
- • start_location: last
- • seconds_since_epoch: 1195447316
- • message: -=- http://blog.secondlife.com -=- Visit the Official Linden Blog for the latest world status updates!
- • first_name: first_name
- • circuit_code: 245160577
- • sim_port: 13005
- • secure_session_id: fdb501ca-22f1-4470-b515-2650f54b8117
- • look_at: [r-0.85717299999999996274,r0.51502899999999995906,r0]
- • agent_id: d5f403c7-7981-425d-a0b5-c65a3d0a4693
- • inventory_host: inv12-mysql
- • region_y: 244992
- • region_x: 247808
- • seed_capability: https://sim2054.agni.lindenlab.com:12043/cap/d373fdc9-d275-e484-3ad2-4a9b231f4e34
- • agent_access: M
- • session_id: 65a7213a-723a-4fcf-baca-7b247c4b43c5
- • login: true
Optional Response
- inventory-root
- UUID of the agent’s root inventory folder.
- { 'inventory-root': [{'folder_id': <uuid>}] }
- inventory-skeleton
- Initial list of folders in agent’s inventory. Returned as an array of five-entry dictionaries. Each dictionary element describes a folder with its name, version, type, its UUID, and the UUID of the containing folder.
- {'inventory-skeleton': [{'parent_id': <uuid>, 'version': <int>, 'name': <name>, 'type_default': <int>, 'folder_id': <uuid>}, .... ]}
- inventory-lib-root
- folder_id of library root inventory folder.
- { 'inventory-lib-root': [{'folder_id': <uuid>}] }
- inventory-lib-owner
- agent_id of owner for inventory lib. Note: Not the same as the agent_id returned in required parameters section
- { 'inventory-lib-owner': [{'agent_id': <uuid>}] }
- inventory-skel-lib
- Initial list of folders in agent’s inventory. Returned as an array of five element dictionaires. Each dictionary describes a folder with its name, its UUID, the UUID of the containing folder, its type, its version.
- {'inventory-skeleton': [{'parent_id': <uuid>, 'version': <int>, 'name': <name>, 'type_default': <int>, 'folder_id': <uuid>},... ]}
- gestures
- List of active gestures. An array of two element dictionaries with the inventory item uuid and the asset uuid.
- { 'gestures': [{'item_id': <uuid>, 'asset_id': <uuid>},...] }
- event_categories
- List of different event categories, mapping category id (an integer) to a category name. Returned as an array of two element dictionaries. Each dictionary describes a category’s id and it’s name.
- { 'event_categories': [{'category_id': <int>, 'category_name': <name>},...] }
- event_notifications
- List of events for which the agent has pending notifications. An array of eight-element dictionaries containing: event_id, event_name, event_desc, event_date, grid_x, grid_y, x_region, y_region.
- {'events': [{"event_id":<uuid>, "event_name"<name>,"event_desc":<string>, "event_date":<date>, "grid_x":<float>, "grid_y":<float>, "x_region":<float>, "y_region":<float>}, ...]}
- classified_categories"
- List of classifieds categories, mapping category id (an integer) to a category. Returned as an array of two element dictionaries with a category’s id and it’s name.
- { 'event_categories': [{'category_id': <int>, 'category_name': <name>},...] }
- buddy-list
- List of friends with granted and given rights masks. Returned as an array of three-element dictionaries with riend’s agent id, granted rights mask, given rights mask.
- { 'buddy-list':[{'buddy_id': <uuid>', 'buddy_rights_given': <int>, 'buddy_rights_has': <int>}, ....] }
- ui-config
- list of UI enabled/disabled states, currently: allow_first_life ('Y' or 'N') for teens.
- { 'ui-config': {'allow_first_life': if allow first life} }
- login-flags
- Several flags about the state of the agent.
- { 'login-flags': {'stipend_since_login': <'Y'|'N'>, 'ever_logged_in': <'Y'|'N'>, 'gendered': <'Y'|'N'>, 'daylight_savings': <'Y'|'N'>} }
- global-textures
- The asset ids of several global textures.
- { 'global-textures': {'sun_texture_id': <uuid>, 'moon_texture_id': <uuid>, 'cloud_texture_id': <uuid>} }
Login Seed-Capability
The current Login Seed-Capability is a Capability associated with the login sim. It should not be confused with the Seed-Capability proposed for the new protocols.
See Current Sim Capabilities for more info.
External Links
[1] -- libsl login page, includes sample code.