*Authentication

Open

Configuration Article | CA-20220907-TP-01 VDG Sense | API | Usage Open

Open

The HTTP interface can be operated by sending HTTP/1.1 compliant requests and retrieving their responses. Requests consist of a single file request, with optionally HTTP/GET parameters and can contain optional HTTP/POST XML data. All responses sent by the HTTP interface will contain XML HTTP/POST data. The following three files are relevant to user authentication, where [server] is the reachable address of manager:

• http://[server]/info

• http://[server]/webservice

• http://[server]/command

In addition, some request and responses contain a UTC timestamp. These timestamps are formatted as follows: yyyy-mm-dd hh:mm:ss. For example, 2013-09-03 19:05:55 represents 5 minutes and 55 seconds past 7 p.m. on the 3rd of September 2013 in UTC time.

Retrieve server-side information

API version 2.6.1 and above contain the /info request file. When called, this request will return the following response:

For example, a /info request made on the date and time above on version 2.6.1 will return the following response in its HTTP/POST data

Take note that earlier versions of the API will return a 404 NOT FOUND error when requesting /info. Use this to work out that the 2.6.1 features are not available. A /info request does not require authentication.

Digest authentication

The digest authentication method uses a so-called ‘nonce’ to identify the type of client that connects. An example message of the digest authentication method is:

In this message, the nonce identifies the client type. These nonces will be given to API integrators based on the type of connection they will use. The timestamp is the current time in UTC. The digest is a digital signature to verify the message contents. Note that there is no password field. The password is used when the digest string is created and this string contains enough information for the API to verify that the sender of the message knows the correct password.

Digest calculation

This section describes how to calculate the digest string. First, some input values need to be determined: username, password, current time and the nonce.

USR: user
PWD: password
TIME: 2013-09-04 08:38:43
NONCE: AR5chsWVZagPfMpB

With the time, username and password, the following string can be formed:

MD5(TIME)+USR+SHA1(SHA1(PWD)) = a268f1c72dea7d9d677e365d1285fd78user2470c0c06dee42fd1618bb99005adca2ec9d1e19

In other words, this means that the resulting string is a concatenation of an MD5 hash of the time string, the username and a double SHA1 hash of the password. Note that the input for the second SHA1 calculation uses the binary result of the first one, not its string representation. This string and the nonce are then used to create the final message authentication code with HMAC-SHA1. The string should be used as key and the nonce should be used as data in the HMAC-SHA1 function.

DATA = AR5chsWVZagPfMpB
KEY = a268f1c72dea7d9d677e365d1285fd78user2470c0c06dee42fd1618bb99005adca2ec9d1e19
HMAC-SHA1 (DATA, KEY) = 804a2cba7610088a6c7975777e6349daefadcdf9

The resulting string can be used as the digest field in the authentication message. The authentication message should be sent to the /webservice request file.

PHP example of digest calculation

Response

If the authentication was successful, the system will respond with a session key. Include this in further requests which require authentication. The following is an example of a successful login response.

In case of error, the system will respond with an error string as seen below.

Basic authentication

Servers using an API version prior to 2.6.1 (which does not support /info) can be reached by using basic authentication. Mobile notifications are not supported using this version. A basic authentication request is also sent to the /webservice file and looks as follows:

In case of success, the webservice will return a session key, which can be used for other methods. In case of error, the webservice will return an error string.

Logging out

Both digest and basic authentication methods use the same logout request. A logout request is sent to the /webservice file and looks as follows:

If the user has been logged out successfully, the webservice will return OK. An error string is returned otherwise.