Security salts and hashes

As an optional security feature, the TeamSpeak SDK offers to restrict access of clients to specific channels by using a salt and hash mechanism. The motivation here is to enforce clients to use a specific identity, nickname and metadata when they connect to the TeamSpeak server.

In the server, a security salt is created over a clients unique data by calling ts3server_createSecuritySalt().

This salt is then attached to a channel during channel creation or by editing existing channels by setting the channel variable CHANNEL_SECURITY_SALT.

When a client attempts to enter such a channel, the clients CLIENT_SECURITY_HASH variable is checked against the clients data (unique id, optionally nickname and meta_data) using the salt. If the hash is not correct, the client is not allowed to enter the channel.

The clients hash value is calculated by the server using ts3server_calculateSecurityHash(). This security hash has to be transmitted to the client by ways outside of the TeamSpeak SDK. The client will set the hash in its CLIENT_SECURITY_HASH variable.

Creating a channel salt

unsigned int ts3server_createSecuritySalt(int options, void *salt, int saltByteSize, char **securitySalt)

Create a security salt to lock channel to identities. See the :ref:SDK Documentation<channel_security_salt> on the topic for more in depth explanation.

Parameters:

  • options – specifies which parameters to include in the security salt. A combination of values from the SecuritySaltOptions enum.

  • salt – pointer to random data of cryptographic quality.

  • saltByteSize – number of bytes of random data to use. Larger is better but slower.

  • securitySalt – address of a variable to receive the security salt. Memory is allocated by the server library and needs to be freed by caller using ts3server_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Creating a client hash

unsigned int ts3server_calculateSecurityHash(const char *securitySalt, const char *clientUniqueIdentifier, const char *clientNickName, const char *clientMetaData, char **securityHash)

create a hash for a specific client from a security salt to lock an identity to a channel. See the :ref:SDK Documentation<channel_security_salt> on the topic for more in depth explanation.

Parameters:

  • securitySalt – the security salt of a channel as generated by ts3server_createSecuritySalt

  • clientUniqueIdentifier – public identity of a client to generate a security hash for

  • clientNickName – nickname of the client to include in the hash if specified by the salt.

  • clientMetaData – meta data of the client to include in the hash if specified by the salt.

  • securityHash – address of a variable to receive the security hash. Memory is allocated by the server library and must be freed by caller using ts3server_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason