The TeamSpeak 3 user management and permission system
=====================================================

Copyright (c) 2009 TeamSpeak Systems GmbH

(1) TeamSpeak 3 server user management
--------------------------------------

The mechanism controlling user permissions on a TeamSpeak 3 server is fundamentally different than in TeamSpeak 2.
In TeamSpeak 2 individual users were added to the servers database and permissions bound to a user login name and
password. In TeamSpeak 3 user login names and passwords no longer exist. Instead users connect to a virtual server providing
just a nickname, which is only used for how to display the user to others but in no way related to access control.
To indentify a user on a TeamSpeak 3 virtual server, a public key encryption mechanism is used: 
When the Client is started for the first time, it automatically creates a key pair consisting of a public and a private key.
The first time a new user connects to a virtual server, his client will automatically send his public key to the server.
The virtual server creates an unique identifier from this public key and stores this identifier in its database. So
instead of identification with login and password, a TeamSpeak 3 server identifies users by their unique ID.
Should the user delete his private key and create a new one when connecting, he will be treated as a new individual by the
server.

Since there is no input needed to "register" on a TeamSpeak 3 server there is no such thing as a manual registration in TeamSpeak 3.
Basically once you connect you are automatically registered on the server you connected to. When you join again the server will
recognize you.

(2) TeamSpeak 3 permission overview
-----------------------------------

All settings that you can apply to a client on the server side are stored in reference to the clients unique ID.
This way, when the client reconnects to the server maybe using a new IP, a new nickname the server can still recoginize it
by the unique ID, and apply these settings. One of the more important settings you can apply to clients is of course
to grant or revoke certain permissions to them.
Clients joining for the first time will automatically become a member of the default Server Permissions Group that is configured via
the server settings - also clients that join a channel they have not visited before will automatically be inserted into
the Default Channel Permission Group (also configured via the server settings). Usually you will also be some kind of administrator
group that allows you to configure the server in the way you like it when you are a member of this group. The default group
layout contains a "Server Admin" group for this purpose.

#When a new virtual
#server is created, the servers global template groups are copied to the virtual servers server default
#and admin group, so modifying the templates is a good way to setup a security and access policy for
#multiple virtual servers without the need to modify each virtual servers permissions individually, although
#this can still be done to tweak individual virtual servers if required. 

(3) The chicken and the egg, or how to use privilege keys
---------------------------------------------------

One obvious problem that presents it self is the following: How does the first client receive elevated permissions
when there is no other client with elevated permissions yet that could grant these permissions? The solution for this
problem is through permission keys, that will now be explained:
A permission key is similar to a client with administrator privileges that adds you to a certain permission group, but without
the necessity of a such a client with administrator privileges to actually exist. It is a long (random looking) string that
can be used as a ticket into a specific server group.

As an example I am a server hoster and a client has just purchased a server. I send this client a privilege keyn that, once it is
used on the clients server, will grant the client that used it administrative powers. Or, in a different use case I might
be a server administrator and I want three of my friends to become members of the clan managment permission group. Since these
friends are not currently connected to my server and I don't have them stored in my buddy list I can't add them directly into
these groups, since I don't know how to tell the server who they are. So, I generate three privilege keys that each promote the
client that uses it into the server managment group. Then I send these privilege keys to my friends, and they can go ahead and
promote themselves when they are online again.

(4) Step by step: Becoming Administrator on your own server using a privilege key
------------------------------------------------------------------------

Since you will usually need at least one privilege key to grant administrative privileges after creating a new virtual server
this task is automatically taken care of uppon creation, the output would look like the following example:

------------------------------------------------------------------
                      I M P O R T A N T
------------------------------------------------------------------
     ServerAdmin privilege key created, please use it to gain
     serveradmin rights for your virtualserver. please
     also check the doc/privilegekey_guide.txt for details.

	 token=gOuRFCa5iM1iC+6GPFaeqiZXJoJrV04+tV0meuE9
------------------------------------------------------------------


Now the server owner would connect using the TeamSpeak 3 client with his still restricted permissions. The
client offers a dialog to copy&paste above privilege key. If the privilege key is correct and has not yet
been used, the user will be elevated and gain administrator permissions by joining the Server Admin
permission group.
A privilege key can only be used once, attempting to use it a second time will result in an error. The
privilege key is only valid for the virtual server which it was created for - other virtual servers running
within the same server process are not affected.

The usual procedure to create a new virtual server is:
* Create the virtual server
* Copy the privilege key from the server log
* Start the client and connect to the new virtual server, automatically creating a new unique user ID
* Paste the privilege key into the clients privilege key dialog

(5) Gaining global ServerQuery administrator permissions
--------------------------------------------------------

In addition to the privilege key mechanism, which grants administrator permissions for individual
users on virtual servers, server owners can gain administrative powers using a global ServerQuery
login.
In contrary to the user management system using unique IDs, ServerQuery connections have to
provide a login name and password.

When a server process starts for the first time, a password for a global ServerQuery
super-admin account is created and printed to the server console output.

The output might look like this:

------------------------------------------------------------------
                      I M P O R T A N T                           
 ------------------------------------------------------------------
       Server Query Admin Acccount created                 
       loginname= "serveradmin", password= "ifSsSm8w"           
------------------------------------------------------------------

Using the provided login name and password, the server administrator can connect to the
ServerQuery interface and login using the "login" command.
The ServerQuery admin account password should be protected carefully, as this grants complete
control over all virtual servers running within the server process.

