forked from coturn/coturn
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.turnutils
459 lines (262 loc) · 12.6 KB
/
README.turnutils
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
GENERAL INFORMATION
A set of turnutils_* programs provides some utility functionality to be used
for testing and for setting up the TURN server.
1. turnutils_uclient: emulates multiple UDP,TCP,TLS or DTLS clients.
(this program is provided for the testing purposes only !)
The compiled binary image of this program is located in bin/
sub-directory.
2. turnutils_peer: a simple stateless UDP-only "echo" server,
to be used as the final server in relay pattern ("peer"). For every incoming
UDP packet, it simply echoes it back.
(this program is provided for the testing purposes only !)
When the test clients are communicating in the client-to-client manner
(when the "turnutils_uclient" program is used with "-y" option) then the
turnutils_peer is not needed.
The compiled binary image of this program is located in bin/ subdirectory.
3. turnutils_stunclient: a simple STUN client example.
The compiled binary image of this program is located in bin/ subdirectory.
4. turnutils_rfc5769check: a utility that checks the correctness of the
STUN/TURN protocol implementation. This utility is used only for the compilation
check procedure, it is not copied to the installation destination.
In the "examples/scripts" subdirectory, you will find the examples of command lines to be used
to run the programs. The scripts are meant to be run from examples/ subdirectory, for example:
$ cd examples
$ ./scripts/secure_relay.sh
5. turnutils_natdiscovery: a utility that provides NAT behavior discovery
according RFC5780. This utility discovers the actual NAT Mapping and Filtering
behavior. Be aweare that at least two different listening IP addresses should
be configured to be able to work properly!
6. turnutils_oauth: a utility that provides OAuth access_token
generation(AEAD encryption), validation and decryption. This utility inputs
all the keys and lifetimes and any related information that needed for
creation and validationi of an access_token. It outputs a JSON with all OAuth
PoP parameters that need to pass to the client. Output is generated accoriding
RFC7635 Appendix B, Figure 8.
For more details, and for the access_token structure, read rfc7635, and see
script in examples/scripts/oauth.sh.
=====================================
NAME
turnutils_uclient - this client emulation application is supplied for the test purposes only.
SYNOPSIS
$ turnutils_uclient [-tTSvsyhcxg] [options] <TURN-Server-IP-address>
DESCRIPTION
It was designed to simulate multiple clients. It uses asynch IO API in
libevent to handle multiple clients. A client connects to the relay,
negotiates the session, and sends multiple (configured number) messages to the server (relay),
expecting the same number of replies. The length of the messages is configurable.
The message is an arbitrary octet stream.
The number of the messages to send is configurable.
Flags:
-t Use TCP for communications between client and TURN server (default is UDP).
-b Use SCTP for communications between client and TURN server (default is UDP).
-T Use TCP for the relay transport (default - UDP). Implies options -t, -y, -c,
and ignores flags and options -s, -e, -r and -g. Can be used together
with -b.
-P Passive TCP (RFC6062 with active peer). Implies -T.
-S Secure SSL connection: SSL/TLS for TCP, DTLS for UDP, TLS/SCTP for SCTP.
-U Secure unencrypted connection (suite eNULL): SSL/TLS for TCP, DTLS for UDP.
-v Verbose.
-s Use "Send" method in TURN; by default, it uses TURN Channels.
-y Use client-to-client connections:
RTP/RTCP pair of channels to another RTP/RTCP pair of channels.
with this option the turnutils_peer application is not used,
as the allocated relay endpoints are talking to each other.
-h Hang on indefinitely after the last sent packet.
-c Do not create rtcp connections.
-x Request IPv6 relay address (RFC6156).
-X IPv4 relay address explicitly requested.
-g Set DONT_FRAGMENT parameter in TURN requests.
-D Do mandatory channel padding even for UDP (like pjnath).
-N do negative tests (some limited cases only).
-R do negative protocol tests.
-O DOS attack mode.
-M Use TURN ICE Mobility.
-I Do not set permissions on TURN relay endpoints
(for testing the non-standard server relay functionality).
-G Generate extra requests (create permissions, channel bind).
-B Random disconnect after a few initial packets.
-Z Dual allocation (SSODA). Implies -c option.
-J Use oAuth with default test key kid='north'.
Options with required values:
-l Message length (Default: 100 Bytes).
-i Certificate file (for secure connections only, optional).
-k Private key file (for secure connections only).
-E CA file for server certificate verification,
if the server certificate to be verified.
-p TURN Server port (Defaults: 3478 unsecure, 5349 secure).
-n Number of messages to send (Default: 5).
-d Local interface device (optional, Linux only).
-L Local IP address (optional).
-m Number of clients (Default: 1, 2 or 4, depending on options).
-e Peer address.
-r Peer port (Default: 3480).
-z Per-session packet interval in milliseconds (Default: 20).
-u STUN/TURN user name.
-w STUN/TURN user password.
-W TURN REST API secret. The "plain text" secret e.g. "north"
that is stored in the value column of the turn_secret
table in the database if dynamic, or the static-auth-secret
value set in the configuration file if using static.
-C This is the timestamp/username separator symbol (character) in
TURN REST API. The default value is :.
-F Cipher suite for TLS/DTLS. Default value is DEFAULT.
-o the ORIGIN STUN attribute value.
-a Bandwidth for the bandwidth request in ALLOCATE. The default value is zero.
See the examples in the "examples/scripts" directory.
======================================
NAME
turnutils_peer - a simple UDP-only echo backend server.
SYNOPSIS
$ turnutils_peer [-v] [options]
DESCRIPTION
This application is used for the test purposes only, as a peer for the turnutils_uclient application.
Options with required values:
-p Listening UDP port (Default: 3480).
-d Listening interface device (optional)
-L Listening address of turnutils_peer server. Multiple listening addresses can be used, IPv4 and IPv6.
If no listener address(es) defined, then it listens on all IPv4 and IPv6 addresses.
-v Verbose
========================================
NAME
turnutils_stunclient - a basic STUN client.
SYNOPSIS
$ turnutils_stunclient [options] <STUN-Server-IP-address>
DESCRIPTION
It sends a "new" STUN RFC 5389 request (over UDP) and shows the reply information.
Options with required values:
-p STUN server port (Default: 3478).
-L Local address to use (optional).
-f Force RFC 5780 processing.
The turnutils_stunclient program checks the results of the first request,
and if it finds that the STUN server supports RFC 5780
(the binding response reveals that) then the turnutils_stunclient makes a couple more
requests with different parameters, to demonstrate the NAT discovery capabilities.
This utility does not support the "old" "classic" STUN protocol (RFC 3489).
=====================================
NAME
turnutils_rfc5769check - a utility that tests the correctness of STUN protocol implementation.
SYNOPSIS
$ turnutils_rfc5769check
DESCRIPTION
turnutils_rfc5769check tests the correctness of STUN protocol implementation
against the test vectors predefined in RFC 5769 and prints the results of the
tests on the screen. This utility is used only for the compilation
check procedure, it is not copied to the installation destination.
Usage:
$ turnutils_rfc5769check
=====================================
NAME
turnutils_natdiscovery - a utility that discovers NAT mapping and filtering
behavior according RFC5780.
SYNOPSIS
$ turnutils_natdiscovery [options] <STUN-Server-FQDN-or-IP-address>
DESCRIPTION
turnutils_natdiscovery discovers the NAT Mapping and Filtering behavior, to
determine if that NAT is currently using Endpoint-Independent,
Address-Dependent, or Address and Port-Dependent Mapping and/or to determine if
that NAT is currently using Endpoint-Independent, Address-Dependent, or Address
and Port-Dependent Filtering.
Use either -m and/or -f flag to discover NAT Mapping and/or Filtering.
Flags:
-m NAT mapping behavior discovery
-f NAT filtering behavior discovery
Options with required values:
-p STUN server port (Default: 3478)
-L Local address to use (optional)
Usage:
$ turnutils_natdiscovery -m -f stun.example.com
=====================================
NAME
turnutils_oauth - a utility that helps OAuth access_token generation/encryption and validation/decyption
SYNOPSIS
$ turnutils_oauth [options]
DESCRIPTION
turnutils_oauth utilitiy provides help in OAuth access_token encryption and/or
decryption with AEAD (Atuthenticated Encryption with Associated Data). It helps
for an Auth Server in access_token creation, and also for debuging purposes it
helps the access_token validation and decryption. This utility inputs all the
keys and lifetimes and any related information that are needed for encryption
or decryption of an access_token. It outputs a JSON with all OAuth PoP
parameters that need to pass to the client. Output is generated accoriding
RFC7635 Appendix B, Figure 8. This utility could help to build an Auth Server
service, but be awere that this utility does not generate "session key" /
"mac_key" and not verifies lifetime of "session key" / "mac_key" or "Auth key".
For more details, and for the access_token structure, read rfc7635, and see
the example in examples/scripts/oauth.sh.
Use either -e and/or -d flag to encrypt or decrypt access_token.
Flags:
-h, --help usage
-v, --verbose verbose mode
-e, --encrypt encrypt token
-d, --decrypt decrypt validate token
Options with required values:
-i, --server-name server name (max. 255 char)
-j, --auth-key-id Auth key id (max. 32 char)
-k, --auth-key base64 encoded Auth key
-l --auth-key-timestamp Auth key timestamp (sec since epoch)
-m, --auth-key-lifetime Auth key lifetime in sec
-n, --auth-key-as-rs-alg Authorization Server(AS) - Resource Server(RS) encryption algorithm
-o, --token-nonce base64 encoded nonce base64(12 octet) = 16 char
-p, --token-mac-key base64 encoded MAC key base64(32 octet) = 44 char
-q, --token-timestamp timestamp in format 64 bit unsigned (Native format - Unix),
so 48 bit for secs since epoch UTC + 16 bit for 1/64000 fractions of a second.
e.g.: the actual unixtimestamp 16 bit left shifted. (Default: actual gmtime)
-r, --token-lifetime lifetime in sec (Default: 3600)
-t, --token base64 encoded encrypted token for validation and decryption
-u, --hmac-alg stun client hmac algorithm
Usage:
$ turnutils_natdiscovery
===================================
DOCS
After installation, run the command:
$ man turnutils
or in the project root directory:
$ man -M man turnutils
to see the man page.
=====================================
FILES
/etc/turnserver.conf
/var/db/turndb
/usr/local/var/db/turndb
/var/lib/turn/turndb
/usr/local/etc/turnserver.conf
=================================
DIRECTORIES
/usr/local/share/turnserver
/usr/local/share/doc/turnserver
/usr/local/share/examples/turnserver
===================================
STANDARDS
new STUN RFC 5389
TURN RFC 5766
TURN-TCP extension RFC 6062
TURN IPv6 extension RFC 6156
STUN/TURN test vectors RFC 5769
STUN NAT behavior discovery RFC 5780
====================================
SEE ALSO
turnserver, turnadmin
======================================
WEB RESOURCES
project page:
https://github.com/coturn/coturn/
Wiki page:
https://github.com/coturn/coturn/wiki
forum:
https://groups.google.com/forum/?fromgroups=#!forum/turn-server-project-rfc5766-turn-server/
======================================
AUTHORS
Oleg Moskalenko <[email protected]>
Gabor Kovesdan http://kovesdan.org/
Daniel Pocock http://danielpocock.com/
John Selbie ([email protected])
Lee Sylvester <[email protected]>
Erik Johnston <[email protected]>
Roman Lisagor <[email protected]>
Vladimir Tsanev <[email protected]>
Po-sheng Lin <[email protected]>
Peter Dunkley <[email protected]>
Mutsutoshi Yoshimoto <[email protected]>
Federico Pinna <[email protected]>
Bradley T. Hughes <[email protected]>
Mihaly Meszaros <[email protected]>