Autenticación

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 ID único que identifica la empresa registrada.
ts 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 Un string random. Que debe ser único por cada petición realizada (request).
mac 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.
dlg Opcional El delegado de la aplicación.

Como 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 )

Arriba

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