FRACTTAL API uses HTTP Hawk as its authentication scheme, which uses the Message Authentication Code (MAC) which is a mechanism for making authenticated HTTP requests through partial cryptographic verification.
Like the HTTP Basic authentication scheme, in the Hawk scheme the client credentials include an identifier and a key. However, in contrast to the HTTP Basic scheme, the key is never included in the authentication request but is used to calculate the value of the MAC field that is included in the request.
The data required by the customer to connect to FRACTTAL API are the unique ID and a SECRET KEY, which are assigned only once to the company. For security reasons, the unique ID and the SECRET KEY are known only to FRACTTAL SPA and the registered company.
FRACTTAL API only supports the sha256 hash algorithm for both HMAC and payload validation.
Request Header
The Authorization request header consists of fields in the format "key": "value", as shown in the following table:
| Field | Required | Description |
|---|---|---|
id | Yes | Unique ID that identifies the registered company. |
ts | Yes | Date with seconds in timestamp in "Unix epoch" format. This must be within 60 seconds of the FRACTTAL API server date. If there is too much difference an error will be returned. |
nonce | Yes | A random string. It must be unique for each request made. |
mac | Yes | The MAC must be encoded in base-64 of the normalized string (see STRING STANDARDIZATION). |
ext | Optional | Application-specific data. |
hash | Optional | Base-64 code of the request payload. |
app | Optional | Base-64 code of the request's payload. |
dig | Optional | The application delegate. |
How is the MAC calculated?
The MAC of the request is calculated using the "hmac-sha-256" algorithm and the secret key on the normalized string. This result is encoded in base-64. Example of the mac = "/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk=".
Example Request Header
Authorization: Hawk id=”qUtGgNr7YTURDensMvGa1g”,
mac=”/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk=”,
ts=”1368116073″, nonce=”Wiok05gO”, app=”2HjRl8gWz5shfSXrwblRnw”
Response Header
Every response has a Server-Authorization header in the header. The header is in the same format as the request, but does not 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 specific values of the response and the header 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 standardization
The normalized (ordered) string forms the value of the HMAC digest that of the mac field. It is based on the details of the request and is composed of values in the "field" structure: "value" and a line break. Some of these fields are also included in the request header.
| Field | Description |
|---|---|
| Header | Specifies the mac type, one of hawk.1.header(request header),hawk.1.response(response header). |
| ts | Date with seconds in timestamp in "Unix epoch" format. |
| nonce | A randomly generated string. |
| Method | El método HTTP del request. Todas las letras deben estar en mayúscula. |
| Request URI | Es el HTTP request URI. |
| Host | Host donde se enviará el request, se le omite el puerto. |
| Port | The port through which the connection will be made. Normally it is port 443. |
| hash | The port through which the connection will be made. Normally it is port 443. |
| ext | Application specific data. Blank if not present |
| app | The id of the application. Omit it if it does not exist. |
| dlg | The delegate of the application. Omit it unless the app field exists. If the app field exists, set it to blank. |
Note: Remember that there must be a line break between each field.
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
¶
Payload validation
The payload is the body of the request/response. Our clients optionally have the possibility to validate the payload, this is not mandatory, however it is highly recommended to do so when possible. This is not mandatory, however it is highly recommended to do so when possible. When the authentication of the Header is generated, the client calculates a hash to the payload using the algorithm you have specified (sha-256). The hash is calculated on the following concatenated values (each value followed by the line break character):
- Hawk.1.payload
- The content type in lowercase without any other parameter (example: application/json)
- The payload of the request 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) obtained as a result is:
Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=
Therefore, the customer's request should look as follows:
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 ±60 seconds range of the server, the server will return the code, with the WWW-Authenticate header containing the server's date and time in timestamp, which must be adjusted according to the response. The calculation of this field must be adjusted according to the date and time of the response. Included in the response is the tsm field which is an HMAC of a header and date which is followed by a new line to prevent malicious attacks.
Example:
WWW-wAuthenticate: Hak ts=”1365741469″,
tsm=”b4Qqhz8OUBq21saghHLV1ktwlXE72T1xtTEZkSlWizA=”,
error=”Stale timestamp”
Note: To learn more about the Hawk authentication scheme, please visit the following page. Official Hawk documentation