FRACTTAL API utiliza como esquema de autenticación HTTP Hawk, el cual utiliza el Código de Autenticación de Mensaje (MAC, por sus siglas en inglés Message Authentication Code) que es un mecanismo para hacer peticiones HTTP autenticadas mediante verificación criptográfica parcial.
Al igual que el esquema de autenticación HTTP Básico, en el esquema Hawk las credenciales del cliente incluyen un identificador y una clave. Sin embargo en contraste con el esquema HTTP Básico la llave nunca es incluida en la autenticación del request pero sí es usada para calcular el valor del campo MAC que está incluido en el request.
Los datos que necesita el cliente para conectarse con FRACTTAL API son el ID único y una CLAVE SECRETA los cuales son asignados una sola vez a la empresa.
Por motivos de seguridad el ID único y la CLAVE SECRETA sólo son conocidos por FRACTTAL SPA y la empresa registrada.
FRACTTAL API sólo soporta el algoritmo hash sha256, tanto para HMAC y la validación payload.
Request Header (Encabezado de la petición)
El encabezado del request Authorization consiste en campos en el formato “clave”:”valor”, como se muestra en la siguiente tabla:
| Campo | Requerido | Descripción |
|---|---|---|
id | Si | ID único que identifica la empresa registrada. |
ts | Si | Fecha con segundos en timestamp en formato “Unix epoch”. Esta debe de estar entre 60 segundos de la fecha del servidor de FRACTTAL API. Si hay demasiada diferencia se devolverá un error. |
nonce | Si | Un string random. Que debe ser único por cada petición realizada (request). |
mac | Si | El MAC debe ser codificado en base-64 del string normalizado (ver NORMALIZACIÓN DEL STRING). |
ext | Opcional | Datos específicos de la aplicación. |
hash | Opcional | Código en base-64 del request payload. |
app | Opcional | El id de la aplicación. Requerido si la petición(request) es generado desde una aplicación. |
dig | Opcional | El delegado de la aplicación. |
¿Cómo se calcula el mac?
El MAC del request es calculado usando el algoritmo “hmac-sha-256” y la clave secreta sobre el string normalizado. Este resultado es codificado en base-64.
Ejemplo del mac = “/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk=”
Ejemplo del Request Header
Authorization: Hawk id=”qUtGgNr7YTURDensMvGa1g”,
mac=”/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk=”,
ts=”1368116073″, nonce=”Wiok05gO”, app=”2HjRl8gWz5shfSXrwblRnw”
Response Header (Encabezado de la respuesta)
Todas los response tiene en el encabezado un encabezado de autorización del servidor (Server-Authorization). El encabezado está en el mismo formato del request, pero no tiene tantos datos. El campo mac, siempre se incluye y se basa en los datos que fueron enviados en el request, el campo hash y ext se reemplazan por valores específicos de la respuesta y la cadena de texto del header es diferente.
El hash es opcional y es un código en base-64 del request-payload response.
Ejemplo:
Server-Authorization: Hawk
mac=”YWojrFVgIjgd+RiPacnDwRcL8VtvcMEzahVfOpoLxoA=”,
hash=”yAF3A3y3uzLvNT2m/nVwsifn1+joCqu0uNWZS8RSv6Y=”
Normalización del string
El string normalizado (ordenado) forma el valor del HMAC digest que del campo mac. Está basado en los detalles del request y se compone de valores en la estructura “campo”: “valor” y un salto de línea. Algunos de estos campos también están incluidos en el encabezado del request.
| Campo | Descripción |
|---|---|
| Header | Especifica el tipo de mac, una de hawk.1.header(request header),hawk.1.response(response header). |
| ts | Fecha con segundos en timestamp en formato “Unix epoch”. |
| nonce | Un string generado en random. |
| 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 | El puerto mediante el cual se hará la conexión. Nomalmente es el puerto 443. |
| hash | Es el request-payload en base-64. Blanco si no existe. |
| ext | Datos específicos de la aplicación. Blanco si no existe |
| app | El id de la aplicación. Omitirlo si no existe |
| dlg | El delegado de la aplicación. Omitirlo a menos de que el campo app exista. Si el campo app existe, ponerlo en blanco |
Nota: Recuerde que entre cada campo debe haber un salto de línea.
Construcción
Header
ts
nonce
Method Request
URI
Host
Port
hash
ext
app
dlg
Ejemplo con el campo app:
hawk.1.header
1353832234
j4h3g2
POST
/inventories/12345
app.fracttal.com
443
¶
¶
1234
¶
Validación del payload
El payload es el cuerpo del request/response. Nuestros clientes opcionalmente tiene la posibilidad de validar el payload. Esto no es obligatorio, sin embargo es altamente recomendado hacerlo cuando sea posible.
Cuando se genera la autenticación del Header, el cliente calcula un hash al payload usando el algoritmo has especificado (sha-256). El hash es calculado sobre los siguientes valores concatenados (cada valor seguido del carácter salto de línea):
- Hawk.1.payload
- El tipo de contenido in minúscula sin ningún otro parámetro (ejemplo: application/json)
- El payload del request antes que cualquier otra codificación de contenido
Ejemplo:
Payload: Thank you for flying Hawk
Content Type: text/plain.
La construcción del payload es la siguiente:
hawk.1.payload
text/plain
Thank you for flying Hawk
El valor hash(sha-256) que se obtiene como resultado es:
Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=
Por tanto el request del cliente debe quedar de la siguiente manera:
hawk.1.header
1353832234
j4h3g2
POST
/inventories/1234
app.fracttal.com
443
Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=
¶
some-app-ext-data
TS (Timestamp) fuera del rango
Cuando el ts del cliente está fuera del rango de ±60 segundos del servidor, este devolverá el código, con el encabezado del WWW-Authenticate que contiene la fecha y hora del servidor en timestamp. Se debe ajustar el cálculo de este campo de acuerdo con la fecha y hora del response.
En la respuesta está incluido el campo tsm que es un HMAC de un encabezado y fecha la cual es seguida por una nueva línea para evitar ataques maliciosos.
Ejemplo:
WWW-wAuthenticate: Hak ts=”1365741469″,
tsm=”b4Qqhz8OUBq21saghHLV1ktwlXE72T1xtTEZkSlWizA=”,
error=”Stale timestamp”
Nota: Para conocer más a cerca del esquema de autenticación Hawk, visite la siguiente página. Documentación oficial Hawk