Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

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

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