AdminGuide:RestAPI

Return to AdminGuide

General description

KalliopePBX offers a set of REST APIs that can be invoked by external systems to execute device (e.g. extension creation, backup generation and download, etc.) or consultation actions (e.g. CDR download, 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).

La procedura di calcolo della digestPassword richiede, oltre alla password dell'utente, una ulteriore stringa denominata salt, univoca per tenant. Il salt può essere ottenuto dal KalliopePBX mediante una API REST apposita, invocabile in modo anonimo (senza autenticazione).

La formula di calcolo della digestPassword è (i caratteri { e } fanno parte della stringa di cui si esegue lo sha256 e devono essere inseriti):

 digestPassword = sha256(password{<salt>})

Ad esempio, supponendo che la password dell'utente sia "admin" e il salt sia uguale a "b5a8fdcf2f8d5acdad33c4a072a97d7a", la digestPassword risultante è:

 digestPassword = sha256(admin{b5a8fdcf2f8d5acdad33c4a072a97d7a}) = dd7b0be7fa37d6cbaf0b842bf7532f229cb79ab8d54d509c2aa7eea27a53cd5e

Come esempio, con i dati seguenti:

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

si ottiene:

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

che vale +PJg7Tb3v98XnL6iJVv+v5hwhYjdzQ2tIWxvJB2cE40=.

NOTA: la funzione sha256_binary(..) indica la funzione sha256(..) che restituisce l'output in formato binario e non in formato esadecimale.

La stringa completa risultante da inserire all'interno dell'header X-authenticate è quindi quella indicata all'inizio del paragrafo e riportata di seguito:

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

Elenco API

La lista dettagliata e aggiornata delle API è consultabile tramite l'interfaccia web di KalliopePBX all'indirizzo http://KALLIOPE_IP_ADDRESS/api/doc