modules: readme files regenerated - auth_ephemeral ...
[sip-router] / src / modules / auth_ephemeral / README
1 Auth_ephemeral Module
2
3 Peter Dunkley
4
5    Crocodile RCS Ltd
6    <peter.dunkley@crocodile-rcs.com>
7
8 Carsten Bock
9
10    ng-voice GmbH
11    <carsten@ng-voice.com>
12
13    Copyright © 2013 Crocodile RCS Ltd
14
15    Copyright © 2017 ng-voice GmbH
16      __________________________________________________________________
17
18    Table of Contents
19
20    1. Admin Guide
21
22         1. Overview
23
24               1.1. How ephemeral credentials work
25
26                     1.1.1. Request
27                     1.1.2. Response
28
29         2. Dependencies
30
31               2.1. Kamailio Modules
32               2.2. External Libraries or Applications
33
34         3. Parameters
35
36               3.1. secret (string)
37               3.2. username_format (integer)
38               3.3. sha_algorithm (integer)
39
40         4. Functions
41
42               4.1. autheph_proxy(realm)
43               4.2. autheph_www(realm[, method])
44               4.3. autheph_check(realm)
45               4.4. autheph_authenticate(username, password)
46               4.5. autheph_check_from([username])
47               4.6. autheph_check_to([username])
48               4.7. autheph_check_timestamp(username)
49
50         5. RPC Commands
51
52               5.1. autheph.add_secret
53               5.2. autheph.dump_secrets
54               5.3. autheph.rm_secret
55
56    List of Examples
57
58    1.1. Request example
59    1.2. Response example
60    1.3. secret parameter usage
61    1.4. username_format parameter usage
62    1.5. sha_algorithm parameter usage
63    1.6. autheph_proxy usage
64    1.7. autheph_www usage
65    1.8. autheph_check usage
66    1.9. autheph_authenticate usage
67    1.10. autheph_check_from usage
68    1.11. autheph_check_to usage
69    1.12. autheph_check_timestamp usage
70
71 Chapter 1. Admin Guide
72
73    Table of Contents
74
75    1. Overview
76
77         1.1. How ephemeral credentials work
78
79               1.1.1. Request
80               1.1.2. Response
81
82    2. Dependencies
83
84         2.1. Kamailio Modules
85         2.2. External Libraries or Applications
86
87    3. Parameters
88
89         3.1. secret (string)
90         3.2. username_format (integer)
91         3.3. sha_algorithm (integer)
92
93    4. Functions
94
95         4.1. autheph_proxy(realm)
96         4.2. autheph_www(realm[, method])
97         4.3. autheph_check(realm)
98         4.4. autheph_authenticate(username, password)
99         4.5. autheph_check_from([username])
100         4.6. autheph_check_to([username])
101         4.7. autheph_check_timestamp(username)
102
103    5. RPC Commands
104
105         5.1. autheph.add_secret
106         5.2. autheph.dump_secrets
107         5.3. autheph.rm_secret
108
109 1. Overview
110
111    1.1. How ephemeral credentials work
112
113         1.1.1. Request
114         1.1.2. Response
115
116    This module contains all authentication related functions that can work
117    with ephemeral credentials. This module can be used together with the
118    auth module for digest authentication. Use this module if you want to
119    use ephemeral credentials instead of ordinary usernames and passwords.
120
121 1.1. How ephemeral credentials work
122
123    Ephemeral credentials are generated by a web-service and enforced on
124    Kamailio. This use of ephemeral credentials ensures that access to
125    Kamailio is controlled even if the credentials cannot be kept secret,
126    as can be the case in WebRTC where the credentials may be specified in
127    Javascript.
128
129    The only interaction needed between the web-service and Kamailio is to
130    share a secret key.
131
132    Credentials will typically be requested from the web-service using an
133    HTTP POST and provided in a HTTP response with a content-type of
134    "application/json". To prevent unauthorised use the HTTP requests can
135    be ACLd by various means.
136
137    This mechanism is based on draft-uberti-rtcweb-turn-rest.
138
139 1.1.1. Request
140
141    The request to the web-service should contain the following parameters:
142      * service - specifies the desired service (msrp, sip, etc)
143      * username - an optional user identifier for the service (as would
144        normally be found in the username parameter of an Authorization: or
145        Proxy-Authorization: header)
146      * key - an optional API key used for authentication
147
148    Example 1.1. Request example
149 POST /?service=sip&username=foo@bar.com
150
151 1.1.2. Response
152
153    The response should include the following parameters:
154      * username - the username to use, which is a colon-delimited
155        combination of the expiration timestamp and the username parameter
156        from the request (if specified). When used with this module the
157        timestamp must be a UNIX timestamp.
158      * password - the password to use; this value is computed from the
159        secret key and the returned username value, by performing
160        base64(hmac-sha1(secret key, returned username)).
161      * ttl - the duration for which the username and password are valid,
162        in seconds.
163      * uris - an array of URIs indicating servers that the username and
164        password are valid for.
165
166    Example 1.2. Response example
167 {
168   "username" : "1234567890:foo@bar.com",
169   "password" : "asdfghjklauio=",
170   "ttl" : 86400,
171   "uris" : [
172     "sip:1.2.3.4;transport=ws",
173     "sip:5.6.7.8;transport=ws"
174   ]
175 }
176
177 2. Dependencies
178
179    2.1. Kamailio Modules
180    2.2. External Libraries or Applications
181
182 2.1. Kamailio Modules
183
184    The module must be loaded before this module:
185      * auth (optional).
186
187 2.2. External Libraries or Applications
188
189    The following libraries must be installed before running Kamailio with
190    this module loaded:
191      * OpenSSL.
192
193 3. Parameters
194
195    3.1. secret (string)
196    3.2. username_format (integer)
197    3.3. sha_algorithm (integer)
198
199 3.1. secret (string)
200
201    The shared secret to use for generating credentials. This parameter can
202    be set multiple times - this enables the secret used for new
203    credentials to be changed without causing existing credentials to stop
204    working. The last secret set is the first that will be tried.
205
206    Example 1.3. secret parameter usage
207 ...
208 modparam("auth_ephemeral", "secret", "kamailio_rules")
209 ...
210
211 3.2. username_format (integer)
212
213    The format of the username in the web-service response.
214
215      * 0 (deprecated - pre IETF draft format) - <username parameter from
216        the request>:<timestamp>
217      * 1 (default - IETF draft format) - <timestamp>:<username parameter
218        from the request>
219
220    Example 1.4. username_format parameter usage
221 ...
222 modparam("auth_ephemeral", "username_format", 0)
223 ...
224
225 3.3. sha_algorithm (integer)
226
227    The SHA algorhithm to be used for the Hash.
228
229      * 0 - SHA1 (default, as per IETF/RFC)
230      * 1 - SHA256
231      * 2 - SHA512
232
233    Example 1.5. sha_algorithm parameter usage
234 ...
235 modparam("auth_ephemeral", "sha_algorithm", 2)
236 ...
237
238 4. Functions
239
240    4.1. autheph_proxy(realm)
241    4.2. autheph_www(realm[, method])
242    4.3. autheph_check(realm)
243    4.4. autheph_authenticate(username, password)
244    4.5. autheph_check_from([username])
245    4.6. autheph_check_to([username])
246    4.7. autheph_check_timestamp(username)
247
248 4.1.  autheph_proxy(realm)
249
250    This function performs proxy authentication.
251
252 Note
253
254    This function can only be used when the auth module is loaded before
255    this module.
256
257    The meaning of the parameters are as follows:
258      * realm - realm is an opaque string that the user agent should
259        present to the user so that he can decide what username and
260        password to use. Usually this is domain of the host the server is
261        running on.
262        It must not be an empty string “”. Apart from a static string, a
263        typical value is the From-URI domain (i.e., $fd).
264        The string may contain pseudo variables.
265
266    This function can be used from REQUEST_ROUTE.
267
268    Example 1.6. autheph_proxy usage
269 ...
270 if (!autheph_proxy("$fd")) {
271     auth_challenge("$fd", "1");
272     exit;
273 }
274 ...
275
276 4.2.  autheph_www(realm[, method])
277
278    This function performs WWW digest authentication.
279
280 Note
281
282    This function can only be used when the auth module is loaded before
283    this module.
284
285    The meaning of the parameters are as follows:
286      * realm - realm is an opaque string that the user agent should
287        present to the user so that he can decide what username and
288        password to use. Usually this is domain of the host the server is
289        running on.
290        It must not be an empty string “”. Apart from a static string, a
291        typical value is the From-URI domain (i.e., $fd).
292        The string may contain pseudo variables.
293      * method - the method to be used for authentication. This parameter
294        is optional and if not set the first "word" on the request-line is
295        used.
296
297    This function can be used from REQUEST_ROUTE.
298
299    Example 1.7. autheph_www usage
300 ...
301 if (!autheph_www("$fd")) {
302     auth_challenge("$fd", "1");
303     exit;
304 }
305 ...
306
307 4.3.  autheph_check(realm)
308
309    This function combines the functionalities of autheph_www and
310    autheph_proxy, the first being exectuted if the SIP request is a
311    REGISTER, the second for the rest.
312
313 Note
314
315    This function can only be used when the auth module is loaded before
316    this module.
317
318    The meaning of the parameters are as follows:
319      * realm - realm is an opaque string that the user agent should
320        present to the user so that he can decide what username and
321        password to use. Usually this is domain of the host the server is
322        running on.
323        It must not be an empty string “”. Apart from a static string, a
324        typical value is the From-URI domain (i.e., $fd).
325        The string may contain pseudo variables.
326
327    This function can be used from REQUEST_ROUTE.
328
329    Example 1.8. autheph_check usage
330 ...
331 if (!autheph_check("$fd")) {
332     auth_challenge("$fd", "1");
333     exit;
334 }
335 ...
336
337 4.4.  autheph_authenticate(username, password)
338
339    This function performs non-digest ephemeral authentication. This may be
340    used when digest authentication cannot. For example, during WebSocket
341    handshake the username may be part of the requested URI and the
342    password presented in a Cookie: header.
343
344 Note
345
346    This function may be used without loading the auth module.
347
348    The meaning of the parameters are as follows:
349      * username - the username returned in the response from the
350        web-service.
351      * password - the password returned in the response from the
352        web-service.
353
354    This function can be used from REQUEST_ROUTE.
355
356    Example 1.9. autheph_authenticate usage
357 ...
358 if (!autheph_authenticate("$var(username)", "$var(password)")) {
359     sl_send_reply("403", "Forbidden");
360     exit;
361 }
362 ...
363
364 4.5.  autheph_check_from([username])
365
366    This function checks that the username (or username and domain) in the
367    From: URI matches the credentials.
368
369    When used without the username parameter it compares the From: URI with
370    the credentials used to authenticate the request (in the Authorization:
371    or Proxy-Authorization: headers).
372
373    The username parameter can be used to check the From: when individual
374    SIP requests are not authenticated (for example, when they are over
375    WebSockets and the connection was authenticated during the handshake).
376    In this scenario the username should be cached (perhaps in a
377    hash-table) at the point the authentication occurs.
378
379 Note
380
381    This function must have the optional username parameter specified to
382    use it without loading the auth module before this module.
383
384    The meaning of the parameters are as follows:
385      * username (optional) - the username returned in the response from
386        the web-service.
387
388    This function can be used from REQUEST_ROUTE.
389
390    Example 1.10. autheph_check_from usage
391 ...
392 if (!autheph_check_from()) {
393     sl_send_reply("403", "Forbidden");
394     exit;
395 }
396 ...
397
398 4.6.  autheph_check_to([username])
399
400    This function checks that the username (or username and domain) in the
401    To: URI matches the credentials.
402
403    When used without the username parameter it compares the To: URI with
404    the credentials used to authenticate the request (in the Authorization:
405    or Proxy-Authorization: headers).
406
407    The username parameter can be used to check the From: when individual
408    SIP requests are not authenticated (for example, when they are over
409    WebSockets and the connection was authenticated during the handshake).
410    In this scenario the username should be cached (perhaps in a
411    hash-table) at the point the authentication occurs.
412
413 Note
414
415    This function must have the optional username parameter specified to
416    use it without loading the auth module before this module.
417
418    The meaning of the parameters are as follows:
419      * username (optional) - the username returned in the response from
420        the web-service.
421
422    This function can be used from REQUEST_ROUTE.
423
424    Example 1.11. autheph_check_to usage
425 ...
426 if (!autheph_check_to()) {
427     sl_send_reply("403", "Forbidden");
428     exit;
429 }
430 ...
431
432 4.7.  autheph_check_timestamp(username)
433
434    This function checks that the timestamp in the username parameter has
435    not expired. The autheph_(check|proxy|www) functions all do this
436    automatically, but in a scenario when individual SIP requests are not
437    authenticated (for example, when they are over WebSockets and the
438    connection was authenticated during the handshake) you may want to
439    re-check for each new out-of-dialog request. In this scenario the
440    username should be cached (perhaps in a hash-table) at the point
441    authentication occurs.
442
443 Note
444
445    This function may be used without loading the auth module.
446
447    The meaning of the parameters are as follows:
448      * username - the username returned in the response from the
449        web-service.
450
451    This function can be used from REQUEST_ROUTE.
452
453    Example 1.12. autheph_check_timestamp usage
454 ...
455 if (!autheph_check_timestamp("$var(username)")) {
456     sl_send_reply("403", "Forbidden");
457     exit;
458 }
459 ...
460
461 5. RPC Commands
462
463    5.1. autheph.add_secret
464    5.2. autheph.dump_secrets
465    5.3. autheph.rm_secret
466
467 5.1. autheph.add_secret
468
469    Add a secret to the head of the shared secret list. The secret will be
470    the first one tried during future authentication attempts. This command
471    allows you to update the shared secret list without having to restart
472    Kamailio.
473
474 Note
475
476    If you want your new shared secret list to persist across restarts you
477    must add it to your Kamailio configuration file.
478
479    Name: autheph.add_secret
480
481    Parameters:
482      * secret
483
484    RPC Command Example:
485 ...
486 kamcmd autheph.add_secret mysecret
487
488 5.2. autheph.dump_secrets
489
490    Dump the set of shared secrets.
491
492    Name: autheph.dump_secrets
493
494    Parameters:
495      * none
496
497    RPC Command Example:
498 ...
499 kamcmd autheph.dump_secrets
500 ...
501
502 5.3. autheph.rm_secret
503
504    Remove the secret with the specified integer ID. This command allows
505    you to update the shared secret list without having to restart
506    Kamailio.
507
508 Note
509
510    If you want your new shared secret list to persist across restarts you
511    must add it to your Kamailio configuration file.
512
513    Name: autheph.rm_secret
514
515    Parameters:
516      * ID - the ID of the secret to remove
517
518    RPC Command Example:
519 ...
520 kamcmd autheph.rm_secret 0
521 ...