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         TODO: Document this.
 453
 454 phone/add
 455 -------------------
 456   Required:
 457         user=foo@bar.bz *
 458         mac=f00ba2ba5c00
 459
 460   Description:
 461         Adds a phone-to-user association to Provisioning. The user may be
 462         provided as 'username' and 'domain' in separate parameters, or as
 463         'user' in sip-address form. The MAC address must be valid, in plain-hex
 464         or colon-separated form, and the user must match a valid user
 465         registration.
 466
 467   Return:
 468         Returns 'mac', 'username' and 'domain' on success.
 469         Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
 470         Returns 'failed' with 'cause' = 'invalid' if MAC address is malformed.
 471         Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
 472         Returns 'failed' with 'cause' = 'exists' if user+mac is already reg.
 473         Returns 'failed' with 'cause' = 'dbfail' on database failure.
 474
 475 phone/remove
 476 -------------------
 477   Required:
 478         user=foo@bar.bz *
 479         mac=f00ba2ba5c00
 480
 481   Description:
 482         Deletes a phone-to-user association. Required parameters and formats
 483         are identical to the phone/add node.
 484
 485   Return:
 486         TODO: Document additional info provided on 'result' = 'ok'
 487         Returns 'failed' with 'cause' = 'invalid' if SIP address is malformed.
 488         Returns 'failed' with 'cause' = 'invalid' if MAC address is malformed.
 489         Returns 'failed' with 'cause' = 'nonexistant' on no such registration.
 490
 491
 492 numbers/list
 493 -------------------
 494   Optional:
 495         search=1234
 496         random=true
 497         limit=n
 498
 499   Description:
 500         Gives a list of entries in the phone number pool.
 501         With no parameters, the entire (ordered) list of available numbers is
 502         returned.  With 'search', the result of a pre-post globbing search is
 503         returned With 'random', a list of entries is returned unordered (random
 504         order) For all nodes, 'limit' may be a numeric limit of desired
 505         results.
 506
 507   Return:
 508         Returns the list of numbers as the array 'list'.
 509         Returns 'failed' with 'cause' = 'empty' if no numbers were listed...
 510
 511 numbers/add_range
 512 -------------------
 513   Required:
 514         start=+4712345000
 515         end=+4712345678
 516
 517   Description:
 518         The start and end must have identical lead-in, and start must be less
 519         than end.  Both numbers must be given in E164 format, remember to
 520         urlencode the plus (+ -> %2B). The numeric component of both will be
 521         extracted, and all numbers in the range will be iteratively added to
 522         the pool, including the ending number.
 523
 524   Return:
 525         TODO: Document additional info provided on 'result' = 'ok'
 526         Returns 'failed' with 'cause' = 'rejected' with 'detail' set on failure
 527
 528 numbers/add
 529 -------------------
 530   Required:
 531         number=+4712345679
 532
 533   Description:
 534         Adds the given number to the pool, after verifying that the number is
 535         in valid E164 format, and that the number does not already exist in the
 536         pool.
 537
 538   Return:
 539         Returns "Added <number>" in 'detail' on success.
 540         Returns 'failed' with 'cause' = 'rejected' and 'detail' set to "Not a
 541         valid E164 number" if the provided number could not pass E164
 542         validation.
 543         Returns 'failed' with 'cause' = 'exists' if number is already in the pool.
 544         TODO: Returns 'failed' with 'cause' = 'dbfail' on database failure.
 545         TODO: Gives 'cause' = 'rejected' with no detail in current code.
 546
 547 numbers/remove
 548 -------------------
 549   Required:
 550         number=+4712345676
 551
 552   Description:
 553         Removes/pulls a number from the pool.
 554         The number must be a valid e164 number, and must be present in the
 555         pool.
 556
 557   Return:
 558         Returns 'number' set to the number that was pulled from the pool.
 559         Returns 'failed' with 'cause' = 'rejected' and 'detail' set to "Not a
 560         valid E164 number" if the provided number could not pass E164
 561         validation.
 562         Returns 'failed' with 'cause' = 'nonexistant' if number is not the pool.
 563         Returns 'failed' with 'cause' = 'dbfail' on database failure.
 564
 565 numbers/inpool
 566 -------------------
 567   Required:
 568         number=+4712345676
 569
 570   Description:
 571         Tests if the given E164 number is in the pool.
 572
 573   Return:
 574         Returns 'number' = '<number>' If the number is in the pool
 575         Returns response = 'failed' with 'cause' = 'nonexistant' if not.
 576
 577 alias/list
 578 -------------------
 579   Optional:
 580         alias=foo@bar.bz
 581         destination=foo@bar.bz
 582         e164=true
 583
 584   Description:
 585         With no parameters, this will return all defined aliases (potentially a
 586         huge list). With the destination parameter set, only aliases for that
 587         destination will be listed, and with the e164 option set to true, only
 588         an e164 alias will be returned (if one/it exists). The alias parameter
 589         gives the same behaviour, but looks up an alias address instead of the
 590         destination. The e164 option is not valid for the alias search
 591         (naturally).
 592
 593   Return:
 594         Returns 'ok' on success, with an array of 'destination' and 'alias'
 595         pairs.
 596         Returns 'ok' with an empty array if the search gave no results.
 597         Returns 'ok' with an empty array if the database search fails.
 598         Returns 'failed' with 'cause' = 'invalid' on invalid SIP addresses.
 599
 600 alias/add
 601 -------------------
 602   Required:
 603         alias=foo@bar.bz *
 604         destination=bar@qux.zx
 605
 606   Description:
 607         Add an alias specified by alias_username and alias_domain that
 608         points to the destination SIP-adress.
 609
 610   Return:
 611         On success, 'ok' is returned, with 'alias' and 'destination' set to the
 612         resulting alias and destination adresses.
 613         Returns 'invalid' with 'cause' = 'destination' or 'alias' if the
 614         resulting alias-adress or destination are invalid SIP-adresses.
 615         Returns 'failed' with 'cause' = 'nxdomain' if the given alias domain is
 616         not a Kamailio domain.
 617         Returns 'failed' with 'cause' = 'exists' if the alias is an E164 number
 618         and the user already has an E164 alias registered.
 619         Returns 'failed' with 'cause' = 'nonexistant' when an alias for a local
 620         domain is requested, but the local subscriber does not exist.
 621         Returns 'failed' with 'cause' = 'exists' for aliases that already
 622         exists, (and aliases that overlaps SIP-accounts - not implemented).
 623
 624
 625 alias/remove
 626 -------------------
 627   Required:
 628         alias=foo@bar.bz *
 629
 630   Description:
 631         Removes the alias given by alias_username and alias_domain.
 632
 633   Return:
 634         Returns 'ok' with the removed alias adress as 'alias' on success
 635         Returns 'failed' with 'cause' = 'nonexistant' it the alias does not
 636         exists.
 637         Returns 'invalid' with 'cause' = 'address' if the given alias is not a
 638         valid SIP adress.
 639
 640
 641 domain/list
 642 -------------------
 643
 644   Description:
 645         Returns a list of configured and valid domains. May return an empty
 646         list if no domains are configured for kamailio. No node is provided
 647         to add domains, this is not a task for Hermes, but a kamailio
 648         configuration task.
 649
 650   Return:
 651         Returns a list of domains as 'list' on success.
 652         Returns 'failed' on database errors.
 653
 654 domain/get_servers
 655 -------------------
 656   Required:
 657         domain=bar.bz
 658
 659   Description:
 660         Provides the default registrar/proxy/provisioning server information
 661         for the given domain.
 662
 663   Return:
 664         Returns 'ok' with 'servers' set to a kvp-set on success, containing:
 665         'registrar','r_port','proxy','p_port','prov_url'.
 666         Returns 'failed' with 'cause' = 'nonexistant' if lookup of data for
 667         given domain results in an empty set (not configured).
 668
 669 domain/set_servers
 670 -------------------
 671   Required:
 672         domain=bar.bz
 673         registrar=server.bar.bz
 674         r_port=5060
 675         proxy=proxy.bar.bz
 676         p_port=5060
 677         prov_url=http://server.bar.bz/hermes/prov
 678
 679   Description:
 680         Sets the server data for the given domain. All of these parameters
 681         are Required: 'domain', 'registrar', 'r_port', 'proxy', 'p_port', 'prov_url'.
 682         If no default server data is defined, the configuration is added.
 683         If server configuration existed, the default data is updated.
 684
 685   Return:
 686         Returns 'ok' with 'servers' set as domain/get_servers on success.
 687         Returns 'failed' with 'cause' set to 'cause' set to 'parameters'
 688         if one of these is true:
 689                 * Missing parameters
 690                 * One or more NULL/empty parameters
 691                 * Non-numeric values for port-numbers.
 692         If you need to determine which of these triggered, the
 693         'description' contains a text describing the actual fail.
 694         Return 'failed' with 'cause' = 'error' on database failure.
 695
 696 BUGS:
 697 ---------------------
 698
 699 api/alias/list destination=foo@bar.bz e164=true
 700         should return an empty array, returns false
 701
 702 TODO list:
 703 ---------------------
 704
 705 Some TODO's listed above ...
 706
 707 Permissions! (user/permissions?user=...)
 708
 709 Improve robustness of change_pw: fetch old password for rollback/testing.
 710
 711 Check for locations where sql_dbexec_rows is more appropriate/correct than sql_dbexec
 712
 713 Perform an evaluation of the security related to the api-key functionality,
 714 and replace if the method is evaluated as too weak. I.e. implement strong
 715 non-interactive, non-user based authentication.