Differenze tra le versioni di "AdminGuide:RestAPI/en"

Da Kalliope Wiki.
Jump to navigation Jump to search
(Creata pagina con " http[s]://''KALLIOPE_IP_ADDRESS''/api/doc.json")
Riga 71: Riga 71:
   X-authenticate: RestApiUsernameToken Username="admin", Domain="default", Digest="+PJg7Tb3v98XnL6iJVv+v5hwhYjdzQ2tIWxvJB2cE40=", Nonce="bfb79078ff44c35714af28b7412a702b", Created="2016-04-29T15:48:26Z"
   X-authenticate: RestApiUsernameToken Username="admin", Domain="default", Digest="+PJg7Tb3v98XnL6iJVv+v5hwhYjdzQ2tIWxvJB2cE40=", Nonce="bfb79078ff44c35714af28b7412a702b", Created="2016-04-29T15:48:26Z"


<div class="mw-translate-fuzzy">
== API list ==
== API list ==
<!--
<!--
Riga 103: Riga 102:
|}
|}
-->
-->
For firmware versions up to 4.8.x, the updated API list can be viewed at '''http://''kalliope_ip_address''/api/doc'''
For firmware versions up to 4.8.x, the updated API list can be viewed at  
</div>


   http[s]://''KALLIOPE_IP_ADDRESS''/api/doc  
   http[s]://''KALLIOPE_IP_ADDRESS''/api/doc  
Riga 112: Riga 110:
Accedendo alla '''KalliopeTribe''' è disponibile un video che mostra l'utilizzo di tale collection per invocare in modo rapido le API di Kalliope.
Accedendo alla '''KalliopeTribe''' è disponibile un video che mostra l'utilizzo di tale collection per invocare in modo rapido le API di Kalliope.


The collection file can be downloaded from this  [https://www.kalliopepbx.com/wiki/KalliopePBX%20API%204.9.4.postman_collection.json.zip link].
The collection file can be downloaded from these links:<br>
* [https://www.kalliopepbx.com/wiki/KalliopePBX%20API%204.9.4.postman_collection.json.zip Collection Postman for firmware 4.9.4 - 4.9.8]
* [https://www.kalliopepbx.com/wiki/KalliopePBX%20API%204.9.9.postman_collection.json.zip Collection Postman for firmware 4.9.9 or superior]
* [https://www.kalliopepbx.com/wiki/Hotel%20API%204.9.9.postman_collection.zip Collection Postman for Hotel Module, firmware 4.9.9 or superior]
* [http://www.kalliopepbx.com/wiki/KalliopeLAM.postman_collection_4_11_3.zip Collection Postman for KalliopeLAM, firmware 4.11.3 or superior]


You can download the file with API swagger specification from KalliopePBX, here:<br>
You can download the file with API swagger specification from KalliopePBX, here:<br>
Riga 118: Riga 120:
   http[s]://''KALLIOPE_IP_ADDRESS''/api/doc.json
   http[s]://''KALLIOPE_IP_ADDRESS''/api/doc.json


== Manuale per le API relative al CDR ==
== Guide for CDR-related API ==
Dal momento che le API relative al CDR sono le più comunemente utilizzate abbiamo realizzato un semplice documento di approfondimento su questa famiglia di API.<br>
Since CDR-related API are the most common, we created a document about this family of API.<br>
E' possibile scaricare il documento da questo [https://www.kalliope.com/download/manuale-api-rest-cdr-v4/?wpdmdl=2100&masterkey link].
You can download it from this [https://www.kalliope.com/download/manuale-api-rest-cdr-v4/?wpdmdl=2100&masterkey link].


== Classes for generating authentication headers ==
== Classes for generating authentication headers ==

Versione delle 14:47, 15 feb 2022

Altre lingue:

Return to AdminGuide

General description

KalliopePBX offers several REST APIs that can be invoked by external systems to execute device actions (e.g. creating extensions, generating and downloading backups, etc.) or consultation actions (e.g. downloading the CDR, etc.).

APIs can be accessed through HTTP or HTTPS with authentication, following the mechanism described below.

Authentication mechanism

The REST API authentication mechanism uses the same user credentials as those needed to access the web. Specifically, each request must contain a custom single-use HTTP header named X-authenticate. The authentication procedure is one-way, i.e. it does not require the server to send a challenge, and all information necessary for authentication is generated from the client side.

Because the headers are single use, knowledge of the X-authenticate header of a request does not allow one to send an illicit request, thus preventing replication attacks.

X-authenticate header construction

The header is comprised of a sequence of data and a digest constructed from that data along with the password of the user making the request. Here is an example of a complete X-authenticate header:

 X-authenticate: RestApiUsernameToken Username="admin", Domain="default", Digest="+PJg7Tb3v98XnL6iJVv+v5hwhYjdzQ2tIWxvJB2cE40=", Nonce="bfb79078ff44c35714af28b7412a702b", Created="2016-04-29T15:48:26Z"

The information transmitted in the request are:

  • Username: the username assigned to the user (e.g. admin).
  • Domain: the domain of the tenant that the user belongs to. In single-tenant systems, the predefined domain is "default".
  • Nonce: a random hexadecimal string of at least 8 characters generated by the client. A new one must be generated for each request, as the system keeps track of all previously used nonces for their lifetime of 5 minutes. After 5 minutes, it is possible to reuse a nonce; protection from attacks will be guaranteed by the nonce creation timestamp.
  • Created: the nonce creation timestamp; if the time of reception differs from the time set on KalliopePBX by more than 5 minutes, the request will be considered invalid and refused. This guarantees that an X-authenticate header cannot be reused at any time. The timestamp format is "YYYY-MM-DDThh:mm:ssZ" (UTC timezone).

The Digest field is a hash of the above data along with the user password, generated by applying the SHA-256 hash algorithm to the concatenation (with no delimiters) of Nonce, digestPassword, Username, Domain, and Created:

 Digest = sha256(Nonce + digestPassword + Username + Domain + Created)

Since KalliopePBX saves passwords in the form of non-reversible hashes, the digest must be generated using the hash of the password obtained using the same method as KalliopePBX (digestPassword).

The hash function that produces the digestPassword requires the user password and a salt string, which is unique for each tenant. The salt can be obtained from KalliopePBX with a designated REST API that can be invoked anonymously (i.e. without authentication):

 rest/salt/<dominio_tenant>

dove la stringa <dominio_tenant> ,nel caso di macchina single tenant, vale "default". Nel caso di sistema multi-tenant, per poter utilizzare le API a disposizione di pbxadmin, è possibile ottenere il salt relativo mediante l'API

 rest/salt/pbxAdmin

The formula is as follows (the { e } characters are part of the string to which SHA-256 is applied and must be inserted):

 digestPassword = sha256(password{<salt>})

For example, if the password is "admin" and the salt is "b5a8fdcf2f8d5acdad33c4a072a97d7a", the resulting digestPassword is

 digestPassword = sha256(admin{b5a8fdcf2f8d5acdad33c4a072a97d7a}) = dd7b0be7fa37d6cbaf0b842bf7532f229cb79ab8d54d509c2aa7eea27a53cd5e

So the following information:

 Nonce: bfb79078ff44c35714af28b7412a702b
 digestPassword: dd7b0be7fa37d6cbaf0b842bf7532f229cb79ab8d54d509c2aa7eea27a53cd5e
 Username: admin
 Domain: default
 Created: 2016-04-29T15:48:26Z
 

will result in:

 Digest = base64(sha256binary(bfb79078ff44c35714af28b7412a702bdd7b0be7fa37d6cbaf0b842bf7532f229cb79ab8d54d509c2aa7eea27a53cd5eadmindefault2016-04-29T15:48:26Z))

which is +PJg7Tb3v98XnL6iJVv+v5hwhYjdzQ2tIWxvJB2cE40=.

N.B.: sha256binary(..) is the sha256(..) function that outputs a binary string rather than a hexadecimal one.

The complete string to insert in the header is therefore:

 X-authenticate: RestApiUsernameToken Username="admin", Domain="default", Digest="+PJg7Tb3v98XnL6iJVv+v5hwhYjdzQ2tIWxvJB2cE40=", Nonce="bfb79078ff44c35714af28b7412a702b", Created="2016-04-29T15:48:26Z"

API list

For firmware versions up to 4.8.x, the updated API list can be viewed at

 http[s]://KALLIOPE_IP_ADDRESS/api/doc 

Starting from firmware version 4.9.4 it is also available a Postman collection (that replaces the sandbox integrated in the documentation page); this collection integrates the code to automatically add the required authentication header (it is necessary only to set the IP address of the PBX and the username/password credentials of the user to invoke the API).

Accedendo alla KalliopeTribe è disponibile un video che mostra l'utilizzo di tale collection per invocare in modo rapido le API di Kalliope.

The collection file can be downloaded from these links:

You can download the file with API swagger specification from KalliopePBX, here:

  http[s]://KALLIOPE_IP_ADDRESS/api/doc.json

Guide for CDR-related API

Since CDR-related API are the most common, we created a document about this family of API.
You can download it from this link.

Classes for generating authentication headers

Listed below are projects in different programming languages for generating and validating authentication headers.

  • phpRestApiUtils: implementation in PHP
  • RegEx: regular expression useful for validating generated headers