Incus platform provides APIs that can be used to access and modify information in the Incus system. Because most of the information is restricted to single company there needs to be a way to restrict access on information also on APIs. Method chosen is to use digest calculation with shared secret.
Whenever there is need to verify the originator of the request, originator needs to provide digest calculated from request parameters and shared secret. Secret is never actually send in the request, it is only used in the digest calculations.
There are two different passwords which are used as shared secrets depending on the API.
Currently Incus is using SHA-256 for digest calculation. This is however bound to change as weaknesses are found in the ciphers.
As an example here is example of digest calculation for RetrieveTransferID API. Full API documentation can be found in Rest API::RetrieveTransferID.
We are trying to retrieve customers transfer credentials using the Users web password. For the request we will need to populate following parameters:
| Parameter | Example value | Description |
|---|---|---|
| id | 2332748-7 | Company's identifier (y-tunnus) |
| idq | y-tunnus |
Qualifier for the company identifier |
| uid | juha.litola@vendep.com | User ID for the user requesting the information |
| ts | 20100621103800 | Time stamp of the request. This needs to be recent as old requests are not accepted |
| d | calculated | Digest calculated for the request. |
We can now calculate digest using the parameters above and users web password ("badpassword").
The digest for the password is calculated first. This can be done e.g. with command line tool shasum.
NOTE: Double hashing is used only with user's web password - not with for example with TransferKey
incus:~> echo -n badpassword | shasum -a 256 -p
3693d93220b28a03d3c70bdc1cab2b890c65a2e6baff3d4a2a651b713c161c5c ?-We will then concatenate all those parameters to one string using "+" character as separator. We will also add password-hash in similar manner. Resulting string is as follows:
2332748-7+y-tunnus+juha.litola@vendep.com+20100621103800+3693d93220b28a03d3c70bdc1cab2b890c65a2e6baff3d4a2a651b713c161c5cWe will then run SHA-256 algorithm for the string to get the final digest.
intra:~> echo -n "2332748-7+y-tunnus+juha.litola@vendep.com+20100621103800+3693d93220b28a03d3c70bdc1cab2b890c65a2e6baff3d4a2a651b713c161c5c" | shasum -a 256 -p
e8eaaaad722d3a6884b7408f911a03b255ac54d668737d2463cde81f085e6295 ?- We will then prepend the name of the cipher and ':' to get the actual digest used in the request
SHA-256:e8eaaaad722d3a6884b7408f911a03b255ac54d668737d2463cde81f085e6295 This can be used in the request as 'd'-parameters. Receiving side will redo the digest calculation on the server side, and if the digests match we have verified the requesting party.
As an example here is digest calculation for SendInvoiceZip API. Full API documentation can be found in Rest API::SendInvoiceZip.
We are trying to send ZIP containing invoices using the transfer credentials gotten by the RetrieveTransferID. For the request we will need to populate following parameters:
| Parameter | Example value | Description |
|---|---|---|
| soft | Economix | Software interface name (agreed with Apix) |
| ver | 1.0 | Software interface version (agreed with Apix) |
| TraID | 18984859858 | TransferID gotten through RetrieveTransferID |
| t | 20100621103800 | Time stamp of the request. This needs to be recent as old requests are not accepted |
| d | calculated | Digest calculated for the request. |
We can now calculate digest using the parameters above and the TransferKey retieved by RetrieveTransferID ("8874926028").
We will then concatenate all those parameters to one string using "+" character as separator. Resulting string is as follows:
Economix+1.0+18984859858+20100621103800+8874926028We will then run SHA-256 algorithm for the string to get the digest.
intra:~> echo -n "Economix+1.0+18984859858+20100621103800+8874926028" | shasum -a 256 -p
4dcec9922f9729311b53363cb313425d8b31a71c5983ea2204f4bfcf7ac74d23 ?-We will then prepend the name of the cipher and ':' to get the actual digest used in the request
SHA-256:4dcec9922f9729311b53363cb313425d8b31a71c5983ea2204f4bfcf7ac74d23This can be used in the request as 'd'-parameters. Receiving side will redo the digest calculation on the server side, and if the digests match we have verified the requesting party.
PUT https://test-api.apix.fi/invoices?soft=Economix&ver=1.0&TraID=18984859858&t=20100621103800&d=SHA-256:4dcec9922f9729311b53363cb313425d8b31a71c5983ea2204f4bfcf7ac74d23