185 lines
7.6 KiB
Plaintext
185 lines
7.6 KiB
Plaintext
|
|
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 the hmackeys. For example, for the user "gorst", realm "north.gov"
|
|
and password "hero", there must be key "turn/realm/north.gov/user/gorst/key"
|
|
with value "7da2270ccfa49786e0115366d3a3d14d". Alternatively, the password
|
|
may be stored in clear text format. Then the key will be
|
|
"turn/realm/north.gov/user/gorst/password" and the key will be simply "hero".
|
|
|
|
2) For the short-term credentials, the passwords are stored always in
|
|
clear text format, with no realm name (because the short-term credentials
|
|
are not bound to a realm). So, there will be key "turn/user/gorst/password"
|
|
and the value will be "hero".
|
|
|
|
3) 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.
|
|
|
|
4) 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.
|
|
|
|
5) 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");
|
|
The ikm_key is not needed if the as_rs_key and auth_key are defined
|
|
explicitly in the database;
|
|
|
|
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.
|
|
|
|
hkdf_hash_func - (optional) hash function for HKDF procedure; the
|
|
valid values are SHA-1 and SHA-256, with SHA-256 as default;
|
|
The hkdf_hash_func is not needed if the as_rs_key and auth_key
|
|
are defined explicitly in the database;
|
|
|
|
as_rs_alg - oAuth token encryption algorithm; the valid values are
|
|
"AES-128-CBC" and "AES-256-CBC", , "AEAD-AES-128-GCM",
|
|
"AEAD-AES-256-GCM".
|
|
The default value is "AES-256-CBC";
|
|
|
|
as_rs_key - (optional) base64-encoded AS-RS key. If not defined, then
|
|
calculated with ikm_key and hkdf_hash_func. The as_rs_key length
|
|
is defined by as_rs_alg.
|
|
|
|
auth_alg - (optional) oAuth token authentication algorithm; the valid values are
|
|
"HMAC-SHA-256-128", "HMAC-SHA-256" and "HMAC-SHA-1".
|
|
The default value is "HMAC-SHA-256-128".
|
|
|
|
auth_key - (optional) base64-encoded AUTH key. If not defined, then
|
|
calculated with ikm_key and hkdf_hash_func. The auth_key length
|
|
is defined by auth_alg.
|
|
|
|
6) admin users (over https interface) are maintained as keys of form:
|
|
"turn/realm/<realm-name>/admin_user/<username>/password" with the password
|
|
values (for the per-relam admin users), or as keys of form:
|
|
"turn/admin_user/<username>/password" with password values - for the global
|
|
admin users.
|
|
|
|
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 through 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;
|
|
* short-term credentials mechanism, with open passwords;
|
|
* 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 "north" and key value "carleon".
|
|
* 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"
|
|
|
|
set turn/realm/north.gov/user/ninefingers/password "youhavetoberealistic"
|
|
set turn/realm/north.gov/user/gorst/password "hero"
|
|
set turn/realm/crinna.org/user/whirrun/password "sword"
|
|
set turn/realm/crinna.org/user/stranger-come-knocking/password "civilization"
|
|
|
|
sadd turn/realm/north.gov/secret "logen" "bloody9"
|
|
sadd turn/realm/crinna.org/secret "north" "library"
|
|
|
|
set turn/user/ninefingers/password "youhavetoberealistic"
|
|
set turn/user/gorst/password "hero"
|
|
set turn/user/whirrun/password "sword"
|
|
set turn/user/stranger-come-knocking/password "civilization"
|
|
|
|
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/north ikm_key 'Y2FybGVvbg==' hkdf_hash_func 'SHA-256' as_rs_alg 'AES-128-CBC' auth_alg 'HMAC-SHA-256-128'
|
|
hmset turn/oauth/kid/oldempire ikm_key 'YXVsY3Vz' hkdf_hash_func 'SHA-256' as_rs_alg 'AEAD-AES-256-GCM'
|
|
|
|
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
|
|
..........
|
|
|
|
|