coturn/turndb/schema.userdb.redis

I. The database

Redis database for user authentication and peer permissions 
has the following schema:

1) For the long-term credentials there must be keys 
"turn/realm/<realm-name>/user/<username>/key" and the values must be 
the hmackeys which is an md5 hash of "<username>:<realm-name>:<password>"
(See STUN RFC: https://tools.ietf.org/html/rfc5389#page-35).
For example, for the user "gorst", realm "north.gov" 
and password "hero", there must be key "turn/realm/north.gov/user/gorst/key" 
and the value should be md5 hash of "gorst:north.gov:hero"
which will result in "7da2270ccfa49786e0115366d3a3d14d".

2) For the shared secrets (REST API), several key/value pairs 
may be used (same as in SQL schema). The secrets are stored as members 
of an unordered set. The name of the set will be 
"turn/realm/<realm-name>/secret" and the value(s) will be the secret(s).
For example, if we have secrets "hero1", "hero2" and "hero3", 
then we will have set "turn/realm/north.gov/secret" with values
"hero1", "hero2" and "hero3". The turnserver will try to use the 
secrets in arbitrary order.

3) The "white" and "black" peer IP ranges are stored as unordered sets
of the following names:  
"turn/realm/<realm>/allowed-peer-ip" and
"turn/realm/<realm>/denied-peer-ip".

The meaning of the keys is the same as the meaning of allowed-peer-ip and
denied-peer-ip turnserver command-line option (with the addition of the realm option).
The only difference is that the turnserver option values are "static" 
(they remain the same for the lifetime of the turnserver process) but 
the database records can be dynamically changed 
and they will be almost immediately "seen" by the turnserver process.

4) For the oAuth authentication, there is a hash structure with the key 
"turn/oauth/kid/<kid-value>". The kid structure fields are:
 
	ikm_key - (optional) base64-encoded key ("input keying material").
		
	timestamp - (optional) the timestamp (in seconds) when the key 
		lifetime started.
	
	lifetime - (optional) the key lifetime in seconds; the default value 
		is 0 - unlimited lifetime.
		
	as_rs_alg - oAuth token encryption algorithm; the valid values are
		"A256GCM", "A128GCM" (see 
		http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40#section-5.1).
		The default value is "A256GCM".

	realm - optionally, a kid can be assigned to a realm that is different
		from the default realm.
		
5) admin users (over https interface) are maintained as keys of form:
"turn/admin_user/<username> with hash members "password" and,
optionally, "realm".

II. Extra realms data in the database

We can use more than one realm with the same instance of the TURN server.
This is done in two ways:

  1) through the third-party authentication option. An oAuth kid can be optionally
  assigned to a realm. When the user provides kid, and the database record
  for that kid contains a non-empty non-default realm, then the user is treated
  as belonging to that realm.
  2) the ORIGIN mechanism - users with different ORIGINS
  are placed into different realms. The database includes information about the
  relationships between the ORIGIN and realms, and about the extra realms
  database numbers.
	The relationship between ORIGIN and realm is set as keys of form:
	"turn/origin/<origin>" with the realm-names as the value. Many different
	ORIGIN keys may have the same realm. If the ORIGIN value is not found in 
	the database or the ORIGIN field is missed in the initial allocate 
	request, then the default realm is assumed.

III) Example of a Redis default user database setup.

This example sets user database for:

  * long-term credentials with hashed passwords and 
  	with default realm "north.gov";
  * long-term credentials with open passwords and 
  	with default realm "north.gov";
  * TURN REST API with shared secrets "logen", etc;
  * Black and white IP peer lists used.
  * Information how to match ORIGIN field with extra
    realms (if used). If no origin match found
    or the ORIGIN field is absent in the ALLOCATE request then the default 
    realm is used.
  * The realm performance parameters: "max_bps", 
  	"total_quota" and "user_quota" (same names as the turnserver 
  	configuration options, with the same meanings).
  * The oAuth data for the key with kid "oldempire" and key value
  "12345678901234567890123456789012", and default realm.
  * The admin user 'skarling', realm 'north.gov', with password 'hoodless';
  * The global admin user 'bayaz' with password 'magi';  
  
The shell command would be:

$ redis-cli <<!

SELECT 2
AUTH turn

set turn/realm/north.gov/user/ninefingers/key "bc807ee29df3c9ffa736523fb2c4e8ee"
set turn/realm/north.gov/user/gorst/key "7da2270ccfa49786e0115366d3a3d14d"
set turn/realm/crinna.org/user/whirrun/key "6972e85e51f36e53b0b61759c5a5219a"
set turn/realm/crinna.org/user/stranger-come-knocking/key "d43cb678560259a1839bff61c19de15e"

sadd turn/realm/north.gov/secret "logen" "bloody9"
sadd turn/realm/crinna.org/secret "north" "library"

set turn/realm/north.gov/max-bps 500000
set turn/realm/north.gov/total-quota 12000
set turn/realm/north.gov/user-quota 10000
set turn/realm/crinna.org/max-bps 400000
set turn/realm/crinna.org/total-quota 10000
set turn/realm/crinna.org/user-quota 8000

set turn/origin/http://crinna.org:80 crinna.org
set turn/origin/https://bligh.edu:443 crinna.org

sadd turn/realm/north.gov/allowed-peer-ip "172.17.13.200" "172.17.13.201"
sadd turn/realm/crinna.org/allowed-peer-ip "172.17.13.202"

sadd turn/realm/north.gov/denied-peer-ip "172.17.13.133-172.17.14.56" "172.17.17.133-172.17.19.56" "123::45"
sadd turn/realm/crinna.org/denied-peer-ip "123::77"

hmset turn/oauth/kid/oldempire ikm_key 'MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIK' as_rs_alg 'A256GCM'

hmset turn/admin_user/skarling realm 'north.gov' password 'hoodless'
hmset turn/admin_user/bayaz password 'magi'

save

!

IV. Redis database configuration parameters

TURN Server connects to the Redis and keeps the same connection during the 
TURN Server process lifetime. That means that we have to take care about that 
connection - it must not expire.

You have to take care about Redis connection parameters, the timeout and the 
keepalive. The following settings must be in your Redis config file
(/etc/redis.conf or /usr/local/etc/redis.conf):

..........
timeout 0
..........
tcp-keepalive 60
..........