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
Authorization: Hawk id=”qUtGgNr7YTURDensMvGa1g”,
mac=”/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk=”,
ts=”1368116073″, nonce=”Wiok05gO”, app=”2HjRl8gWz5shfSXrwblRnw”
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.
Example:
Server-Authorization: Hawk
mac=”YWojrFVgIjgd+RiPacnDwRcL8VtvcMEzahVfOpoLxoA=”,
hash=”yAF3A3y3uzLvNT2m/nVwsifn1+joCqu0uNWZS8RSv6Y=”
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
Example with the app field:
hawk.1.header
1353832234
j4h3g2
POST
/inventories/12345
app.fracttal.com
443
¶
¶
1234
¶
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
Example
Payload: Thank you for flying Hawk
Content Type: text/plain.
The construction of the payload is as follows:
hawk.1.payload
text/plain
Thank you for flying Hawk
The hash value(sha-256) that is obtained as a result is:
Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=
Therefore, the client request must be as follow:
hawk.1.header
1353832234
j4h3g2
POST
/inventories/1234
app.fracttal.com
443
Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=
¶
some-app-ext-data
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.
Example:
WWW-wAuthenticate: Hak ts=”1365741469″,
tsm=”b4Qqhz8OUBq21saghHLV1ktwlXE72T1xtTEZkSlWizA=”,
error=”Stale timestamp”
Note: To learn more about the Hawk authentication scheme, visit the following page. Documentación oficial Hawk