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