UACCESS Protocol
- See also: HEUAccess
The UACCESS Protocol is the interface used between the FireStorm AUTHENTICATOR service and a remote Billing and authentication database. This is a server-side mechanism, and not forward facing. That is to say, it is an inter-process communication facility between servers behind the firewall.
Contents |
Connection Protocol
The connection protocol involves a listening port over which line-based text commands are sent and received. The end-of-line character is the UNIX style linefeed (decimal 10, \n) in both directions. Each parameter is separated by a tab character (decimal 9, \t) when both sending and receiving.
For example, to format an authenticate command for a user, the following code may suffice.
fprintf(socket, "%c\t%s\t%s\t%s\n", 'A', "TEST-USER", "PASSWORD", "198.168.1.100");
Commands
There are several commands supported. All arguments and responses for a command are separated by TAB (control_I, hex 09) characters. These are the ones that are implemented.
Authenticate
An authenticate command is defined as:
<Transaction ID> B <USERNAME> <PASSWORD> <INCOMING IP ADDRESS> <FEDERATED WORLD ID> <SERVICE NAME>
(Legacy) A USERNAME PASSWORD IP.ADD.RE.SS
Responses
<Transaction ID> B <USERNAME> KEY <KEY> <LEVEL> <USER NAME> <FEDERATED ACCOUNT ID> <EULA NEEDED>
(Legacy)A USERNAME NORECORD(no username found)
<Transaction ID> B USERNAME PASSWORD
(Legacy)A USERNAME PASSWORD
(username found, password wrong)
(Legacy)A USERNAME KEY ABC123 1 Full_Name
(success, key of ABC123, the default, user level 1, full name)
EULA Request
<Transaction ID> E <USERNAME> <FEDERATED WORLD ID> <FEDERATED ACCOUNT ID> <PRODUCT>
Responses
<Transaction ID> EULA USERNAME EULA URI(s)
Note* if there are no corresponding eulas, a blank string may be returned. It is not an error, and will be handled accordingly
User Authorizations
<Transaction ID> P R <
Check Subscription
The check subscription command is defined as:
<Transaction ID> S N <USERNAME> <SUBNAME>
(Legacy) S N USERNAME SUBNAME
Responses
The first parameter of each response will be the transaction id.
S USERNAME INTERNAL S USERNAME NO_SUBSCRIPTION S USERNAME SHAREWARE S USERNAME NEED_BILLING S USERNAME UNEXPECTED S USERNAME EXPIRED S USERNAME NO_ACCESS S USERNAME INTERNAL S USERNAME PAYING S USERNAME PREMIUM S USERNAME TRIAL S USERNAME BETA S USERNAME FREE S USERNAME NOT_YET_SET
S USERNAME ERROR:...
(error, non-user displayable reason code)
Get All Subscriptions on Account
<Transaction ID> S K USERNAME
(Legacy) S K USERNAME
Responses
<Transaction ID> S USERNAME [subname price_code expanded_sub_name]...
(Legacy) S USERNAME [subname 0 expanded_sub_name]...
- price_code - price codes are intended to communicate information from the account/billing system into the product so that game logic can make decisions about a user's status. It is not currently used by HeroEngine's processes.
Examples
Authenticate with success
SEND: "%c\t%s\t%s\t%s\n", 'A', "TEST-USER", "PASSWORD", "198.168.1.100" RECV: "A\tTEST-USER\tKEY\t9e107d9d372bb6826bd81d3542a419d6\t100\tTest User of HeroEngine\n"
Get Subscription List (ALL)
SEND: "%c\t%c\t%s\t%s\n", 'S', 'K', "TEST-USER", " " RECV: "S\tTEST-USER\tENGINE\t-4\tHeroEngine Licensee\tHE-DEV\t-1\tHeroEngine Development\n"
Get Subscription List (prefixed)
SEND: "%c\t%c\t%s\t%s\n", 'S', 'K', "TEST-USER", "HE" RECV: "S\tTEST-USER\tHE-DEV\t-1\tHeroEngine Development\n"
Get Subscription Status
SEND: "%c\t%c\t%s\t%s\n", 'S', 'N', "TEST-USER", "ENGINE" RECV: "S\tTEST-USER\tINTERNAL\n"
Get Subscription Status (failure)
SEND: "%c\t%c\t%s\t%s\n", 'S', 'N', "TEST-USER", "BADSUB" RECV: "S\tTEST-USER\tERROR: no data found\n"
