Skip to end of metadata
Go to start of metadata

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.

  1. User web password. This is used whenever customer is directly accessing account information. Usually this involves customer to manually enter the password.
  2. 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

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:

We will then run SHA-256 algorithm for the string to get the final digest.

We will then prepend the name of the cipher and ':' to get the actual digest used in the request

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:

We will then run SHA-256 algorithm for the string to get the digest.

We will then prepend the name of the cipher and ':' to get the actual digest used in the request

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.

  • No labels