FRACTTAL API uses HTTP Hawk as authentication scheme, which uses the Message Authentication Code (MAC, stands for Message Authentication Code) which is a mechanism for making HTTP requests authenticated by partial cryptographic verification.


Like the HTTP Basic authenticated scheme, in the Hawk scheme the client’s credentials includes an identifier and a key. However in contrast with the Basic HTTP scheme the key is never included in the authentication but is used to calculate the value of the MAC field which is included in the request.


The data that the client needs to connect with FRACTTAL API are the unique ID and a SECRET PASSWORD which are assigned only once to the company.
For security reasons the unique ID and the SECRET PASSWORD are only known by FRACTTAL SPA and the registered company.
FRACTTAL API only supports the sha256 hash algorithm, both for HMAC and the payload validation.

Request Header

Request header of the request Authorization consist of fields in the format “key”:”value”, as shown in the following table:

Field

Required

Description

id

Yes

Unique ID which indentifies the registered company.

ts

Yes

Date with seconds in timestamp in “Unix epoch” format. This must be between ±60 seconds of the date of the FRACTTAL API server. If there is too much difference and error will be returned.

nonce

Yes

A random string. Which must be unique for each request made (request).

mac

Yes

The MAC must be encoded in base-64 of the normalized string (see STRING NORMALIZATION).

ext

Optional

Specific data of the application.

hash

Optional

Code in base-64 of the request payload.

app

Optional

The application id. Required if the request is generated from an application.

dlg

Optional

The application delegate.

How to calculate the mac

The MAC of the request is calculated using the “hmac-sha-256” algorithm and the secret key over the normalized string. This result is encoded in base-64.
MAC Example = “/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk=”

Request Header Example

Forma

Authorization: Hawk id=”qUtGgNr7YTURDensMvGa1g”,
mac=”/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk=”,
ts=”1368116073″, nonce=”Wiok05gO”, app=”2HjRl8gWz5shfSXrwblRnw”

Forma

Response Header

All the responses have the header a server authorization header (Server-Authorization). The header is in the same format as the request, but it doesn’t have as much data. The mac field is always included and is based on the data that was sent in the request, the hash and ext field are replaced by response specific values, and the header text string is different.
The hash is optional and is a base-64 code of the request-payload response.

Forma

Example:

Server-Authorization: Hawk
mac=”YWojrFVgIjgd+RiPacnDwRcL8VtvcMEzahVfOpoLxoA=”,
hash=”yAF3A3y3uzLvNT2m/nVwsifn1+joCqu0uNWZS8RSv6Y=”

Forma

String normalization

The normalized (ordered) string form the value of the HMAC digest of the mac field. It is based on the details of the request and is made up of values in the structure “field”: “value” and a line break. Some of these fields are also included in the request heading.

Field

Description

Header

Specifies the type of mac, one of hawk.1.header(request header),hawk.1.response(response header).

ts

Date with seconds in timestamp in “Unix epoch” format.

nonce

A string generated in random.

Method

The HTTP method of the request. All letters must be capitalized.

Request URI

Is the HTTP request URI.

Host

Host where the request will be sent, the port is omitted.

Port

The port through which the connection will be made. Usually it is port 443.

hash

Is the request-payload in base-64. White if none exists.

ext

Specific data of the application. White if none exists

app

The application id. Skip it if it doesn’t exist

dlg

The application delegate. Skip it unless the app field exist. If the app field exist, make it white

Note: Remember that between each field must be a line break.

Construction


Header
ts
nonce
Method Request
URI
Host
Port
hash
ext
app
dlg

Forma

Example with the app field:


hawk.1.header
1353832234
j4h3g2
POST
/inventories/12345
app.fracttal.com
443


1234

Forma

Validation of the payload

The payload is the body of the request/response. Our clients optionally have the possibility to validate the payload. This is not required, however it is highly recommended to do so when possible.
When Header authentication is generated, the client calculates a hash to the payload using the specified hash algorithm (sha-256). The hash is calculated over the following concatenate values (each value followed by the new line character):

  • hawk.1.payload

  • The content type in lowercase without any other parameters (example: application/json)

  • The request payload before any other content encoding

Forma

Example

Payload: Thank you for flying Hawk
Content Type: text/plain.

Forma

The construction of the payload is as follows:

Forma

hawk.1.payload
text/plain

Thank you for flying Hawk

Forma

The hash value(sha-256) that is obtained as a result is:

Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=

Therefore, the client request must be as follow:

Forma

hawk.1.header
1353832234
j4h3g2
POST
/inventories/1234
app.fracttal.com
443
Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=

some-app-ext-data

Forma

TS (Timestamp) out of range

When the client’s ts is outside the server’s ±60 seconds range, the server will return the code, with the WWW-Authenticate header that contains the date and hour of the server in timestamp. The calculation of this field must be adjusted according to the date and hour of the response.
Included in the response is the tsm field which is an HMAC of a header and which is followed by a newline to prevent malicious attacks.

Forma

Example:

WWW-wAuthenticate: Hak ts=”1365741469″,
tsm=”b4Qqhz8OUBq21saghHLV1ktwlXE72T1xtTEZkSlWizA=”,
error=”Stale timestamp”

Forma

Note: To learn more about the Hawk authentication scheme, visit the following page. Documentación oficial Hawk

Did this answer your question?