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)

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. Normalmente 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

¿Encontró su respuesta?