SceneID v0.90 specification file
================================

* 09.01.2007
  - v0.90
  - Verification keys are now being checked for duplicates

* 06.07.2006
  - v0.89
  - Support for SSL, certain operations are only possible
    with a valid certificate delivered by scene.org (portal class 1)

* 17.11.2005
  - v0.88
  - Fixes to user authentication
  - Added getFileInfo command for websites, portals and SceneID servers
    * experimental *

* 14.10.2005
  - v0.87
  - requestNewUserPassword returns the also the user login.
  - SceneID Library v0.3b / first beta for SceneID developers released

* 05.09.2005
  - v0.86
  - requestNewUserPassword returns the email address where we just
    sent the new user password.

* 31.08.2005
  - v0.85
  - registerUserMD5 and loginUserMD5 return now also user data
  - renewUserPassword and requestNewUserPassword also require now at least
    portalClass 3 (full website access)
  - added getPortalList command
  - changed returncode #99 into 'Internal error' - this should never
    be returned, but if it ever happens, it's means you've found a bug
    in SceneID and should report it to the admins.
  - SceneID Library v0.1b / first internal beta released

* 25.06.2005
  - v0.84
  - requestNewUserPassword takes now alternatively also user id, not just 
    user login as a parameter.

* 22.06.2005
  - v0.83
  - added portalClass check and automated a list of active SceneID portals:
    + portalClass 1 = SceneID server, full access and local user database
    + portalClass 2 = portal, full r/w access
    + portalClass 3 = website (default), full r/w access without registering users
    + portalClass 4 = minor website, read access only

* 22.06.2005
  - v0.82
  - loginUser, setUserInfo and registerUser commands deprecated.
  - SceneID version added to the beginning of the document, i.e.
    <sceneid version="x.y">

* 16.02.2005
  - v0.81
  - implemented loginUserMD5, setUserInfoMD5 and registerUserMD5 commands,
    which act just like the similar commands only difference being the
    user password is MD5 crypted, not cleartext. loginUser, setUserInfo
    and registerUser will get deprecated at some point during 2005 so
    please start using the MD5 versions instead!

* 03.01.2005
  - v0.80
  - added country information for the users
  - added optional external id for portals wanting to merge their existing 
    userbases into SceneID, giving externalid parameter to loginUser does
    the trick

* 17.10.2004
  - v0.79
  - changed xml encoding from iso-8859-1 to utf-8

* 24.08.2004
  - v0.78
  - split the password renewal into two separate commands:
    requestNewUserPassword and renewUserPassword

* 04.03.2004
  - v0.77
  - internal changes, added logging to all sceneid actions

* 29.02.2004
  - v0.76
  - portalLogin and portalPassword parameters are required now for every command.

* 03.02.2004
  - v0.75
  - added nickname and showinfo fields to user data.

* 04.01.2004
  - v0.73
  - removed <password/> tags from loginUser and getUserInfo command
    return values as portals don't need to know the user password.

* 03.01.2004
  - v0.72
  - added a check for user login name when registering. only charactes a-z,0-9,'-' 
    and '_' are valid, otherwise register command returns with an error code
  - in all commands: changed 'name' parameter to 'login' to prevent confusion

* 21.12.2003
  - v0.71
  - updated PHP session parameter requirements after successful loginUser

* 20.12.2003
  - v0.7
  - changed userAlias to userLogin, and xml tag <alias> to <login>
  - added IP and date logging to SceneID, userLogin requires now an IP address as
    an additional parameter

* 19.12.2003
  - v0.6
  - modified loginUser to return whole user info, not just userID

* 18.12.2003
  - v0.5
  - added setUserInfo command

* 17.12.2003
  - v0.4
  - added renewUserPassword command

* 15.12.2003
  - v0.3
  - added logoutUser command
  - changed one cookie to two - SCENEID_COOKIE for a permanent login and
    SCENEID_SESSION for a session long login
    
* 14.12.2003 
  - v0.2
  - revised the sceneid definition, added user birthdate
  - added loginUser command

* 20.07.2003
  - v0.1
  - initial version, getUserInfo and registerUser commands

Database design for the SceneID userbase:

+-----------------+------------------+------+-----+------------+----------------+
| Field           | Type             | Null | Key | Default    | Extra          |
+-----------------+------------------+------+-----+------------+----------------+
| userID          | int(10) unsigned |      | PRI | NULL       | auto_increment |
| userLogin       | varchar(32)      |      |     |            |                |
| userPassword    | varchar(255)     |      |     |            |                |
| userEmail       | varchar(128)     |      |     |            |                |
| userURL         | varchar(255)     | YES  |     | NULL       |                |
| userNickname    | varchar(32)      |      |     |            |                |
| userFirstname   | varchar(64)      |      |     |            |                |
| userLastname    | varchar(64)      |      |     |            |                |
| userBirthdate   | date             |      |     | 0000-00-00 |                |
| userCountry     | varchar(2)       |      |     |            |                |
| userShowinfo    | tinyint(1)       |      |     | 0          |                |
| userIP          | varchar(15)      |      |     |            |                |
| userCookie      | varchar(255)     | YES  |     | NULL       |                |
| userLastVisited | int(11)          |      |     | 0          |                |
| userVerified    | tinyint(1)       |      |     | 0          |                |
+-----------------+------------------+------+-----+------------+----------------+

All user information beyond this doesn't belong to the basic userbase
scheme but is considered as being portal related secondary information.
userCookie is a cookie key. Cookies are used for identifying users
by all portals using SceneID. If $SCENEID_COOKIE is set, portal can
query with getUserInfo and $SCENEID_COOKIE as a cookie parameter and
verify user is really logged in using SceneID. $SCENEID_SESSION is also
another cookie used for logins but user is logged out when closing
browser. userVerified is simple variable for preventing false / fake 
registrations, registered users should verify their account by accessing 
an url received in their registration email.

The current version of the SceneID entry-point is located here
(note that you have to use always port 8080 when accessing it):

  http://www.scene.org:8080/sceneid.php

The page takes parameters only in get, if you need post for any reason let
me know. Please note also that the SceneID XML tag names defined in the 
protocol are case-insensitive (however tag values can be case-sensitive!)

Currently the available commands:

- getUserInfo
- registerUserMD5
- loginUserMD5
- logoutUser
- setUserInfoMD5
- requestNewUserPassword
- renewUserPassword

All commands have always two mandatory parameters:
- portalLogin (your personal login)
- portalPassword (your personal password as md5 hash)

If you're using a test version of SceneID (http://test.scene.org:8080/sceneid.php)
you can use login "test" and password "test" (no md5 hashing needed).

In detail:

command: getUserInfo
parameters: userID, login or cookie value
explanation: with return value 10 (user data fetched succesfully)
             you'll get also user data (see below).

example input 1: http://www.scene.org:8080/sceneid.php?portalLogin=test&portalPassword=test&command=getUserInfo&userID=38
example output 1:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<sceneid>
  <returnvalue id="10">User data fetched succesfully</returnvalue>
  <user id="38">
    <login>melwyn</login>
    <nickname>melw</firstname>
    <firstname>Matti</firstname>
    <lastname>Palosuo</lastname>
    <email hidden="yes">melwyn@scene.org</email>
    <url>http://www.veljeskunta.org/melwyn/</url>
    <birthdate>0000-00-00</birthdate>
    <country id="FI">Finland</country>
  </user>
  <external>
  	<portal id="6" externalid="1">Slengpung</portal>
  </external>
</sceneid>

example input 2: http://www.scene.org:8080/sceneid.php?portalLogin=test&portalPassword=test&command=getUserInfo&login=analogue
example output 2:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<sceneid>
  <returnvalue id="10">User data fetched succesfully</returnvalue>
  <user id="1">
    <login>analogue</login>
    <nickname>analogue</nickname>
    <firstname>Laurent</firstname>
    <lastname>Raufaste</lastname>
    <email>analogue@glop.org</email>
    <url>http://www.glop.org/</url>
    <birthdate>0000-00-00</birthdate>
    <country id="FR">France</country>
  </user>
  <external>
  	<portal id="6" externalid="487">Slengpung</portal>
  </external>
</sceneid>

example input 3: http://www.scene.org:8080/sceneid.php?portalLogin=test&portalPassword=test&command=getUserInfo&cookie=21c514149be65f8e99e7d72d2f082659
example output 3:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<sceneid>
  <returnvalue id="10">User data fetched succesfully</returnvalue>
  <user id="38">
    <login>melwyn</login>
    <nickname>melw</nickname>
    <firstname>Matti</firstname>
    <lastname>Palosuo</lastname>
    <email hidden="yes">melwyn@scene.org</email>
    <url>http://www.veljeskunta.org/melwyn/</url>
    <birthdate>0000-00-00</birthdate>
    <country id="FI">Finland</country>
  </user>
  <external>
  	<portal id="6" externalid="1">Slengpung</portal>
  </external>
</sceneid>


command: loginUserMD5
parameters: login (mandatory)
            password (mandatory, MD5 crypted)
            ip (mandatory)
            permanent (set this on if you want to set up a permanent login)
            externalid (optional external id if you want to inform SceneID about 
                        your own portals userid for cross-linking purposes)
explanation: with correct login you'll get returnvalue 30 (user logged
             in succesfully), user data and cookie you should set up immediately.
             Cookie name is SCENEID_COOKIE for permanent logins and SCENEID_SESSION
             for session based logins (logout automatically when browser is closed).
             you should set up also the following session parameters:
             $_SESSION["SCENEID"] = session_id();
             $_SESSION["SCENEID_ID"] = from <user id=...>
             $_SESSION["SCENEID_LOGIN"] = from <user><login>...</login></user>
             $_SESSION["SCENEID_IP"] = $_SERVER["REMOTE_ADDR"];

example input: http://www.scene.org:8080/sceneid.php?portalLogin=test&portalPassword=test&command=loginUser&login=test123&password=cc03e747a6afbbcbf8be7668acfebee5&ip=127.0.0.1&permanent=1
example output:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<sceneid>
  <returnvalue id="30">User logged in succesfully</returnvalue>
  <user id="38">
    <login>melwyn</login> 
    <firstname>Matti</firstname> 
    <lastname>Palosuo</lastname> 
    <email>mpalosuo@cs.helsinki.fi</email> 
    <url>http://www.veljeskunta.org/melwyn/</url> 
    <birthdate>1979-11-17</birthdate> 
    <country id="FI">Finland</country>
    <verified>1</verified> 
  </user>
  <external>
  	<portal id="6" externalid="1">Slengpung</portal>
  </external>
  <cookie>
    <name>SCENEID_COOKIE</name>
    <value>62d21009241f07455ea677c68145bcab</value>
    <expires>1102960691</expires>
    <path>/</path>
    <domain>scene.org</domain>
    <secure>0</secure>
  </cookie>
</sceneid>


command: logoutUser
parameters: userID, login or cookie value
explanation: logs out the user from SceneID system. With successful logout
             returns value 40 and logged out userID. You should also unset
             SCENEID_COOKIE and SCENEID_SESSION immediately after calling this 
             command.

example input 1: http://www.scene.org:8080/sceneid.php?portalLogin=test&portalPassword=test&command=logoutUser&userID=38
example output 1:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<sceneid>
  <returnvalue id="40">User logged out succesfully</returnvalue>
  <user id="38"/>
</sceneid>

example input 2: http://www.scene.org:8080/sceneid.php?portalLogin=test&portalPassword=test&command=logoutUser&login=melwyn
example output 2:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<sceneid>
  <returnvalue id="40">User logged out succesfully</returnvalue>
  <user id="38"/>
</sceneid>

example input 3: http://www.scene.org:8080/sceneid.php?portalLogin=test&portalPassword=test&command=logoutUser&cookie=21c514149be65f8e99e7d72d2f082659
example output 3:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<sceneid>
  <returnvalue id="40">User logged out succesfully</returnvalue>
  <user id="38"/>
</sceneid>


command: registerUserMD5
parameters: login (mandatory)
            nickname
            firstname
            lastname
            email (mandatory)
            url
            birthdate (in 'yyyy-mm-dd' format)
            country (in ISO 3166 code such as 'FI' or 'FR')
            password (mandatory, MD5 crypted)
            password2 (mandatory, MD5 crypted)
            showinfo
explanation: registers a user. if registration succeeded (return value 20)
             you'll get back also an user id for the newly registered user

example input: http://www.scene.org:8080/sceneid.php?portalLogin=test&portalPassword=test&command=registerUser&login=test123&email=melwyn@scene.org&password=cc03e747a6afbbcbf8be7668acfebee5&password2=cc03e747a6afbbcbf8be7668acfebee5
example output:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<sceneid>
  <returnvalue id="20">User registered succesfully</returnvalue>
  <user id="8124"/>
</sceneid>


command: setUserInfoMD5
parameters: userID (mandatory)
            nickname
            firstname
            lastname
            email
            url
            birthdate (in 'yyyy-mm-dd' format)
            country (in ISO 3166 code such as 'FI' or 'FR')
            password (MD5 crypted)
            password2 (mandatory if password is given, MD5 crypted)
            showinfo
explanation: with success returns value 50 (user data updated succesfully).

example input: http://www.scene.org:8080/sceneid.php?portalLogin=test&portalPassword=test&command=setUserInfo&userID=38&email=mpalosuo@cs.helsinki.fi
example output:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<sceneid>
  <returnvalue id="50">User data updated succesfully</returnvalue>
  <user id="38"/>
</sceneid>


command: requestNewUserPassword
parameters: login (mandatory) OR userID (mandatory if no login is set)
explanation: requests for a new user password and sends a verification key to the
             user by email
             value 70 (user password renew request sent successfully).

example input: http://www.scene.org:8080/sceneid.php?portalLogin=test&portalPassword=test&command=requestNewUserPassword&login=melwyn
example output:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<sceneid>
  <returnvalue id="70">User password renew request sent successfully</returnvalue>
  <user id="38">
    <login>melwyn</login>
    <email hidden="yes">melwyn@scene.org</email>
  </user>
</sceneid>


command: renewUserPassword
parameters: key (mandatory)
explanation: renews user password and sends it back - in clear text!
             value 60 (user password renewed succesfully).

example input: http://www.scene.org:8080/sceneid.php?portalLogin=test&portalPassword=test&command=renewUserPassword&key=4CJuYAatv7vPdtWt3NazD4W
example output:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<sceneid>
  <returnvalue id="60">User password renewed succesfully</returnvalue>
  <user id="38">
    <password>aU24gHO1</password>
  </user>
</sceneid>

command: getPortalList
parameters: none
explanation: get list of all SceneID enabled websites, 
             with success returns a value 80.
             
example input: http://www.scene.org:8080/sceneid.php?portalLogin=test&portalPassword=test&command=getPortalList
example output:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<sceneid version="0.88">
	<returnvalue id="80">Portal list fetched succesfully</returnvalue>
	<portals>
		<portal id="1">
			<name>Scene.org</name>
			<url>http://www.scene.org/</url>
			<class id="1">sceneid server</class>
		</portal>
		<portal id="3">
			<name>MacScene</name>
			<url>http://mac.scene.org/</url>
			<class id="2">portal</class>
		</portal>
		<portal id="2">
			<name>Pouet.net</name>
			<url>http://www.pouet.net/</url>
			<class id="2">portal</class>
		</portal>
		<portal id="7">
			<name>Scene.org Awards</name>
			<url>http://awards.scene.org/</url>
			<class id="4">minor website</class>
		</portal>
	</portals>
</sceneid>


command: getFileInfo
parameters: fileID
explanation: get a file information hosted by Scene.org,
             with success returns a value 110.

example input: http://www.scene.org:8080/sceneid.php?portalLogin=test&portalPassword=test&command=getFileInfo&fileID=1
example output:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<sceneid version="0.88">
  <returnvalue id="110">File information fetched succesfully</returnvalue> 
  <file id="1">
    <filename>appform.txt</filename> 
    <path>/</path> 
    <size>26</size> 
    <date>0</date> 
    <downloads>16548</downloads> 
    <monthdownloads>296</monthdownloads> 
    <mirrors /> 
  </file>
</sceneid>


Full list of current return values (10-19 = get user data, 20-29 = register user, 
30-39 = login user, 40-49 = logout user, 50-59 = set user data, 
60-79 = user password renewal, 0-9 & 90-99 = general messages):

 0 => 'Command not defined',
10 => 'User data fetched succesfully',
11 => 'No userID, login or cookie parameter defined',
12 => 'User does not exist',
20 => 'User registered succesfully',
21 => 'User with same login exists already',
22 => 'User login not specified',
23 => 'User email not specified',
24 => 'Invalid email address',
25 => 'User password not specified',
26 => 'Verified password missing',
27 => 'User passwords do not match',
28 => 'Invalid password',
29 => 'Invalid login',
30 => 'User logged in succesfully',
31 => 'User login not specified',
32 => 'User does not exist',
33 => 'User password not specified',
34 => 'Invalid password',
35 => 'User is not verified',
36 => 'User IP address is missing',
40 => 'User logged out succesfully',
41 => 'User not found',
42 => 'No session found',
50 => 'User data updated succesfully',
51 => 'UserID not specified',
52 => 'User not found',
53 => 'Invalid email address',
54 => 'Verified password missing',
55 => 'User passwords do not match',
56 => 'Invalid password',
60 => 'User password renewed successfully',
61 => 'User not found with given verification key',
62 => 'Verification key not set!',
70 => 'User password renew request sent successfully',
71 => 'User not found',
72 => 'User email not set, cannot send new password request!',
90 => 'Access not granted (ip address: '.$_SERVER['REMOTE_ADDR'].')',
91 => 'Access not granted, wrong password (ip address: '.$_SERVER['REMOTE_ADDR'].')',
92 => 'Access not granted, insufficient access level for this command!',
99 => 'Empty message',
101 => 'setUserInfo is deprecated - use setUserInfoMD5 instead!',
102 => 'loginUser is deprecated - use loginUserMD5 instead!',
103 => 'registerUser is deprecated - use registerUserMD5 instead!',

You get 90 if you're accessing the page outside scene.org domain, if that
happens just tell us what ip address the error message shows and we'll add
access to the page.

How to implement this in your code? It's pretty simple. You can ask
Melwyn (melwyn@scene.org) for the latest SceneID library written in PHP.
The documentation unfortunately doesn't exist (besides this short specification),
but the library makes the development quite straight-forward. We do have also
developers mailing list available at sceneid@scene.org.