This piece of documentation is quite old. Please help review it!
This document briefly describes the connection process of a client to a shard running a NeL-based system.
The login_system sample and snowballs2 use a simple login_system that doesn't require web server.
Here is the steps:
FOLLOWING IS OUT OF DATE
Here it is a picture that displays different system with interaction between them:
The FS detects the disconnection of a client, sends a message to the WS that is forward to the LS. Then, the LS updates the NeL database setting the user offline.
The configuration parameters are in the nel_launcher.cfg.
The startup url is composed using this rule: http://<StartupHost><StartupPage>
For example if StartupHost is "itsalive.nevrax.org" and StartupPage is "/login/welcome.php", the resulting url will be "http://itsalive.nevrax.org/login/welcome.php",
The configuration parameters are in the login_service.cfg.
The configuration parameters are in the welcome_service.cfg.
The Database name is "nel" by default. It contains 2 tables; "shard" and "user".
shard table
user table
Whenever a shard starts, the WS establishes a permanent link with the LS. A validation on the LS will done to check that the shard is authorized to work on this login system using the WS IP and the ShardId.
outofdate If the LS detects that a person is trying to connect to an account that is already on use by another person, then the 2 people will be disconnected. The goal is to discourage people from sharing their accounts and also to avoid account deadlock in the case of bug. If for an obscure reason the user state in the LS is bad, then the next time the user tries to connect, they will be disconnected and their account will be reseted to the offline state and the user will be able to retry with a normal state.
A cookie is a class (CLoginCookie in login_cookie.cpp) that contains the web server's IP (uint32) as seen by the LS (to avoid address translation problems) for validation, a unique key (uint32) and the user id (uint32).
This document is deprecated.
This document briefly describes the connection process of a client to a shard running a NeL-based system.
Sxx
is the step number, you can search the code for this step is coded.
S01: In function CLoginClient::authenticate()
in login_client.cpp
.
The client initiates a connection to the LS, using the supplied IP and port from the configuration file, with the help of the DNS for IP resolution.
DNS spoofing or configuration file modification can lead to LS spoofing and hacking of the login/password information of the client. However, DNS is needed for flexibility of the login service location. It would be possible to supply the client with a range of valid IP address for the LS, and for the client to test the DNS' response against this range, in order to thwart this.
S02: In function CLoginClient::authenticate()
in login_client.cpp
.
The client sends "VLP" message with login (string
), password (\p string), client version (\p uint32) and system capabilities (4 \p string) to the LS.
S03: In function \p cbClientVerifyLoginPassword in \p connection_client.cpp of the LS.
The LS receives "VLP" message from the client and checks the client login/password validity.
The LS also generates a single-use cookie to validate the incoming connection with this client.
If something fails, the LS sends "VLP" message to the client with the reason why it failed and it
disconnects the client.
If everything succees, the LS builds a list of all available shards according to account information and current system settings. This list contains shards names (\p string) and the IP (in string format) for the WS of that shard. It sends "VLP" message to client with this list.
S04: In function \p cbVerifyLoginPassword in \p login_client.cpp.
The client receives "VLP" message from LS and handles the result.
S05: In function \p CLoginClient::connectToShard() in \p login_client.cpp.
The user selected the shard it wants to login to, and the client sends "CS" message with the IP address of its WS (in string format) to the LS.
S06: In function \p cbClientChooseShard() in \p connection_client.cpp of the LS.
The LS receives the "CS" message from client.
If something goes wrong, the LS sends a "SCS" message to the client with the reason for the problem and disconnects the client.
In a normal case, The LS sends "CS" message to the selected WS of the client's connection desires with the cookie generated in the step S03 (CLoginCookie).
S07: In function \p cbLSChooseShard() in \p welcome_service.cpp of the WS.
The WS receives the "CS" message from LS. The WS selects a FES to accept the client connexion, and sends "CS" message with the cookie to the selected FES.
If something goes wrong, the LS sends a "SCS" message to the LS with the reason for the problem.
S08: In function \p cbWSChooseShard in \p login_server.cpp.
The FES checks its capacity to accept the client. It stores the cookie and sends a "SCS" message to the WS with reason why it failed with it failed or with the cookie and the listen address (\p string) where the client will try to connect.
S09: In function \p cbFESShardChooseShard() in \p welcome_service.cpp of the WS.
The WS receives the "SCS" message from FES and sends it to the LS.
S10: In function \p cbWSShardChooseShard() in \p connection_ws.cpp of the LS.
The LS receives "SCS" message from WS and sends "SCS" message to the client and disconnects the client connection.
S11: In function \p cbShardChooseShard() in \p login_client.cpp.
The client receives "SCS" message from LS and handles it.
S12: In function \p CLoginClient::connectToShard() in \p login_client.cpp.
The client initiates a connection to the indicated FES and sends "SV" message to the FES with the submitted cookie.
S13: In function \p cbShardValidation in \p login_server.cpp.
The FES receives the cookie from the client. It checks if the cookie is good.
The FES sends "SV" message to the client to say if it accepts the client.
If the check failed, the "SV" message contains the reason (\p string) explains what goes wrong and the FES disconnects the client.
Otherwise, the "SV" message contains an empty string. In this case, the FES also sends a "CC" message to the WS with the userid (\p uint32) and an \p uint8 saying that the client is connected.
S14: In function \p cbShardValidate() in \p login_client.cpp.
The client receives "SV" message saying whether all is ok or not.
S15: In function cbFESClientConnected()
in welcome_service.cpp
of the WS.
The WS receives "CC" message from FES and sends "CC" message to the LS
S16: In function cbWSClientConnected()
in connection_ws.cpp
of the LS.
The LS receives "CC" message from WS and handles the message. The LS is now able to see whether the same account is being used to connects 2 different people and know exactly how many people are on each shard.
It's similar to steps S13 to S16. The FES receives the disconnection of a client. It sends "CC" message to the WS with the userid (\p uint32) and an \p uint8 to 0 saying that the client is disconnected. The WS receives the message and sends the same message to the LS. The LS receives the message and handles it.
Whenever a shard starts, the WS establishes a permanent link with the LS, using an encrypted link (it is assumed that the LS and WS are located on two physically and probably geographically distinct networks). A "SHARD" message serves as authentification, and the WS then updates the LS with its state, name and IP address. The LS may have a list of valid IP/port addresses for WS to avoid the occasional pirate server registration.
If the LS detects that a person is trying to connect to an account that is already on use by another person, then the 2 people will be disconnected. The goal is to discourage people from sharing their accounts and also to avoid account deadlock in the case of bug. If for an obscur reason the user state in the LS is bad, then the next time the user tries to connect, they will be disconnected and their account will be reseted to the offline state and the user will be able to retry with a normal state.
A cookie is a class (CLoginCookie
in login_cookie.cpp
) that contains the client's IP (uint32
) as seen by the LS (to avoid address translation problems) for validation, a unique key (uint32
) and the user id (\p uint32).
An account is a class that contains information about a physical person like their visa card number and their userid.
A *userid *is an unique number associated to an account for life.