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 tokens
---------------------------------------------------

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 tokens, that will now be explained:
A token 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 token 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 connect 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 tokens that each promote the client to
use it into the server managment group. Then I send these tokens 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 tokens
------------------------------------------------------------------------

Since you will usually need at least one token 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:

--------------------------------------------------------
ServerAdmin token created, please use the line below
TPyeBvpmrDbGVnhgg3ME1bAY7SLqYJB0KkTCHzf3
--------------------------------------------------------

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 token. If the token 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 token can only be used once, attempting to use it a second time will result in an error. The token is
only valid for the virtual server which has created the token. Other virtual servers running within the
same server process are not affected by a token.

The regular precedure of a servers administrator when creating a new virtual server would be:

* Create the virtual server
* Copy the token from the server log
* Start the client and connect to the new virtual server, automatically creating a new unique user ID
* Paste the token into the clients token dialog (use the 'T' key in the console client)

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

In addition to the token 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:

------------------------------------------------------------------
              Server Query Admin Acccount created
         loginname= "serveradmin", password= "BAIPwM8X"
------------------------------------------------------------------

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

