git.defcon.no Git - hermes/blob - doc/api-nodes.txt

   1 General description on API protocol:
   2 =========================================================================
   3 All API nodes currently use POST requests for all parameters.
   4 All API nodes return JSON data unless explicitly noted ,
   5 and all JSON results will contain  a 'response' element.
   6 The 'response' may be set to:
   7   * 'ok' on success. Further contents depend on the node requested.
   8   * 'invalid' on invalid requests. A 'cause' element should give a
   9         keyword denoting what was invalid about the request...
  10   * 'failed' on simple failure. A 'cause' element is supplied, with a
  11         failure-keyword (e.g. 'nonexistant', 'inuse', 'dbfail').
  12         A final 'detail' is commonly included, with a verbose desctiption.
  13   * 'error' on critical failure. Regard this as a soft form of "500 server error"...
  14
  15 So, in all Return-specifications it should be assumed that 'response' is set to
  16 'ok' on success.
  17
  18
  19 Authentication mechanism:
  20 =========================================================================
  21 All API nodes except 'auth/login' and 'auth/logout' require a
  22 'token authentication' based on a session identifier (session) and a
  23 session authentication key (auth_key) passed as parameters.
  24
  25 The 'session' and 'auth_key' values are provided as response to a
  26 successful API login through 'auth/login', and must be included as
  27 parameters to all subsequent calls to the API.
  28
  29 The 'auth_key' has a limited lifetime (configurabel, defaul 5 minutes),
  30 significantly shorter than the session lifetime. The 'auth_kye' must
  31 be renewed before the key lifetime expires, by issuing a call to
  32 'auth/ping'. The ping call will provide a new key that replaces the
  33 previous 'auth_key' in subsequent calls to the API.
  34
  35 API login may be done using either a username/password combination,
  36 or using a registered API key tied to the host originating the requests.
  37
  38 See documentation for nodes under 'auth/*' for information about
  39 adding, removing and maintaining authentication users and keys.
  40
  41 Sample session:
  42
  43    call auth/login with username and password
  44    store session and auth_key for further requests
  45
  46    perform API calls with session and auth_key set
  47    ...
  48
  49    call auth/ping with session and auth_key set
  50    update the auth_key used for requests
  51
  52    perform API calls with session and auth_key set
  53    ...
  54
  55    call auth/logout with session set
  56
  57 NOTE: that the API also requires COOKIE-support in the user-agent
  58 used to communicate with the API.
  59
  60 NOTE: See README for information on configuring API authentication
  61 backends, and boostrapping the user/key authorizations.
  62
  63 Parameter notes:
  64 =========================================================================
  65  'user'/'alias' parameters marked '*' may alternatively be given as
  66         username=foo + domain=bar
  67         alias_username=foo + alias_domain=bar
  68
  69 List of API nodes:
  70 =========================================================================
  71
  72 auth/login
  73 -------------------
  74   Required:
  75         username=authuser
  76         password=authpassword
  77   Alternate:
  78         api_key=API_KEY
  79
  80   Description:
  81         TODO: DOCUMENT THIS.
  82
  83   Return:
  84         Returns 'session' set to the allocated session_name and 'auth_key'
  85         set to the generated auth_key. These must be used for further access,
  86         and the key must be refreshed through 'auth/ping' at intervals.
  87         Returns 'failed' with 'cause' = 'unauthorized' if Login failed
  88
  89 auth/logout
  90 -------------------
  91   Required:
  92         session=session_name
  93
  94   Description:
  95         TODO: DOCUMENT THIS.
  96         // De-authenticate/deauthorize the ongoing session.
  97         // I.e. destroy session data, remove session cookies.
  98
  99   Return:
 100         Returns 'ok' on successful logout
 101
 102 auth/ping
 103 -------------------
 104   Required:
 105         session=$session_name
 106         auth_key=$auth_key
 107
 108   Description:
 109         TODO: DOCUMENT THIS.
 110         // API clients are required to periodically ping the server
 111         // The time between pings (interval) is 5 minutes?
 112         // A ping call refreshes cookie lifetimes, then
 113         // generates and stores a new auth_key
 114         // The ping required a valid session...
 115         // A successful ping returns a 'response' => 'pong'
 116         // along with the new auth_key.
 117
 118         NOTE!: Does not give 'response' => 'ok' !
 119
 120   Return:
 121         Returns 'pong' with 'auth_key' set to the new key to be used
 122         with the session_name in further requests.
 123
 124 auth/new_apikey
 125 -------------------
 126   Required:
 127         host_ip=10.20.30.40
 128         access=limited_read
 129
 130   Description:
 131         TODO: DOCUMENT THIS.
 132         'access' may be one of:
 133           * limited_read
 134           * full_read
 135           * read_write
 136
 137   Return:
 138         Returns 'key', 'host' and 'access'.
 139         Returns 'invalid' with 'cause' = 'parameters' on parameter error
 140         Returns 'failed' with  'cause' = 'error' on database errors.
 141         TODO: Change 'error' to 'dbfail'.
 142
 143 auth/remove_apikey
 144 -------------------
 145   Required:
 146         api_key=$key
 147
 148   Description:
 149         TODO: DOCUMENT THIS.
 150
 151   Return:
 152         Returns 'key' set to the removed key on success.
 153         Returns 'invalid' on parameter error
 154         Returns 'failed' with 'cause' = 'nonexistant' if key does not exist.
 155         Returns 'failed' with 'cause' = 'error' on database errors.
 156         TODO: Change 'error' to 'dbfail'.
 157
 158 auth/list_apikeys
 159 -------------------
 160
 161   Description:
 162         TODO: DOCUMENT THIS.
 163
 164   Return:
 165         Returns 'list'
 166
 167 auth/authorize_user
 168 -------------------
 169   Required:
 170         username=authuser
 171         access=limited_read
 172
 173   Description:
 174         TODO: DOCUMENT THIS.
 175         // Add or update a valid back-end user in authorization
 176         // if the current authentication has write access.
 177         // If the authorization does not exist, add it.
 178         // If the user is already authorized, replace access level.
 179
 180         'access' may be one of:
 181           * limited_read
 182           * full_read
 183           * read_write
 184
 185   Return:
 186         Returns 'user' and 'access' when user was successfully added.
 187         Returns 'invalid' with 'cause' = 'parameters' on parameter error
 188         Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
 189         Returns 'failed' with 'cause' = 'error' on database errors.
 190
 191 auth/remove_user
 192 -------------------
 193   Required:
 194         username=authuser
 195
 196   Description:
 197         TODO: DOCUMENT THIS.
 198         // If the current authentication has write access:
 199         // Remove authorization for the given users.
 200         // Delete user from backend if backend is read-write.
 201
 202   Return:
 203         Returns 'user' when user was successfully removed.
 204         Returns 'invalid' with 'cause' = 'parameters' on parameter error
 205         Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
 206         Returns 'failed' with 'cause' = 'error' on database errors.
 207
 208 auth/list_users
 209 -------------------
 210
 211   Description:
 212         Returns 'list'
 213
 214 auth/add_user
 215 -------------------
 216
 217   Description:
 218         TODO: This is not implemented. Document, write test and implement.
 219         Returns 'notimplemented'
 220         // Add user to backend if backend is read-write and
 221         // the current authentication has write access.
 222         // The created user should be added to authorizations
 223         // with an access level of "limited_read (1)"
 224
 225 auth/update_user
 226 -------------------
 227
 228   Description:
 229         TODO: This is not implemented. Document, write test and implement.
 230         Returns 'notimplemented'
 231         // Update the given user in the backend, if the backend
 232         // is read-write, and the current authentication has
 233         // write access.
 234
 235 user/get
 236 -------------------
 237   Required:
 238         user=user@bar.bz *
 239
 240   Description:
 241         Return User information, not including hardphone association.
 242
 243   Return:
 244         On success, 'user' will be set to the user-data set:
 245         for all users:
 246                 type,username,password,domain,authid,registrar,
 247                 r_port,proxy,p_port,dialplan,displayname,linetext
 248         for local users (kamailio), as above, plus:
 249                 email,ha1,ha1b,rpid,permittedcalls
 250         Returns 'failed' with 'cause' = 'nonexistant' if user does not exist..
 251         Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
 252
 253 user/list
 254 -------------------
 255   Optional:
 256         search=foo@bar
 257
 258   Description:
 259         Return an array of users, with 'user' set to SIP-address and
 260         'displayname' set to the users Displayname.
 261
 262         If the search parameter is included, a globbing search is performed,
 263         and only matches are listed.
 264
 265   Return:
 266         TODO: Document this
 267
 268 user/add_local
 269 -------------------
 270   Required:
 271         user=foo@bar.bz *
 272         displayname=baz
 273         email=qux@zef.tld
 274
 275   Description:
 276         Adds a user account to both Kamailio and provisioning, if the
 277         username@domain is nonexistant, and the domain is local (handled by
 278         Kamailio). The password for the user is auto-generated.
 279
 280   Return:
 281         Returns a full user object, the same form as user/get
 282         Returns 'failed' with 'cause' = 'exists' if address is taken
 283         Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
 284         Returns 'failed' with 'cause' = 'servfail' if no default servers
 285         could be determined for the requested domain. See domain/set_servers.
 286         Returns 'failed' with 'cause' = 'dbfail' on database errors..
 287
 288 user/add_remote
 289 -------------------
 290   Required:
 291         user=foo@bar.bz *
 292         password=S3cr3t
 293         displayname=baz
 294         registrar=sip.example.com
 295   Optional:
 296         r_port=5060
 297         proxy=sipproxy.example.com
 298         p_port=5060
 299         authid=realfoo
 300         dialplan=(.*)
 301         linetext=lalala
 302
 303   Description:
 304         Adds a provisioning user for a remote SIP account. This allows locally
 305         provisioned hardphones to be associated with non-local SIP accounts.
 306
 307   Return:
 308         Returns a full user object, the same form as user/get
 309         Returns 'failed' with  'cause' = 'domain' if an attempt is made to
 310         add_remote for a local domain.
 311         Returns 'failed' with 'cause' = 'exists' on any address collisions
 312         Returns 'failed' with 'cause' = 'dbfail' on database errors..
 313
 314 user/remove
 315 -------------------
 316   Required:
 317         user=foo@bar.bz *
 318
 319   Description:
 320         Removes user account from Kamailio, if present, and removes user from
 321         provisioning.
 322
 323         Will fail if user has associated hardphones, remove phones before
 324         removing user.
 325
 326         TODO: Should fail if user has associated aliases. Remove aliases before
 327         removing user.
 328
 329   Return:
 330         TODO: Document additional data on 'result' = 'ok'
 331         Returns 'failed' with 'cause' = 'nonexistant' if user does not exist..
 332         Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
 333         Returns 'failed' with 'cause' = 'inuse' if phone-associations exists
 334         TODO: Returns 'failed' with 'cause' = 'inuse' if aliases exist for the address
 335
 336
 337 user/change_pw
 338 -------------------
 339   Required:
 340         user=foo@bar.bz *
 341         password=baz
 342
 343   Description:
 344         Changes the password for the given user, returns 'ok' with 'detail' as
 345         a descriptive text on success. In the current implementation,
 346         provisioning and kamailio passwords are handled separately, so one
 347         may succeed and the other fail. As is, this permits password changes
 348         of non-local provision users with minimal effort.
 349
 350   Return:
 351         Returns 'detail' on success.
 352         Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
 353         Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
 354         Returns 'failed' with 'cause' = 'dbfail' if the database request
 355         failed. Note that this may be because the given password was identical
 356         to the old.
 357
 358 user/change_email
 359 -------------------
 360   Required:
 361         user=foo@bar.bz *
 362         email=user@example.com
 363
 364   Description:
 365         Changes the email address for the given user, returns 'ok' with
 366         'user' set to the requested username and 'email' set to the
 367         email address.  This only applies to kamailio local users.
 368
 369   Return:
 370         Returns 'user' and 'email' on success.
 371         Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
 372         TODO: Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
 373         Returns 'failed' with 'cause' = 'dbfail' if the database request
 374         failed. This may be because no update was required ...
 375
 376 user/update
 377 -------------------
 378   Required:
 379         user=foo@bar.bz *
 380   optionals:
 381         displayname=baz
 382         dialplan=(.*)
 383         linetext=lalala
 384         email=foo@bar.baz
 385
 386         Updates user with the given data....
 387         TODO: Extend this description ;)
 388
 389   Return:
 390         Returns two arrays on success, 'updated' containing updated params
 391         and 'skipped' containing specified parameters that did not require
 392         any changes.
 393         Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
 394         Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
 395         Returns 'failed' with 'cause' = 'dbfail' if the database request
 396         failed. With database errors, the array 'failed' will contain any
 397         parameters that may have caused the dbfail.
 398
 399 user/available
 400 -------------------
 401         user=foo@bar.bz *
 402
 403   Description:
 404         Tests an address to see if it is available.
 405
 406   Return:
 407         Returns 'ok' with 'cause' = 'nonexistant' if the address is available.
 408         Returns 'failed' with 'cause' = 'exists' if the address is in use.
 409         Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
 410
 411 user/gen_pw
 412 -------------------
 413
 414   Description:
 415         Generates a random password on the same form as that used by
 416         user/add_local.
 417
 418         NOTE: This node does not use JSON formatting.
 419
 420   Return:
 421         Return is always a password in plain text, with no formatting.
 422
 423 phone/get
 424 -------------------
 425   Optional:
 426         mac=f00ba2ba5c00
 427         user=foo@bar.bz *
 428
 429   Description:
 430         Returns a list of associated elements. If MAC address is given as
 431         parameter, a list of associated user@domain addresses is retruned. If
 432         user@domain is given as parameter, a list of associated mac addresses
 433         is returned.
 434
 435   Return:
 436         Returns 'list' as an array of phone-user mappings on success,
 437         where each element of 'list' consists of either usernames or mac-adresses.
 438         Returns 'failed' with 'cause' = 'nonexistant' on no matches.
 439         Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
 440
 441 phone/list
 442 -------------------
 443   Optional:
 444         search=f00ba2
 445
 446   Description:
 447         Returns the list of registered MAC addresses. If the (optional) search
 448         parameter is included, the list is the result of a globbing search,
 449         a subset matching on the MAC addresses.
 450
 451   Return:
 452         Returns 'list' as a simple array of registered MAC-adresses on success,
 453         the list will be limited to addresses matching the search if provided.
 454
 455
 456 phone/add
 457 -------------------
 458   Required:
 459         user=foo@bar.bz *
 460         mac=f00ba2ba5c00
 461
 462   Description:
 463         Adds a phone-to-user association to Provisioning. The user may be
 464         provided as 'username' and 'domain' in separate parameters, or as
 465         'user' in sip-address form. The MAC address must be valid, in plain-hex
 466         or colon-separated form, and the user must match a valid user
 467         registration.
 468
 469   Return:
 470         Returns 'mac', 'username' and 'domain' on success.
 471         Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
 472         Returns 'failed' with 'cause' = 'invalid' if MAC address is malformed.
 473         Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
 474         Returns 'failed' with 'cause' = 'exists' if user+mac is already reg.
 475         Returns 'failed' with 'cause' = 'dbfail' on database failure.
 476
 477 phone/remove
 478 -------------------
 479   Required:
 480         user=foo@bar.bz *
 481         mac=f00ba2ba5c00
 482
 483   Description:
 484         Deletes a phone-to-user association. Required parameters and formats
 485         are identical to the phone/add node.
 486
 487   Return:
 488         Returns 'mac', 'username' and 'domain' on success.
 489         Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
 490         Returns 'failed' with 'cause' = 'invalid' if MAC address is malformed.
 491         Returns 'failed' with 'cause' = 'nonexistant' on no such registration.
 492
 493
 494 numbers/list
 495 -------------------
 496   Optional:
 497         search=1234
 498         random=true
 499         limit=n
 500
 501   Description:
 502         Gives a list of entries in the phone number pool.
 503         With no parameters, the entire (ordered) list of available numbers is
 504         returned.  With 'search', the result of a pre-post globbing search is
 505         returned With 'random', a list of entries is returned unordered (random
 506         order) For all nodes, 'limit' may be a numeric limit of desired
 507         results.
 508
 509   Return:
 510         Returns the list of numbers as the array 'list'.
 511         Returns 'failed' with 'cause' = 'empty' if no numbers were listed...
 512
 513 numbers/add_range
 514 -------------------
 515   Required:
 516         start=+4712345000
 517         end=+4712345678
 518
 519   Description:
 520         The start and end must have identical lead-in, and start must be less
 521         than end.  Both numbers must be given in E164 format, remember to
 522         urlencode the plus (+ -> %2B). The numeric component of both will be
 523         extracted, and all numbers in the range will be iteratively added to
 524         the pool, including the ending number.
 525
 526   Return:
 527         TODO: Document additional info provided on 'result' = 'ok'
 528         Returns 'failed' with 'cause' = 'rejected' with 'detail' set on failure
 529
 530 numbers/add
 531 -------------------
 532   Required:
 533         number=+4712345679
 534
 535   Description:
 536         Adds the given number to the pool, after verifying that the number is
 537         in valid E164 format, and that the number does not already exist in the
 538         pool.
 539
 540   Return:
 541         Returns "Added <number>" in 'detail' on success.
 542         Returns 'failed' with 'cause' = 'rejected' and 'detail' set to "Not a
 543         valid E164 number" if the provided number could not pass E164
 544         validation.
 545         Returns 'failed' with 'cause' = 'exists' if number is already in the pool.
 546         TODO: Returns 'failed' with 'cause' = 'dbfail' on database failure.
 547         TODO: Gives 'cause' = 'rejected' with no detail in current code.
 548
 549 numbers/remove
 550 -------------------
 551   Required:
 552         number=+4712345676
 553
 554   Description:
 555         Removes/pulls a number from the pool.
 556         The number must be a valid e164 number, and must be present in the
 557         pool.
 558
 559   Return:
 560         Returns 'number' set to the number that was pulled from the pool.
 561         Returns 'failed' with 'cause' = 'rejected' and 'detail' set to "Not a
 562         valid E164 number" if the provided number could not pass E164
 563         validation.
 564         Returns 'failed' with 'cause' = 'nonexistant' if number is not the pool.
 565         Returns 'failed' with 'cause' = 'dbfail' on database failure.
 566
 567 numbers/inpool
 568 -------------------
 569   Required:
 570         number=+4712345676
 571
 572   Description:
 573         Tests if the given E164 number is in the pool.
 574
 575   Return:
 576         Returns 'number' = '<number>' If the number is in the pool
 577         Returns response = 'failed' with 'cause' = 'nonexistant' if not.
 578
 579 alias/list
 580 -------------------
 581   Optional:
 582         alias=foo@bar.bz
 583         destination=foo@bar.bz
 584         e164=true
 585
 586   Description:
 587         With no parameters, this will return all defined aliases (potentially a
 588         huge list). With the destination parameter set, only aliases for that
 589         destination will be listed, and with the e164 option set to true, only
 590         an e164 alias will be returned (if one/it exists). The alias parameter
 591         gives the same behaviour, but looks up an alias address instead of the
 592         destination. The e164 option is not valid for the alias search
 593         (naturally).
 594
 595   Return:
 596         Returns 'ok' on success, with an array 'aliases' containing
 597         'destination' and 'alias' pairs.
 598         Returns 'ok' with an empty array if the search gave no results.
 599         Returns 'ok' with an empty array if the database search fails.
 600         Returns 'failed' with 'cause' = 'invalid' on invalid SIP addresses.
 601
 602 alias/add
 603 -------------------
 604   Required:
 605         alias=foo@bar.bz *
 606         destination=bar@qux.zx
 607
 608   Description:
 609         Add an alias specified by alias_username and alias_domain that
 610         points to the destination SIP-adress.
 611
 612   Return:
 613         On success, 'ok' is returned, with 'alias' and 'destination' set to the
 614         resulting alias and destination adresses.
 615         Returns 'invalid' with 'cause' = 'destination' or 'alias' if the
 616         resulting alias-adress or destination are invalid SIP-adresses.
 617         Returns 'failed' with 'cause' = 'nxdomain' if the given alias domain is
 618         not a Kamailio domain.
 619         Returns 'failed' with 'cause' = 'exists' if the alias is an E164 number
 620         and the user already has an E164 alias registered.
 621         Returns 'failed' with 'cause' = 'nonexistant' when an alias for a local
 622         domain is requested, but the local subscriber does not exist.
 623         Returns 'failed' with 'cause' = 'exists' for aliases that already
 624         exists, (and aliases that overlaps SIP-accounts - not implemented).
 625
 626
 627 alias/remove
 628 -------------------
 629   Required:
 630         alias=foo@bar.bz *
 631
 632   Description:
 633         Removes the alias given by alias_username and alias_domain.
 634
 635   Return:
 636         Returns 'ok' with the removed alias adress as 'alias' on success
 637         Returns 'failed' with 'cause' = 'nonexistant' it the alias does not
 638         exists.
 639         Returns 'invalid' with 'cause' = 'address' if the given alias is not a
 640         valid SIP adress.
 641
 642
 643 domain/list
 644 -------------------
 645
 646   Description:
 647         Returns a list of configured and valid domains. May return an empty
 648         list if no domains are configured for kamailio. No node is provided
 649         to add domains, this is not a task for Hermes, but a kamailio
 650         configuration task.
 651
 652   Return:
 653         Returns a list of domains as 'list' on success.
 654         Returns 'failed' on database errors.
 655
 656 domain/get_servers
 657 -------------------
 658   Required:
 659         domain=bar.bz
 660
 661   Description:
 662         Provides the default registrar/proxy/provisioning server information
 663         for the given domain.
 664
 665   Return:
 666         Returns 'ok' with 'servers' set to a kvp-set on success, containing:
 667         'registrar','r_port','proxy','p_port','prov_url'.
 668         Returns 'failed' with 'cause' = 'nonexistant' if lookup of data for
 669         given domain results in an empty set (not configured).
 670
 671 domain/set_servers
 672 -------------------
 673   Required:
 674         domain=bar.bz
 675         registrar=server.bar.bz
 676         r_port=5060
 677         proxy=proxy.bar.bz
 678         p_port=5060
 679         prov_url=http://server.bar.bz/hermes/prov
 680
 681   Description:
 682         Sets the server data for the given domain. All of these parameters
 683         are Required: 'domain', 'registrar', 'r_port', 'proxy', 'p_port', 'prov_url'.
 684         If no default server data is defined, the configuration is added.
 685         If server configuration existed, the default data is updated.
 686
 687   Return:
 688         Returns 'ok' with 'servers' set as domain/get_servers on success.
 689         Returns 'failed' with 'cause' set to 'cause' set to 'parameters'
 690         if one of these is true:
 691                 * Missing parameters
 692                 * One or more NULL/empty parameters
 693                 * Non-numeric values for port-numbers.
 694         If you need to determine which of these triggered, the
 695         'description' contains a text describing the actual fail.
 696         Return 'failed' with 'cause' = 'error' on database failure.
 697
 698 BUGS:
 699 ---------------------
 700
 701 api/alias/list destination=foo@bar.bz e164=true
 702         should return an empty array, returns false
 703
 704 TODO list:
 705 ---------------------
 706
 707 Some TODO's listed above ...
 708
 709 Permissions! (user/permissions?user=...)
 710
 711 Improve robustness of change_pw: fetch old password for rollback/testing.
 712
 713 Check for locations where sql_dbexec_rows is more appropriate/correct than sql_dbexec
 714
 715 Perform an evaluation of the security related to the api-key functionality,
 716 and replace if the method is evaluated as too weak. I.e. implement strong
 717 non-interactive, non-user based authentication.