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 | Sí | ID único que identifica a empresa registrada. |
| ts | Sí | 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.
O 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”