FRACTTAL API

Autenticação

A API FRACTTAL usa o esquema de autenticação HTTP Hawk , que usa o Message Authentication Code(MAC ), que é um mecanismo para fazer solicitações HTTP autenticadas por verificação criptográfica parcial.

Como o esquema de autenticação HTTP Básico, no esquema Hawk , as credenciais do cliente incluem um identificador e uma chave. No entanto, em contraste com o esquema HTTP básico, a chave nunca é incluída na autenticação da solicitação, mas é usada para calcular o valor do campo MAC incluído na solicitação.

Os dados que o cliente precisa para se conectar à API FRACTTAL são o ID exclusivo e uma CHAVE SECRETA que são atribuídos apenas uma vez à empresa.

Por razões de segurança, a identificação exclusiva e a chave secreta são conhecidas apenas pela FRACTTAL SPA e pela empresa registrada.

A API FRACTTAL suporta apenas o algoritmo de hash sha256, tanto para validação de HMAC  quanto de carga útil.

Cabeçalho da Solicitação (Cabeçalho da solicitação)

O cabeçalho de autorização da solicitação consiste em campos no formato “chave”: “valor”, conforme mostrado na tabela a seguir:

Campo Obrigatório Descrição
id ID único que identifica a empresa registrada.
ts Data com segundos em timestamp no formato “Unix epoch”. Esta deve estar entre ±60 segundos da data do servidor FRACTTAL API. Se houver muita diferença, um erro será retornado.
nonce Sim Um string random. Que deve ser único por cada petição realizada (request).
mac Sim o MAC deve ser codificado na base-64 da string normalizado (ver NORMALIZAÇÃO DO STRING).
ext Opcional Dados especificados da solicitação.
hash Opcional Código na base-64 do request payload.
app Opcional O id da solicitação. Obrigatório se a petição(request) é gerada a partir de uma solicitação.
dlg Opcional O delegado da aplicação.

Como se calcula o MAC

O MAC do pedido é calculado usando o algoritmo “hmac-sha-256” e a chave secreta na string normalizada. Este resultado é codificado em base-64.

Exemplo de mac = ” / uYWR6W5vTbY3WKUAN6fa + 7p1t + 1Yl6hFxKeMLfR6kk =”

Exemplo do cabeçalho da solicitação

Autorização: Hawk id=”qUtGgNr7YTURDensMvGa1g”,
mac=”/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk=”,
ts=”1368116073″, nonce=”Wiok05gO”, app=”2HjRl8gWz5shfSXrwblRnw”

Response Header (Cabeçalho de resposta)

Cada resposta tem um cabeçalho para autorização do servidor (Autorização do Servidor) no cabeçalho. O cabeçalho está no mesmo formato de solicitação, mas não possui tantos dados. O campo MAC , sempre incluído e baseado nos dados que foram enviados na solicitação, o campo hash e ext são substituídos por valores específicos da resposta e a sequência de texto do cabeçalho é diferente.

hash é opcional e é um código base-64 da resposta do pedido-payload.

Exemplo:

Server-Authorization: Hawk
mac=”YWojrFVgIjgd+RiPacnDwRcL8VtvcMEzahVfOpoLxoA=”,
hash=”yAF3A3y3uzLvNT2m/nVwsifn1+joCqu0uNWZS8RSv6Y=”

Padronização da string

A cadeia normalizada (ordenada) forma o valor do resumo HMAC que o campo mac. Baseia-se nos detalhes da solicitação e consiste em valores na estrutura “field”: “value” e uma quebra de linha. Alguns desses campos também estão incluídos no cabeçalho da solicitação..

Campo Descrição
Header Especifica o tipo de MAC, uma de hawk.1.header(request header),hawk.1.response(response header).
ts Data com segundos em timestamp no formato “Unix epoch”.
nonce Um string gerado na random.
Method O método HTTP do request. Todas as letras devem estar maiúsculas.
Request URI É o HTTP request URI.
Host Host onde se enviará a request, se emite a porta.
Port A porta pela qual a conexão será feita. Nomally é porto 443.
hash É o request-payload na base-64. Branco se não existe.
ext Dados específicos da aplicação. Branco se não existe
app O id da aplicação. Omiti-lo se não existe
dlg O delegado da aplicação. Omiti-lo a menos que o campo app exista. Se o campo app existe, por ele em branco

Nota: Lembre-se de que deve haver uma quebra de linha entre cada campo.

CONSTRUÇÃO

Header
ts
nonce
Method Request
URI
Host
Port
hash
ext
app
dlg

Exemplo com o campo de solicitações:

hawk.1.header
1353832234
j4h3g2
POST
/inventories/12345
app.fracttal.com
443 


1234

Validação da carga útil

A carga útil é o corpo da solicitação / resposta. Nossos clientes, opcionalmente, têm a possibilidade de validar a carga útil. Isto não é obrigatório, no entanto, é altamente recomendável fazê-lo quando possível.

Quando a autenticação do Header é gerada, o cliente calcula um hash na carga usando o algoritmo que você especificou (sha-256). O hash é calculado nos seguintes valores concatenados (cada valor seguido pelo caractere de quebra de linha):

  • hawk.1.payload
  • O tipo de conteúdo em minúsculas sem nenhum outro parâmetro (exemplo: application / json)
  • A carga útil da solicitação antes de qualquer outro código de conteúdo

Exemplo

Payload: Thank you for flying Hawk
Content Type: text/plain.

A construção da carga útil é a seguinte:

hawk.1.payload
text/plain
Thank you for flying Hawk

O valor de hash (sha-256) obtido como resultado é:

Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=

Portanto, a solicitação do cliente deve ser a seguinte:

hawk.1.header
1353832234
j4h3g2
POST
/inventories/1234
app.fracttal.com
443
Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=

some-app-ext-data

TS (Timestamp) fora de alcance

Quando o cliente estiver fora do intervalo de ± 60 segundos do servidor, ele retornará o código, com o cabeçalho WWW-Authenticate contendo a data e a hora do servidor no registro de data e hora. O cálculo deste campo deve ser ajustado de acordo com a data e hora da resposta.

A resposta inclui o campo TSM , que é um HMAC de cabeçalho e data, seguido de uma nova linha para evitar ataques maliciosos.
Exemplo:

WWW-wAuthenticate: Hak ts=”1365741469″,
tsm=”b4Qqhz8OUBq21saghHLV1ktwlXE72T1xtTEZkSlWizA=”,
error=”Stale timestamp”

Para saber mais sobre o esquema de autenticação do Hawk, visite a seguinte página:
Documentação oficial do Hawk