Background
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.
How it is used in APIX ?
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.
- User web password. This is used whenever customer is directly accessing account information. Usually this involves customer to manually enter the password.
- Transfer password. This is used when customer is sending messages and for APIs supporting message sending. This is used be customers software to automatically connect Incus system.
Currently Incus is using SHA-256 for digest calculation. This is however bound to change as weaknesses are found in the ciphers.
Example (RetrieveTransferID)
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
| Code Block |
|---|
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:
| Code Block |
|---|
2332748-7+y-tunnus+juha.litola@vendep.com+20100621103800+3693d93220b28a03d3c70bdc1cab2b890c65a2e6baff3d4a2a651b713c161c5c |
We will then run SHA-256 algorithm for the string to get the final digest.
| Code Block |
|---|
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
| Code Block |
|---|
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.
Example (SendInvoiceZip)
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:
| Code Block |
|---|
Economix+1.0+18984859858+20100621103800+8874926028 |
We will then run SHA-256 algorithm for the string to get the digest.
| Code Block |
|---|
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
| Code Block |
|---|
SHA-256:4dcec9922f9729311b53363cb313425d8b31a71c5983ea2204f4bfcf7ac74d23 |
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.
| Code Block |
|---|
PUT https://test-api.apix.fi/invoices?soft=Economix&ver=1.0&TraID=18984859858&t=20100621103800&d=SHA-256:4dcec9922f9729311b53363cb313425d8b31a71c5983ea2204f4bfcf7ac74d23 |